### Setup Willow CMS Development Environment

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Clones the Willow CMS repository and starts the development environment using Docker. It sets up Nginx, PHP, MySQL, Redis, Mailpit, and phpMyAdmin. An optional Jenkins CI server can also be started.

```bash
git clone git@github.com:matthewdeaves/willow.git
cd willow/
./setup_dev_env.sh
./setup_dev_env.sh --jenkins
```

--------------------------------

### Setup Development Environment in Bash

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Shell commands to set up the development environment, including starting the environment, installing aliases, and running the queue worker, which is essential for AI features.

```bash
# Start development environment
./setup_dev_env.sh

# Install aliases
./setup_dev_aliases.sh

# Start queue worker (essential for AI features)
cake_queue_worker_verbose
```

--------------------------------

### Start Willow CMS Development Environment

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Commands to initiate the Willow CMS development environment using Docker. Includes options for starting with Jenkins.

```bash
# Start development environment
./setup_dev_env.sh

# Start development environment with Jenkins
./setup_dev_env.sh --jenkins
```

--------------------------------

### Continue Willow CMS Environment Setup

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Allows proceeding with the existing setup without modifications. It performs basic health checks, may perform minimal cache operations, and directly starts the development environment. Use when the environment is already configured correctly.

```Shell
# Example command for continuing setup (specific command not provided in text)
# Assuming a script or CLI tool exists for this purpose
./willow continue
```

--------------------------------

### Setup Development Environment and Aliases

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Scripts to set up the development environment and load essential development aliases for testing, code quality, and project management.

```bash
# Start development environment
./setup_dev_env.sh && ./setup_dev_aliases.sh
```

--------------------------------

### Setup Development Environment Aliases

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

This script, `setup_dev_aliases.sh`, configures command-line aliases to simplify common development tasks. It modifies shell configuration files like `.bashrc` or `.zshrc` to make these aliases available. The script guides the user through setup options based on the project's configuration.

```shell
#!/bin/bash

# This script sets up development command aliases for easier access to common tasks.
# If completed successfully, it creates aliases in your shell configuration file (e.g., .bashrc, .zshrc).
# Once pre-requisites are met, it asks you to run one of the following options based on your total project configuration:

echo "Setting up development aliases..."
# Example alias setup (actual implementation would be more complex)
# echo "alias manage='./manage.sh'" >> ~/.bashrc
# echo "alias cake='bin/cake'" >> ~/.bashrc

echo "Development aliases setup complete."
```

--------------------------------

### Install Willow CMS Developer Aliases

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Script to install helpful shell aliases for Willow CMS development, compatible with bash and zsh.

```bash
# Install aliases (supports both bash and zsh)
./setup_dev_aliases.sh
```

--------------------------------

### Manage Docker Services

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Provides commands to manage the Docker containers for the Willow project, including starting, stopping, viewing logs, and cleaning up unused resources.

```bash
# Start all services
docker_up

# Stop all services
docker_down

# View logs
docker_logs

# Clean up
docker_prune
```

--------------------------------

### Example Migration (PHP)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

An example of a CakePHP database migration class that adds a 'user_preferences' table with several columns and a foreign key constraint.

```php
// config/Migrations/20241225000000_AddUserPreferences.php
class AddUserPreferences extends AbstractMigration {
    public function change(): void {
        $table = $this->table('user_preferences');
        $table->addColumn('user_id', 'char', ['limit' => 36])
              ->addColumn('preference_key', 'string')
              ->addColumn('preference_value', 'text', ['null' => true])
              ->addColumn('created', 'datetime')
              ->addColumn('modified', 'datetime')
              ->addForeignKey('user_id', 'users', 'id')
              ->create();
    }
}
```

--------------------------------

### Start Willow CMS Queue Workers

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Commands to start queue workers, which are essential for AI features, image processing, and email sending in Willow CMS. Includes verbose and basic options.

```bash
# Start queue worker (required for AI features, image processing)
docker compose exec willowcms bin/cake queue worker --verbose
# or with alias:
cake_queue_worker_verbose

# Basic queue worker
cake_queue_worker
```

--------------------------------

### Development Alias Setup - setup_dev_aliases.sh

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

A shell script to set up command-line aliases for development, simplifying common tasks.

```bash
#!/bin/bash

alias c='php bin/cake.php'

```

--------------------------------

### Setup Development Aliases (Shell)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

A shell script command used for setting up development aliases, likely for streamlining common development tasks like running tests.

```Shell
./setup_dev_aliases.sh
```

--------------------------------

### Install Willow CMS Development Shell Aliases

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Installs essential shell aliases for improved productivity when working with Willow CMS. These aliases streamline common development tasks and include a pre-push Git hook for automated testing.

```shell
./setup_dev_aliases.sh
```

--------------------------------

### Core Configuration Environment Variables

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Example environment variables for core application settings, including application name, debug mode, default locale, timezone, and database/Redis connection URLs.

```bash
# Application settings
APP_NAME="Willow CMS"
DEBUG=true
APP_ENCODING="UTF-8"
APP_DEFAULT_LOCALE="en_US"
APP_DEFAULT_TIMEZONE="UTC"

# Database
DATABASE_URL="mysql://root:password@mysql:3306/willowcms?encoding=utf8mb4"

# Redis (cache and queue)
REDIS_URL="redis://redis:6379"
```

--------------------------------

### Development Environment Setup - setup_dev_env.sh

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

A shell script to configure and prepare the development environment for the Willow project.

```bash
#!/bin/bash

composer install
php bin/cake.php migrations migrate

```

--------------------------------

### Example Controller Test (PHP)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

An example of a controller test case written for CakePHP using PHPUnit. It demonstrates testing an 'add' action, asserting a successful response, and checking for redirects.

```php
// Example controller test
class ArticlesControllerTest extends AppControllerTestCase {
    public function testAdd(): void {
        $data = [
            'title' => 'Test Article',
            'body' => 'Test content',
            'published' => true
        ];
        
        $this->post('/admin/articles/add', $data);
        $this->assertResponseSuccess();
        $this->assertRedirect(['action' => 'index']);
    }
}
```

--------------------------------

### Queueing AI Jobs in PHP

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Demonstrates how to queue an AI job, specifically ArticleSeoUpdateJob, with article ID and locale data. It also provides an example implementation of the JobInterface for background job execution.

```php
// Queue an AI job
$this->queue->push(ArticleSeoUpdateJob::class, [
    'article_id' => $article->id,
    'locale' => 'en'
]);

// Background job example
class ArticleSeoUpdateJob implements JobInterface {
    public function execute(array $data): void {
        $seoGenerator = new SeoContentGenerator();
        $seoGenerator->generateSeoContent($data['article_id']);
    }
}
```

--------------------------------

### Willow CMS Management Tool

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Command to launch the Willow CMS management tool, providing an interactive menu for common tasks.

```bash
# Management tool (interactive menu for common tasks)
./manage.sh
```

--------------------------------

### Internationalization Configuration

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Configuration example for setting the default locale and supported locales within the application's configuration file.

```php
// config/app.php
'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),
'supportedLocales' => [
    'en_US', 'es_ES', 'fr_FR', 'de_DE', 'zh_CN', 'ja_JP'
    // ... more locales
],
```

--------------------------------

### Clone Willow CMS and Setup Development Environment

Source: https://github.com/garzarobm/willow/blob/main/README.md

This snippet demonstrates how to clone the Willow CMS repository and set up the local development environment using Docker. It requires Git and Docker to be installed on the host machine.

```bash
git clone git@github.com:matthewdeaves/willow.git
cd willow/
./setup_dev_env.sh
```

--------------------------------

### Custom AI Extension Example

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Demonstrates how to extend the base API service to create custom AI functionalities, including defining the API URL and making custom requests.

```php
class CustomAiService extends AbstractApiService {
    protected function getApiUrl(): string {
        return 'https://api.example.com/v1/';
    }
    
    public function customAnalysis(string $content): array {
        return $this->makeRequest('analyze', ['content' => $content]);
    }
}
```

--------------------------------

### Execute CakePHP Commands and Manage Queue Workers

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Provides aliases for executing CakePHP shell commands, starting queue workers in verbose mode, and running database migrations.

```bash
# Execute CakePHP commands
cake_shell

# Start queue worker
cake_queue_worker

# Run migrations
cake_migrate

# Clear all caches
cake_clear_cache
```

--------------------------------

### Launch Management Tool (Bash)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Launches the interactive management tool for WillowCMS, providing a menu-driven interface for various development and maintenance tasks.

```bash
./manage.sh
```

--------------------------------

### CI Pipeline Configuration

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Details of the GitHub Actions CI pipeline, including supported PHP versions, services, testing frameworks, code quality tools, and dependency management.

```yaml
# CI Pipeline (.github/workflows/ci.yml)
- PHP Versions: 8.1, 8.2, 8.3 (comprehensive matrix testing)
- Services: MySQL 8.0+ and Redis server setup
- Tests: PHPUnit with 292+ tests and coverage reporting
- Code Quality: PHPStan (level 5) and PHP CodeSniffer (CakePHP standards)
- Dependencies: Composer validation and security scanning
- Performance: Parallel test execution and optimized Docker builds
- Pre-push Hooks: Local test execution before remote pushes
```

--------------------------------

### Anthropic AI Service Integration

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Examples of using Anthropic AI services for content analysis, SEO generation, and comment moderation. Requires instantiation of specific service classes.

```php
// Generate SEO content
$seoGenerator = new SeoContentGenerator();
$seoContent = $seoGenerator->generate($article->title, $article->body);

// Analyze image
$imageAnalyzer = new ImageAnalyzer();
$analysis = $imageAnalyzer->analyze($imagePath);

// Moderate comment
$commentAnalyzer = new CommentAnalyzer();
$isAppropriate = $commentAnalyzer->analyze($comment->content);
```

--------------------------------

### GalleryHelper and VideoHelper Usage in PHP

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Illustrates the use of GalleryHelper for processing gallery placeholders and VideoHelper for integrating YouTube videos with GDPR compliance within the view layer.

```php
// GalleryHelper - Gallery placeholder processing
$this->Gallery->processGalleryPlaceholders($content);

// VideoHelper - YouTube integration with GDPR compliance
$this->Video->processVideoPlaceholders($content);
```

--------------------------------

### Run Unit Tests (PHPUnit)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands for executing unit tests using PHPUnit. Supports running all tests, specific files or methods, and generating code coverage reports.

```bash
# All tests (292+ comprehensive tests)
phpunit

# Specific test file
phpunit tests/TestCase/Controller/ArticlesControllerTest.php

# Filter specific test methods
phpunit --filter testAdd tests/TestCase/Controller/ArticlesControllerTest.php

# With coverage report (HTML accessible at /coverage/)
phpunit_cov_html

# Text coverage report
phpunit_cov

# Test specific components
phpunit tests/TestCase/Model/Behavior/SlugBehaviorTest.php
phpunit tests/TestCase/Controller/Admin/ImageGalleriesControllerTest.php
phpunit tests/TestCase/Service/Api/Anthropic/
```

--------------------------------

### Troubleshoot Permission Issues

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands to fix file ownership and permissions.

```bash
change_ownership
```

```bash
set_permissions
```

--------------------------------

### Willow CMS Database Migrations and Cache

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Commands for managing database migrations (applying, diffing, snapshotting, rolling back) and clearing the cache in Willow CMS.

```bash
# Run migrations
docker compose exec willowcms bin/cake migrations migrate
# or with alias:
cake_migrate

# Create migration diff (after making schema changes)
docker compose exec willowcms bin/cake bake migration_diff YourMigrationName
# or with alias:
bake_diff YourMigrationName

# Create migration snapshot
bake_snapshot InitialSchema

# Rollback migrations
cake_rollback

# Clear all cache
docker compose exec willowcms bin/cake cache clear_all
# or with alias:
cake_clear_cache
```

--------------------------------

### Willow CMS Plugin-Based Theming Structure (PHP)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Illustrates the directory structure for a Willow CMS plugin, specifically the AdminTheme, highlighting its controller, view, template, and webroot configurations.

```php
plugins/AdminTheme/
├── src/
│   ├── Controller/AppController.php    # Admin base controller
│   ├── View/AppView.php               # Admin view configuration
│   └── Command/Bake/                  # Custom bake templates
├── templates/
│   ├── Admin/                         # Admin CRUD templates
│   ├── element/                       # Reusable elements
│   └── layout/                        # Admin layouts
└── webroot/
    ├── css/                           # Admin stylesheets
    └── js/                            # Admin JavaScript
```

--------------------------------

### ImageGalleriesTable Method in PHP

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Provides an example method from the ImageGalleriesTable class for retrieving gallery information, including options for requiring published status and using cache keys. It supports locale-aware caching and automatic cache invalidation.

```php
// ImageGalleriesTable - Advanced gallery management
public function getGalleryForPlaceholder(
    string $galleryId,
    bool $requirePublished = true,
    ?string $cacheKey = null
): ?object {
    // Locale-aware caching and translation support
    // Automatic cache invalidation on content changes
}
```

--------------------------------

### Willow CMS Project Structure

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

This outlines the directory structure of the Willow CMS project, categorizing core code, plugins, configuration, tests, and other essential components.

```bash
willow/
├── 📁 src/                          # Core application code
│   ├── 🎮 Controller/              # Frontend controllers
│   │   └── Admin/                  # Admin backend controllers
│   ├── 📊 Model/                   # Data models and entities
│   │   ├── Behavior/              # Reusable model behaviors
│   │   ├── Entity/                # Entity classes
│   │   └── Table/                 # Table classes with business logic
│   ├── 🔌 Service/Api/             # AI and external API integrations
│   ├── ⚡ Job/                     # Background job classes
│   ├── 🛠️ Command/                 # CLI command tools
│   ├── 🛡️ Middleware/              # Security and request processing
│   └── 🔧 Utility/                 # Helper and utility classes
├── 🎨 plugins/                     # Plugin-based themes
│   ├── AdminTheme/                # Administrative interface
│   └── DefaultTheme/              # Public website theme
├── ⚙️ config/                      # Configuration files
│   ├── Migrations/                # Database migration files
│   └── schema/                    # Database schema files
├── 🧪 tests/                       # Unit and integration tests
│   ├── TestCase/                  # Test classes
│   └── Fixture/                   # Test data fixtures
├── 🐳 docker/                      # Docker configuration
├── 📁 webroot/                     # Public web assets
└── 🔧 manage.sh                    # Interactive management tool
```

--------------------------------

### Manage Translations Workflow

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands for managing translations, including loading default translations, generating PO files, and auto-translating content.

```bash
# Load default translations
i18n_load

# Generate PO files for all locales
i18n_gen_po

# Auto-translate using AI/Google
i18n_translate
```

--------------------------------

### Investigate Article Translation and SEO (Bash)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

This command helps debug issues related to article translation and SEO generation within WillowCMS. It checks article existence, translation status, system logs, and queue jobs. Examples are provided for specific article slugs.

```bash
# Investigate article translation and SEO issues
docker compose exec willowcms bin/cake investigate_article article-slug-here

# Examples:
docker compose exec willowcms bin/cake investigate_article this-is-a-test-page
docker compose exec willowcms bin/cake investigate_article my-blog-post
```

--------------------------------

### Run Comprehensive Tests and Quality Checks

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Executes unit tests, code sniffer checks, and static analysis to ensure code quality and correctness.

```bash
# Run comprehensive tests and quality checks
phpunit && phpcs_sniff && phpstan_analyse
```

--------------------------------

### Running Tests in Bash

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Command to execute specific unit tests using PHPUnit, following a Test-Driven Development (TDD) approach.

```bash
# Write tests first (TDD approach)
# Run specific tests
phpunit tests/TestCase/Controller/YourModelControllerTest.php
```

--------------------------------

### Troubleshoot Failing Tests

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands to clear the test cache and reset the test database using PHPUnit.

```bash
willowcms_exec rm -rf tmp/cache/models/*
willowcms_exec rm -rf tmp/cache/persistent/*
```

```bash
phpunit tests/TestCase/YourTest.php
```

--------------------------------

### Willow CMS OrderableBehavior (PHP)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Explains the OrderableBehavior in Willow CMS, facilitating drag-and-drop ordering functionality and managing item positions within specified scopes.

```php
// Drag-and-drop ordering functionality with position management
$this->addBehavior('Orderable', [
    'order_field' => 'sort_order',
    'scope' => ['gallery_id'] // Optional: scope ordering within groups
]);

// Automatic position calculation and reordering
$this->moveUp($entity);    // Move item up in order
$this->moveDown($entity);  // Move item down in order
```

--------------------------------

### Run Willow CMS Tests with PHPUnit

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Commands to execute tests using PHPUnit within the Willow CMS Docker environment, including options for specific files, coverage, and filtering.

```bash
# Run all tests
docker compose exec willowcms php vendor/bin/phpunit
# or with alias:
phpunit

# Run specific test file
docker compose exec willowcms php vendor/bin/phpunit tests/TestCase/Controller/UsersControllerTest.php
# or with alias:
phpunit tests/TestCase/Controller/UsersControllerTest.php

# Run tests with coverage (text)
docker compose exec willowcms php vendor/bin/phpunit --coverage-text
# or with alias:
phpunit_cov

# Run tests with coverage (HTML) - accessible at http://localhost:8080/coverage/
docker compose exec willowcms php vendor/bin/phpunit --coverage-html webroot/coverage tests/TestCase/
# or with alias:
phpunit_cov_html

# Filter specific test methods
phpunit --filter testLogin tests/TestCase/Controller/UsersControllerTest.php
```

--------------------------------

### Direct Database Access

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Connects directly to the MySQL database using Docker Compose to execute SQL commands.

```bash
# Direct database access
docker compose exec mysql mysql -u cms_user -ppassword cms
```

--------------------------------

### Key Database Tables

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Lists the primary database tables used in the project, including `articles`, `tags`, `images`, `models_images`, `slugs`, `users`, `comments`, `settings`, `aiprompts`, and `page_views`, highlighting their respective functionalities.

```SQL
articles
tags
images
models_images
slugs
users
comments
settings
aiprompts
page_views
```

--------------------------------

### Run Performance Tests with Queue Worker (Bash)

Source: https://github.com/garzarobm/willow/blob/main/AI_IMPROVEMENTS_IMPLEMENTATION_PLAN.md

Starts the queue worker in the background and then runs performance tests, specifically generating articles. This simulates a production environment for performance evaluation.

```Bash
docker compose exec willowcms bin/cake queue worker &
docker compose exec willowcms bin/cake generate_articles 5

```

--------------------------------

### Generate Code with AdminTheme Templates

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Uses the CakePHP bake command with the AdminTheme to generate models, controllers, and templates for new features.

```bash
# Generate code with AdminTheme templates
bake_diff MyFeature
cake_bake_model MyModel --theme AdminTheme
cake_bake_controller MyModel --theme AdminTheme
cake_bake_template MyModel --theme AdminTheme
```

--------------------------------

### Manage Internationalization (i18n)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands for managing internationalization messages, including extracting messages, generating PO files, and translating content.

```bash
# Manage internationalization
i18n_extract && i18n_gen_po && i18n_translate
```

--------------------------------

### Configure Security Settings

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Sets up security parameters including a unique salt for cryptographic operations and session timeout duration, along with CSRF protection.

```bash
# Security salt (generate unique for each environment)
SECURITY_SALT="your_unique_security_salt_here"

# Session configuration
SESSION_TIMEOUT=3600
CSRF_PROTECTION=true
```

--------------------------------

### QueueableImageBehavior in PHP

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Automates background image processing by queuing jobs like ProcessImageJob and ImageAnalysisJob. It handles thumbnail generation, alt text creation, and metadata extraction.

```php
$this->addBehavior('QueueableImage');

// Automatically queues ProcessImageJob and ImageAnalysisJob
// Handles thumbnail generation, alt text creation, and metadata extraction
```

--------------------------------

### Code Generation Commands in Bash

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Shell commands using `cake_bake` to generate models, controllers, and templates for a new feature, specifying a theme like 'AdminTheme'.

```bash
# Generate model, controller, and templates
cake_bake_model YourModel --theme AdminTheme
cake_bake_controller YourModel --theme AdminTheme
cake_bake_template YourModel --theme AdminTheme
```

--------------------------------

### Access Willow CMS MySQL Database

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Direct commands to access the MySQL database for Willow CMS, including executing queries and describing table structures.

```bash
# Direct MySQL database access
docker compose exec mysql mysql -u cms_user -ppassword cms
# Query examples:
docker compose exec mysql mysql -u cms_user -ppassword cms -e "SELECT * FROM settings WHERE key_name = 'editor';"
docker compose exec mysql mysql -u cms_user -ppassword cms -e "DESCRIBE articles;"
docker compose exec mysql mysql -u cms_user -ppassword cms -e "SELECT id, title, is_published FROM articles LIMIT 5;"
```

--------------------------------

### Generate Code Coverage Reports (PHPUnit)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands to generate code coverage reports using PHPUnit, providing insights into test completeness. Supports both HTML and text formats.

```bash
# HTML coverage report (accessible at /coverage/)
phpunit_cov_html

# Text coverage report
phpunit_cov
```

--------------------------------

### Willow CMS SluggableBehavior (PHP)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Demonstrates the SluggableBehavior in Willow CMS, which enables SEO-friendly URLs with history tracking and automatic redirects for content changes.

```php
// SEO-friendly URLs with history tracking and automatic redirects
$this->addBehavior('Sluggable', [
    'slug' => ['source' => 'title'],
    'history' => true  // Maintains slug history for SEO redirects
]);

// Automatic slug generation and conflict resolution
// Handles URL changes gracefully with 301 redirects
```

--------------------------------

### Configure API Keys and Feature Toggles

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Configures API keys for AI services like Anthropic and Google Translate, and enables/disables features such as AI processing and translation.

```bash
# AI Services
ANTHROPIC_API_KEY="your_api_key_here"
GOOGLE_TRANSLATE_API_KEY="your_google_api_key"

# Feature toggles
AI_ENABLED=true
TRANSLATION_ENABLED=true
```

--------------------------------

### Willow CMS Code Generation (Baking)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Commands using CakePHP's bake functionality to generate models, controllers, and templates, with an option to use the AdminTheme.

```bash
# Bake model/controller/template with AdminTheme
docker compose exec willowcms bin/cake bake model Dogs --theme AdminTheme
docker compose exec willowcms bin/cake bake controller Dogs --theme AdminTheme
docker compose exec willowcms bin/cake bake template Dogs --theme AdminTheme

# Using aliases:
cake_bake_model Dogs --theme AdminTheme
cake_bake_controller Dogs --theme AdminTheme
cake_bake_template Dogs --theme AdminTheme
```

--------------------------------

### File Organization Structure (PHP)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Illustrates the directory structure for the Willow CMS project, following CakePHP conventions. It shows the placement of controllers, models, services, commands, and other core components.

```PHP
src/
├── Application.php                 # Main application class
├── Command/                        # CLI commands
│   ├── CreateUserCommand.php
│   ├── DefaultDataImportCommand.php
│   ├── ResizeImagesCommand.php
│   └── ...
├── Controller/                     # Frontend controllers
│   ├── AppController.php          # Base controller
│   ├── ArticlesController.php
│   ├── UsersController.php
│   └── Admin/                      # Admin controllers
├── Model/
│   ├── Behavior/                   # Reusable behaviors
│   ├── Entity/                     # Entity classes
│   └── Table/                      # Table classes
├── Service/Api/                    # API integrations
│   ├── AbstractApiService.php
│   ├── Anthropic/                  # Anthropic API services
│   └── Google/                     # Google API services
├── Job/                           # Queue job classes
├── Middleware/                    # Custom middleware
└── Utility/                       # Utility classes

```

--------------------------------

### Performance Considerations (PHP)

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Illustrates performance optimization techniques in CakePHP, such as using eager loading to prevent N+1 query problems and implementing caching for frequently accessed data.

```php
// Use eager loading to prevent N+1 queries
$articles = $this->Articles->find()
    ->contain(['Tags', 'Images', 'User'])
    ->where(['published' => true]);

// Implement caching for expensive operations
$result = Cache::remember('articles_popular', function() {
    return $this->Articles->getPopularArticles();
});
```

--------------------------------

### Initialize Willow CMS Development Environment

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

The `setup_dev_env.sh` script initializes the Willow CMS development environment. It handles environment detection, sets up Docker volumes with correct permissions, ensures critical services like MySQL are available, and manages Composer dependencies. It also checks the database state and presents an interactive menu for environment management.

```shell
#!/bin/bash

# Project: /garzarobm/willow
# Content: Development Environment Initialization Process

echo "Initializing Willow CMS development environment..."

# Environment Detection and Setup
# Detects host system (e.g., Apple Silicon Mac) and creates environment files with UID:GID mappings for Docker volume permissions.
# Creates necessary directories like logs/nginx for the web server.
# Example: Creating log directory
# mkdir -p logs/nginx

# Container Status Verification
# Waits for critical services like MySQL to become available on port 3306 using a wait-for-it.sh script.
# Example: Waiting for MySQL
# ./wait-for-it.sh mysql:3306 -t 60

# Dependency Management
# Installs or updates Composer dependencies and executes post-installation hooks, including CakePHP-specific routines.
# Example: Running composer install
# composer install

# Database State Detection
# Checks for the existence of a 'settings' table to determine if the database has been previously initialized.
# If an existing database is detected, it presents the interactive menu with five options.
# Example: Checking for settings table (conceptual)
# if psql -h db -U user -d willow -c '\dt settings' | grep -q '1'; then
#   echo "Database initialized. Presenting interactive menu..."
#   # Display interactive menu options
# else
#   echo "Database not initialized. Running initial setup..."
#   # Run initial migrations and import default data
# fi

echo "Development environment setup script finished."
```

--------------------------------

### PHP Entry Point - index.php

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

The main entry point for the Willow PHP application. It initializes the framework and handles incoming requests.

```php
<?php

use App\Application;

require dirname(__DIR__) . '/vendor/autoload.php';

$app = new Application(dirname(__DIR__));
$app->run();

```

--------------------------------

### Import Default Data (Bash)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Imports default datasets such as AI prompts, email templates, and internationalization data into the WillowCMS. This command is executed within the WillowCMS Docker container.

```bash
docker compose exec willowcms bin/cake default_data_import
```

--------------------------------

### Willow CMS Internationalization (i18n)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Commands for managing internationalization in Willow CMS, including extracting translatable strings, loading default data, running automated translations, and generating PO files.

```bash
# Extract translatable strings from code
docker compose exec willowcms bin/cake i18n extract --paths /var/www/html/src,/var/www/html/plugins,/var/www/html/templates
# or with alias:
i18n_extract

# Load default internationalization data
docker compose exec willowcms bin/cake load_default18n
# or with alias:
i18n_load

# Run automated translations (requires AI API keys)
docker compose exec willowcms bin/cake translate_i18n
# or with alias:
i18n_translate

# Generate PO files for all locales
docker compose exec willowcms bin/cake generate_po_files
```

--------------------------------

### Application Configuration - config/

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Core configuration files for the Willow application, including database settings, application behavior, and routing.

```php
<?php

return [
    'Datasources' => [
        'default' => [
            'className' => 'Cake\Database\Connection',
            'driver' => 'Cake\Database\Driver\Mysql',
            'persistent' => false,
            'host' => 'localhost',
            // ... other database settings
        ]
    ]
];

```

```php
<?php

use Cake\Core\Configure;

Configure::write('App', [
    'name' => 'Willow',
    'base' => false,
    'encoding' => 'UTF-8',
    'paths' => [
        'plugins' => [APP . 'Plugin' . DS],
        'templates' => [ROOT . DS . 'templates' . DS],
        // ... other paths
    ]
]);

```

--------------------------------

### PHPStan Static Analysis

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Run PHPStan for static analysis to identify bugs and enforce coding standards like type declarations and documentation blocks. Can be run directly or via Composer.

```bash
# Run static analysis
phpstan_analyse

# Or via composer
docker compose exec willowcms composer stan
```

--------------------------------

### Google Translate API Usage

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Example of using the Google Translate API to translate an array of strings from a source language to a target language.

```php
// Translate content
$googleApi = new GoogleApiService();
$translations = $googleApi->translateStrings([
    'Hello World',
    'Welcome to Willow CMS'
], 'en', 'es');
```

--------------------------------

### Plugin Structure (PHP)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Details the typical structure for plugins within the Willow CMS project, including theme plugins. It shows the separation of source code, templates, and web assets.

```PHP
plugins/
├── AdminTheme/                    # Admin backend theme
│   ├── src/                       # Plugin controllers and logic
│   ├── templates/                 # Admin templates
│   └── webroot/                   # Admin assets
└── DefaultTheme/                  # Public website theme
    ├── src/                       # Theme controllers
    ├── templates/                 # Public templates
    └── webroot/                   # Public assets

```

--------------------------------

### Content Translation Behavior

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Example of using the 'Translate' behavior in a CakePHP Table to manage translatable fields like title and body, and how to set the locale for retrieval.

```php
// Automatic translation behavior
class ArticlesTable extends Table {
    public function initialize(array $config): void {
        $this->addBehavior('Translate', [
            'fields' => ['title', 'body', 'meta_description']
        ]);
    }
}

// Usage
$article = $this->Articles->get(1);
$article->setLocale('es');
echo $article->title; // Spanish title
```

--------------------------------

### Configure Default Email Transport

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Sets the default URL for the email transport service, typically used for sending emails. This example uses Mailpit for local development.

```shell
EMAIL_TRANSPORT_DEFAULT_URL="smtp://mailpit:1025"
```

--------------------------------

### Willow Project: Test Suite Structure

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

This snippet outlines the structure of the test suite for the Willow project. It includes bootstrap files, database schema, fixtures, test cases, and helper traits.

```php
// tests/bootstrap.php
// tests/schema.sql
// tests/Fixture/
// tests/TestCase/
// tests/Traits/
```

--------------------------------

### Willow Project: Docker Configuration Files

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

This snippet lists the Docker-related configuration files and directories within the Willow project. It includes configurations for GitHub integration, Jenkins CI/CD, MySQL, and the Willow CMS itself.

```json
{
  "docker": {
    "github": "GitHub integration configs",
    "jenkins": "Jenkins CI/CD configs",
    "mysql": "MySQL Docker configs",
    "willowcms": "Willow CMS Docker configs"
  }
}
```

--------------------------------

### Export Data as Defaults (Bash)

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Exports the current data from WillowCMS, including AI prompts, email templates, and i18n data, to be used as default settings for future installations. The alias 'export_data' can also be used.

```bash
# Export current data as defaults
docker compose exec willowcms bin/cake default_data_export
# or with alias:
export_data
```

--------------------------------

### CakePHP Reusable Model Behaviors

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Showcases reusable model behaviors in CakePHP for common functionalities like image association, slug management, ordering, commenting, and queued image processing. Examples include `ImageAssociableBehavior`, `SlugBehavior`, `OrderableBehavior`, `CommentableBehavior`, and `QueueableImageBehavior`.

```PHP
ImageAssociableBehavior
SlugBehavior
OrderableBehavior
CommentableBehavior
QueueableImageBehavior
```

--------------------------------

### Willow CMS Interactive Menu Options

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

This describes the interactive menu options presented during Willow CMS container startup. These options allow users to manage the development environment, including wiping all data, rebuilding containers, updating dependencies, running migrations, and continuing with the current setup.

```text
# Understanding Willow CMS Interactive Menu Options: Rebuilding, Running Migrations, and Continue

# Based on the logs from the Willow CMS GitHub repository and the Docker development environment setup, the interactive menu that appears during container startup provides five critical options for managing your development environment. Here's a comprehensive explanation of what each option does:

# [W]ipe Data - Complete Data Reset
# This option performs a complete data wipe of the development environment. This includes:
# - Database Reset: Drops and recreates the entire database, removing all tables, data, and schema.
# - Volume Cleanup: Clears Docker volumes containing persistent data.
# - Cache Clearing: Removes all CakePHP cache files and temporary data.
# - Fresh Installation: Runs initial migrations and imports default data.
# Use this when you need to start completely fresh or when your database has become corrupted.

# re[B]uild - Container Reconstruction
# The rebuild option performs a complete Docker environment reconstruction:
# - Image Rebuilding: Rebuilds all Docker images from their Dockerfiles, incorporating any changes to the base configuration.
# - Container Recreation: Destroys existing containers and creates new ones.
# - Dependency Updates: Downloads and installs the latest versions of system dependencies.
# - Configuration Refresh: Applies any changes made to Docker configuration files.
# This is essential when you've modified Dockerfiles, updated base images, or need to incorporate system-level changes.
```

--------------------------------

### CakePHP Queue Worker Commands

Source: https://github.com/garzarobm/willow/blob/main/dev_aliases.txt

Aliases for starting the CakePHP queue worker. 'cake_queue_worker' starts the worker, and 'cake_queue_worker_verbose' starts it with verbose output.

```bash
alias cake_queue_worker='willowcms_exec bin/cake queue worker'
```

```bash
alias cake_queue_worker_verbose='willowcms_exec bin/cake queue worker --verbose'
```

--------------------------------

### Create AI Metrics Database Migration (Bash)

Source: https://github.com/garzarobm/willow/blob/main/AI_IMPROVEMENTS_IMPLEMENTATION_PLAN.md

Commands to create and run a new database migration for AI metrics using CakePHP's bake command within a Docker environment.

```bash
docker compose exec willowcms bin/cake bake migration CreateAiMetrics
docker compose exec willowcms bin/cake migrations migrate
```

--------------------------------

### Start Willow CMS Queue Workers

Source: https://github.com/garzarobm/willow/blob/main/README.md

Starts the background queue worker process, which is essential for AI features, image handling, and other heavy operations in Willow CMS. This command can be run with verbose output for debugging.

```bash
cake_queue_worker_verbose
# or
docker compose exec willowcms bin/cake queue worker --verbose
```

--------------------------------

### Install Developer Aliases for Willow CMS

Source: https://github.com/garzarobm/willow/blob/main/README.md

Installs shell aliases to simplify common development tasks within the Willow CMS project. These aliases provide shortcuts for running queue workers, tests, code quality checks, and database migrations.

```bash
./setup_dev_aliases.sh
```

--------------------------------

### Create Settings Migration (Bash)

Source: https://github.com/garzarobm/willow/blob/main/AI_IMPROVEMENTS_IMPLEMENTATION_PLAN.md

Bash commands to generate and run a CakePHP database migration for inserting AI metrics settings. This includes creating the migration file and then applying it to the database.

```bash
# Create settings migration
docker compose exec willowcms bin/cake bake migration InsertAiMetricsSettings

# Run the migration after editing
docker compose exec willowcms bin/cake migrations migrate

```

--------------------------------

### PHP Dependencies - composer.json

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Defines the PHP dependencies required for the Willow project. This file is used by Composer to manage package installations and versions.

```json
{
  "composer": {
    "require": {
      "php": ">=7.4",
      "cakephp/cakephp": "^4.0"
    }
  }
}
```

--------------------------------

### Psalm Static Analysis Configuration - psalm.xml

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Configuration file for Psalm, another static analysis tool for PHP, specifying analysis levels and included files.

```xml
<?xml version="1.0"?>
<psalm>
    <projectFiles>
        <directory name="src" />
    </projectFiles>
    <issueHandlers>
        <InvalidArgument errorLevel="suppress"/>
    </issueHandlers>
</psalm>

```

--------------------------------

### Troubleshoot Queue Not Processing

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands to check if the queue worker is running and to clear the Redis queue if it becomes stuck.

```bash
cake_queue_worker_verbose
```

```bash
redis-cli FLUSHDB
```

--------------------------------

### Database Operations and Cache Clearing

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Performs database migrations and clears application caches using CakePHP commands.

```bash
# Database operations
cake_migrate && cake_clear_cache
```

--------------------------------

### Docker Compose Configuration - docker-compose.yml

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Configuration file for Docker Compose, defining the services, networks, and volumes for the Willow application's environment.

```yaml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "8000:80"
    volumes:
      - ./:/var/www/html
```

--------------------------------

### Run Initial Test Suite and Generate Coverage (Bash)

Source: https://github.com/garzarobm/willow/blob/main/AI_IMPROVEMENTS_IMPLEMENTATION_PLAN.md

Executes various PHPUnit test suites for model, service, and job classes within the Willow project using Docker. It also demonstrates how to generate an HTML code coverage report for the model tests, aiding in assessing test completeness.

```bash
# Run all new model tests
docker compose exec willowcms php vendor/bin/phpunit tests/TestCase/Model/Table/AiMetricsTableTest.php
docker compose exec willowcms php vendor/bin/phpunit tests/TestCase/Model/Entity/AiMetricsTest.php

# Run service tests
docker compose exec willowcms php vendor/bin/phpunit tests/TestCase/Service/Api/RateLimitServiceTest.php

# Run job tests
docker compose exec willowcms php vendor/bin/phpunit tests/TestCase/Job/

# Generate coverage report
docker compose exec willowcms php vendor/bin/phpunit --coverage-html webroot/coverage tests/TestCase/Model/
```

--------------------------------

### CakePHP Console Scripts - bin/

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Executable scripts for interacting with the CakePHP framework, including console commands.

```bash
#!/bin/bash
# bin/cake

APP_DIR=$(dirname "$0")/../src

APP_ENV=development

export APP_DIR
export APP_ENV

exec php "$0.php" "$@"

```

```batch
@echo off

setlocal

set APP_DIR=%~dp0..src

set APP_ENV=development

php "%~dp0cake.php" %*

endlocal

```

```php
<?php

require dirname(__DIR__) . '/vendor/autoload.php';

use CakeConsole\
    ConsoleIo;
use CakeConsole\
    CommandRunner;

$runner = new CommandRunner();
$runner->run($argv);

```

--------------------------------

### Extract Translatable Strings

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Commands to extract translatable strings from the project's code, either automatically or by specifying custom paths.

```bash
# Extract strings from code
i18n_extract

# Manually extract with custom paths
docker compose exec willowcms bin/cake i18n extract \
    --paths /var/www/html/src,/var/www/html/plugins
```

--------------------------------

### PHPStan Static Analysis Configuration - phpstan.neon

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Configuration file for PHPStan, a static analysis tool for PHP, specifying analysis parameters and rules.

```neon
parameters:
  level: 5
  paths:
    - src

```

--------------------------------

### Willow Project: Git Hooks

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

This snippet details the Git hooks available in the Willow project. It specifically highlights the 'pre-push' hook, which is used for pre-push validation scripts.

```bash
#!/bin/bash
# Pre-push validation script
# Add your validation logic here
```

--------------------------------

### PHPUnit Testing Configuration - phpunit.xml.dist

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

Configuration file for PHPUnit, the unit testing framework for PHP, defining test suites and execution settings.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd">
    <coverage>
        <include>
            <directory suffix=".php">src/</directory>
        </include>
    </coverage>
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">tests/Unit</directory>
        </testsuite>
    </testsuites>
</phpunit>

```

--------------------------------

### Access Willow CMS Docker Container

Source: https://github.com/garzarobm/willow/blob/main/CLAUDE.md

Command to access the Willow CMS Docker container's shell for interactive operations.

```bash
# Access the container shell
docker compose exec -it willowcms /bin/sh
```

--------------------------------

### Run Comprehensive Test Suite with Coverage (Bash)

Source: https://github.com/garzarobm/willow/blob/main/AI_IMPROVEMENTS_IMPLEMENTATION_PLAN.md

Executes all PHPUnit tests for the project and generates an HTML coverage report. This command is executed within the Docker environment.

```Bash
docker compose exec willowcms php vendor/bin/phpunit --coverage-html webroot/coverage
```

--------------------------------

### Execute Commands in WillowCMS Container

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Provides aliases to execute commands within the WillowCMS Docker container or to open an interactive shell inside it.

```bash
# Execute commands in container
willowcms_exec

# Interactive container shell
willowcms_shell
```

--------------------------------

### Create Admin User with CakePHP Shell

Source: https://github.com/garzarobm/willow/blob/main/DeveloperGuide.md

Uses the CakePHP shell to create a new administrative user with a specified email, password, and role.

```bash
# Create admin user
cake_shell create_user admin@example.com password Admin User
```

--------------------------------

### Willow Project: Tool Modules for Management

Source: https://github.com/garzarobm/willow/blob/main/HELPER.md

This snippet lists the shell scripts available as tool modules for managing the Willow project. These include asset management, data management, internationalization, service checks, system operations, and UI management.

```bash
# tool_modules/asset_management.sh
# tool_modules/common.sh
# tool_modules/data_management.sh
# tool_modules/internationalization.sh
# tool_modules/service_checks.sh
# tool_modules/system.sh
# tool_modules/ui.sh
```