### Initialize PHPDocker.io Project

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/README.md

Automates project setup through Docker, including cache cleanup, SSL provisioning, dependency installation, and environment startup. Ensure Docker and Docker Compose are installed.

```bash
make init
```

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

### Start Docker Containers

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Starts the Docker containers defined in the docker-compose.yaml file.

```bash
make start
```

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

### PHPDocker.io Make Targets

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/AGENTS.md

Common make targets for project setup, management, and testing. Use these instead of direct binary execution.

```bash
make init               # Full first-time setup (certs, hosts, deps, Docker build, start)
make start              # Start containers
make stop               # Stop containers
make shell              # Bash shell inside PHP container

make static-analysis    # PHPStan level 9 on src/
make unit-tests         # PHPUnit (no coverage)
make coverage-tests     # PHPUnit with xdebug coverage
make behaviour          # Behat behavioral tests

make clear-cache        # Clear Symfony var/ cache
make fix-cache-permissions-dev  # Fix var/ permissions if needed
```

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

### Generate PHP-FPM Dockerfile with Dockerfile

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Renders a Dockerfile for PHP-FPM using a Twig template. It installs only the Debian packages required by selected PHP extensions and git, keeping the image lean. Mandatory extensions are pre-installed in the base image.

```php
use App\PHPDocker\Generator\Files\Dockerfile;

// Inside Generator::generate() — Dockerfile is constructed automatically.
// The rendered output for PHP 8.4 + Redis + GD + git looks like:

// FROM phpdockerio/php:<version>-fpm
// WORKDIR "/application"
//
// RUN apt-get update \
//     && apt-get -y --no-install-recommends install \
//         git \
//         php8.4-redis \
//         php8.4-gd \
//     && apt-get clean \
//     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

// Mandatory extensions (cURL, MBSTRING, OPCache, Readline, XML, Zip) are
// pre-installed in the phpdockerio/php base image and NOT re-listed here.

$dockerfile = new Dockerfile($twig, $project);
echo $dockerfile->getFilename();   // "php-fpm/Dockerfile"
echo $dockerfile->getContents();   // rendered Dockerfile string

```

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

### Calculate External Ports for Services

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Demonstrates how to use `getExternalPort` with various service options to get their assigned host ports. Services like Redis, which are internal-only, return NULL. The webserver (nginx) is noted to bind directly on the base port.

```PHP
use App\PHPDocker\Project\ServiceOptions\GlobalOptions;
use App\PHPDocker\Project\ServiceOptions\MySQL;
use App\PHPDocker\Project\ServiceOptions\MariaDB;
use App\PHPDocker\Project\ServiceOptions\Postgres;
use App\PHPDocker\Project\ServiceOptions\Mailhog;
use App\PHPDocker\Project\ServiceOptions\Redis;

$basePort = 10000;

$mysql    = new MySQL();
$mariadb  = new MariaDB();
$postgres = new Postgres();
$mailhog  = new Mailhog();
$redis    = new Redis();

echo $mysql->getExternalPort($basePort);    // 10002  (offset +2)
echo $mariadb->getExternalPort($basePort);  // 10003  (offset +3)
echo $postgres->getExternalPort($basePort); // 10004  (offset +4)
echo $mailhog->getExternalPort($basePort);  // 10001  (offset +1, web UI)
var_dump($redis->getExternalPort($basePort)); // NULL  (internal-only)

// The webserver (nginx) always binds directly on $basePort (10000 -> 80)
// with no offset, hard-coded in DockerCompose::addWebserver().
```

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

### Configure Docker Environment with Project Object

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Instantiate and configure the Project object, enabling specific services like Redis and ClickHouse, and setting detailed options for MariaDB. Introspect the project to verify enabled services and retrieve configuration values.

```php
use App\PHPDocker\Project\Project;
use App\PHPDocker\Project\ServiceOptions\Php as PhpOptions;
use App\PHPDocker\Project\ServiceOptions\GlobalOptions;

$php    = new PhpOptions('8.3', ['Xdebug', 'Intl (Internationalisation)'], false, 'public/index.php');
$global = new GlobalOptions(basePort: 8080, appPath: '/home/user/myproject', dockerWorkingDir: '/var/www');

$project = new Project(phpOptions: $php, globalOptions: $global);

// Selectively enable services
$project->getRedisOptions()->setEnabled(true);
$project->getClickhouseOptions()->setEnabled(true);

$project->getMariadbOptions()
    ->setEnabled(true)
    ->setVersion('11.2')           // see MariaDB::getChoices()
    ->setDatabaseName('shop')
    ->setRootPassword('r00t')
    ->setUsername('shop_user')
    ->setPassword('shop_pass');

// Introspect
var_dump($project->hasRedis());       // bool(true)
var_dump($project->hasMysql());       // bool(false)
var_dump($project->hasMariadb());     // bool(true)
var_dump($project->getPhpOptions()->getVersion());         // string(3) "8.3"
var_dump($project->getGlobalOptions()->getBasePort());     // int(8080)

// Port offsets (base + offset):
// webserver  => basePort + 0  (10000)
// mailhog    => basePort + 1
// mysql      => basePort + 2
// mariadb    => basePort + 3
// postgres   => basePort + 4
```

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

### Common PHPDocker.io Commands

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/README.md

A collection of make commands for managing the PHPDocker.io environment, including starting/stopping services, accessing the shell, and running analysis tools.

```bash
make start
```

```bash
make stop
```

```bash
make shell
```

```bash
make static-analysis
```

```bash
make unit-tests
```

```bash
make behaviour
```

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

### Configure PHP Options with Version and Extensions

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Configure PHP options, specifying the version, desired extensions, Git support, and front controller path. This class validates PHP versions and resolves extensions to their Debian package names.

```php
use App\PHPDocker\Project\ServiceOptions\Php as PhpOptions;
use App\PHPDocker\PhpExtension\AvailableExtensionsFactory;
use InvalidArgumentException;

// List all optional extensions available per PHP version (used to populate the UI)
$allExtensions = AvailableExtensionsFactory::getAllExtensionNames();
// ['8.2' => ['AMQP', 'Bcmath', ...], '8.3' => [...], '8.4' => [...], '8.5' => [...]]

// Create extensions registry for a specific version
$registry = AvailableExtensionsFactory::create('8.4');

$ext = $registry->getPhpExtension('Xdebug');
echo $ext->getName();          // "Xdebug"
print_r($ext->getPackages());  // ['php8.4-xdebug']

$ext2 = $registry->getPhpExtension('GD');
print_r($ext2->getPackages()); // ['php8.4-gd']

var_dump($registry->isAvailable('Redis'));    // bool(true)
var_dump($registry->isAvailable('nonexist')); // bool(false)

// All optional extensions as PhpExtension objects
$optionals = $registry->getOptional();
// [ PhpExtension('AMQP'), PhpExtension('AST'), PhpExtension('Bcmath'), ... ]

// Invalid version throws
try {
    AvailableExtensionsFactory::create('7.4');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(); // "PHP version specified (7.4) is unsupported"
}

// Build PhpOptions with selected extensions (unknown extension also throws)
$phpOptions = new PhpOptions(
    version: PhpOptions::PHP_VERSION_84,   // '8.4'
    extensions: ['Redis', 'GD', 'Xdebug'],
    hasGit: true,
    frontControllerPath: 'public/index.php',
);

foreach ($phpOptions->getExtensions() as $ext) {
    echo $ext->getName() . ': ' . implode(', ', $ext->getPackages()) . PHP_EOL;
}
// Redis: php8.4-redis
// GD: php8.4-gd
// Xdebug: php8.4-xdebug
```

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

### Generate docker-compose.yml with DockerCompose

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Constructs the full docker-compose.yml as a YAML string. It iterates over enabled services, setting images, environment variables, port mappings, and volume mounts. The output includes a header comment and blank lines for readability.

```php
use App\PHPDocker\Generator\Files\DockerCompose;
use Symfony\Component\Yaml\Dumper;

// Typically constructed and called inside Generator::generate()
$project = /* ... fully configured Project ... */;
$phpIniFilename = 'php-fpm/php-ini-overrides.ini';

$dockerCompose = new DockerCompose(new Dumper(), $project, $phpIniFilename);

echo $dockerCompose->getFilename();   // "docker-compose.yml"
$yaml = $dockerCompose->getContents();
// Outputs (example with MySQL + Redis enabled, basePort=10000):
//
// ###############################################################################
// #                          Generated on phpdocker.io                          #
// ###############################################################################
//
// version: '3.1'
// services:
//     redis:
//         image: 'redis:alpine'
//
//     mysql:
//         image: 'mysql:8.0'
//         working_dir: /application
//         volumes:
//             - '.:/application'
//         environment:
//             - MYSQL_ROOT_PASSWORD=secret
//             - MYSQL_DATABASE=myapp
//             - MYSQL_USER=appuser
//             - MYSQL_PASSWORD=apppass
//         ports:
//             - '10002:3306'
//
//     webserver:
//         image: 'nginx:alpine'
//         working_dir: /application
//         volumes:
//             - '.:/application'
//             - './phpdocker/nginx/nginx.conf:/etc/nginx/conf.d/default.conf'
//         ports:
//             - '10000:80'
//
//     php-fpm:
//         build: phpdocker/php-fpm
//         working_dir: /application
//         volumes:
//             - '.:/application'
//             - './phpdocker/php-fpm/php-ini-overrides.ini:/etc/php/8.4/fpm/conf.d/99-overrides.ini'
//             - './phpdocker/php-fpm/php-ini-overrides.ini:/etc/php/8.4/cli/conf.d/99-overrides.ini'

```

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

### Configure Global Options for Docker Environment

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Set global options for the Docker environment, including the base port for services, the local application path, and the Docker working directory. These settings influence volume mappings and port exposures in the generated Docker Compose file.

```php
use App\PHPDocker\Project\ServiceOptions\GlobalOptions;

$opts = new GlobalOptions(
    basePort: 10000,
    appPath: '.',                    // relative to docker-compose.yml location
    dockerWorkingDir: '/application',
);

echo $opts->getBasePort();       // 10000
echo $opts->getAppPath();        // "."
echo $opts->getDockerWorkingDir(); // "/application"

// Resulting docker-compose volume entry built by DockerCompose:
// ".:/application"
// nginx exposed on host port 10000 -> container 80
// mysql (if enabled) on 10002 -> 3306
// postgres (if enabled) on 10004 -> 5432
```

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

### Run Single PHPUnit Test File

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/AGENTS.md

Execute a specific PHPUnit test file within the PHP container. Ensure XDEBUG_MODE is set for coverage.

```bash
docker compose run -e XDEBUG_MODE=coverage --rm php-fpm vendor/bin/phpunit tests/Functional/GeneratorTest.php
```

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

### Perform Static Analysis

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Runs PHPStan level 9 on the src/ directory to check for static analysis errors.

```bash
make static-analysis
```

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

### POST Request Form Data Simulation

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

This snippet simulates the POST data that would be submitted from the web form. It covers global settings, PHP options, optional services, and MySQL configuration. This data is used to hydrate a project object for generation.

```php
// Route: POST /  (form action)
// The form fields map directly to the domain model:

// global settings
$_POST['project']['globalOptions']['basePort']        = '10000';
$_POST['project']['globalOptions']['appPath']         = '.';
$_POST['project']['globalOptions']['dockerWorkingDir']= '/application';

// PHP settings
$_POST['project']['phpOptions']['version']            = '8.4';
$_POST['project']['phpOptions']['extensions']         = ['Redis', 'GD'];
$_POST['project']['phpOptions']['hasGit']             = '1';
$_POST['project']['phpOptions']['frontControllerPath']= 'public/index.php';

// Optional services (checkbox values)
$_POST['project']['hasRedis']      = '1';
$_POST['project']['hasMemcached']  = '0';
$_POST['project']['hasMailhog']    = '1';
$_POST['project']['hasClickhouse'] = '0';

// MySQL block (only processed when hasMysql = true)
$_POST['project']['mysqlOptions']['hasMysql']      = '1';
$_POST['project']['mysqlOptions']['version']       = '8.0';
$_POST['project']['mysqlOptions']['databaseName']  = 'myapp';
$_POST['project']['mysqlOptions']['rootPassword']  = 'secret';
$_POST['project']['mysqlOptions']['username']      = 'appuser';
$_POST['project']['mysqlOptions']['password']      = 'apppass';

// On success, the response is:
// HTTP 200, Content-Disposition: attachment; filename="phpdocker.zip"
// Body: binary ZIP containing:
//   phpdocker/README.md
//   phpdocker/README.html
//   phpdocker/php-fpm/Dockerfile
//   phpdocker/php-fpm/php-ini-overrides.ini
//   phpdocker/nginx/nginx.conf
//   docker-compose.yml

// On validation failure, HTTP 200 re-renders the form with inline error messages,
// e.g. "#container_for_basePort" contains "This value should not be blank."
```

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

### Run Unit Tests

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Executes PHPUnit tests without code coverage generation.

```bash
make unit-tests
```

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

### Generate Nginx Configuration with NginxConf

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Renders an Nginx server block configuration from a Twig template. It sets up FastCGI to the php-fpm upstream and configures the document root and front controller based on project settings.

```nginx
server {
    listen 80 default;
    client_max_body_size 108M;
    access_log /var/log/nginx/application.access.log;

    root /application/public;
    index index.php;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    if (!-e $request_filename) {
        rewrite ^.*$ /index.php last;
    }

    location ~ \.php$ {
        fastcgi_pass php-fpm:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PHP_VALUE "error_log=/var/log/nginx/application_php_errors.log";
        fastcgi_buffers 16 16k;
        fastcgi_buffer_size 32k;
        include fastcgi_params;
    }
}

```

```php
use App\PHPDocker\Generator\Files\NginxConf;

// frontControllerPath = 'public/index.php'
// dockerWorkingDir    = '/application'
//
// Generated nginx.conf:
//
// server {
//     listen 80 default;
//     client_max_body_size 108M;
//     access_log /var/log/nginx/application.access.log;
//
//     root /application/public;
//     index index.php;
//
//     location / {
//         try_files $uri /index.php$is_args$args;
//     }
//
//     if (!-e $request_filename) {
//         rewrite ^.*$ /index.php last;
//     }
//
//     location ~ \.php$ {
//         fastcgi_pass php-fpm:9000;
//         fastcgi_index index.php;
//         fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
//         fastcgi_param PHP_VALUE "error_log=/var/log/nginx/application_php_errors.log";
//         fastcgi_buffers 16 16k;
//         fastcgi_buffer_size 32k;
//         include fastcgi_params;
//     }
// }

$nginxConf = new NginxConf($twig, $project);
echo $nginxConf->getFilename();   // "nginx/nginx.conf"
echo $nginxConf->getContents();   // rendered nginx config

```

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

### Run Single Behat Scenario

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/AGENTS.md

Execute a specific Behat scenario within the PHP container. Use --colors for better output and --name to target a scenario.

```bash
docker compose run -e XDEBUG_MODE=coverage --rm php-fpm vendor/bin/behat --colors --name="scenario name"
```

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

### Run Coverage Tests

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Executes PHPUnit tests with xdebug coverage enabled to generate code coverage reports.

```bash
make coverage-tests
```

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

### Generator::generate

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Produces a complete Docker environment archive by accepting a fully hydrated `Project` object and rendering all necessary configuration files into a ZIP archive for download. This is the primary entry point for the generation pipeline.

```APIDOC
## Generator::generate — Produce a complete Docker environment archive

### Description
Accepts a fully hydrated `Project` and renders all configuration files (README, Dockerfile, php.ini overrides, nginx.conf, docker-compose.yml) into a ZIP archive that the user downloads. This is the single entry point to the generation pipeline.

### Method Signature
```php
public function generate(Project $project): Archive
```

### Parameters
#### Project Object
- **project** (App\PHPDocker\Project\Project) - Required - A fully configured `Project` object containing all service options and global settings.

### Request Example
```php
use App\PHPDocker\Generator\Generator;
use App\PHPDocker\Project\Project;
use App\PHPDocker\Project\ServiceOptions\Php as PhpOptions;
use App\PHPDocker\Project\ServiceOptions\GlobalOptions;

// Build PHP options: version 8.4, with Redis + GD extensions, git installed,
// front controller at public/index.php
$phpOptions = new PhpOptions(
    version: '8.4',
    extensions: ['Redis', 'GD'],
    hasGit: true,
    frontControllerPath: 'public/index.php',
);

// Global project settings
$globalOptions = new GlobalOptions(
    basePort: 10000,
    appPath: '.',
    dockerWorkingDir: '/application',
);

// Assemble the project
$project = new Project(phpOptions: $phpOptions, globalOptions: $globalOptions);

// Enable optional services
$project->getRedisOptions()->setEnabled(true);
$project->getMemcachedOptions()->setEnabled(true);
$project->getMailhogOptions()->setEnabled(true);

// Configure MySQL
$project->getMysqlOptions()
    ->setEnabled(true)
    ->setVersion('8.0')
    ->setDatabaseName('myapp')
    ->setRootPassword('secret')
    ->setUsername('appuser')
    ->setPassword('apppass');

// Configure PostgreSQL
$project->getPostgresOptions() 
    ->setEnabled(true)
    ->setVersion('15')
    ->setDatabaseName('myapp_pg')
    ->setRootUser('pgadmin')
    ->setRootPassword('pgsecret');

/** @var Generator $generator */ // injected via Symfony DI
$archive = $generator->generate($project);

// $archive->getTmpFilename() => '/tmp/phpdocker_abc123.zip'
// $archive->getFilename()    => 'phpdocker.zip'
// Serve via BinaryFileResponse:
$response = new \Symfony\Component\HttpFoundation\BinaryFileResponse($archive->getTmpFilename());
$response->setContentDisposition(
    \Symfony\Component\HttpFoundation\ResponseHeaderBag::DISPOSITION_ATTACHMENT,
    $archive->getFilename()
);
$response->deleteFileAfterSend(true);
```

### Response
#### Success Response (Archive Object)
- **tmpFilename** (string) - The temporary path to the generated ZIP archive.
- **filename** (string) - The intended filename for the downloaded ZIP archive.
```

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

### Run Behavioral Tests

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Executes Behat behavioral tests to verify application functionality from a user's perspective.

```bash
make behaviour
```

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

### Generate Docker Environment Archive

Source: https://context7.com/phpdocker-io/phpdocker.io/llms.txt

Use the Generator::generate method to produce a ZIP archive containing all necessary configuration files for a Dockerized PHP application. This method accepts a fully configured Project object and returns an archive object with temporary and final filenames.

```php
use App\PHPDocker\Generator\Generator;
use App\PHPDocker\Project\Project;
use App\PHPDocker\Project\ServiceOptions\Php as PhpOptions;
use App\PHPDocker\Project\ServiceOptions\GlobalOptions;

// Build PHP options: version 8.4, with Redis + GD extensions, git installed,
// front controller at public/index.php
$phpOptions = new PhpOptions(
    version: '8.4',
    extensions: ['Redis', 'GD'],
    hasGit: true,
    frontControllerPath: 'public/index.php',
);

// Global project settings
$globalOptions = new GlobalOptions(
    basePort: 10000,
    appPath: '.',
    dockerWorkingDir: '/application',
);

// Assemble the project
$project = new Project(phpOptions: $phpOptions, globalOptions: $globalOptions);

// Enable optional services
$project->getRedisOptions()->setEnabled(true);
$project->getMemcachedOptions()->setEnabled(true);
$project->getMailhogOptions()->setEnabled(true);

// Configure MySQL
$project->getMysqlOptions תחום
    ->setEnabled(true)
    ->setVersion('8.0')
    ->setDatabaseName('myapp')
    ->setRootPassword('secret')
    ->setUsername('appuser')
    ->setPassword('apppass');

// Configure PostgreSQL
$project->getPostgresOptions תחום
    ->setEnabled(true)
    ->setVersion('15')
    ->setDatabaseName('myapp_pg')
    ->setRootUser('pgadmin')
    ->setRootPassword('pgsecret');

/** @var Generator $generator */ // injected via Symfony DI
$archive = $generator->generate($project);

// $archive->getTmpFilename() => '/tmp/phpdocker_abc123.zip'
// $archive->getFilename()    => 'phpdocker.zip'
// Serve via BinaryFileResponse:
$response = new \Symfony\Component\HttpFoundation\BinaryFileResponse($archive->getTmpFilename());
$response->setContentDisposition(
    \Symfony\Component\HttpFoundation\ResponseHeaderBag::DISPOSITION_ATTACHMENT,
    $archive->getFilename()
);
$response->deleteFileAfterSend(true);

```

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

### Fix Development Cache Permissions

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Corrects file permissions for the development cache in the var/ directory if they become problematic.

```bash
make fix-cache-permissions-dev
```

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

### Stop Docker Containers

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Stops the running Docker containers.

```bash
make stop
```

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

### Access PHP Container Shell

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Opens an interactive bash shell inside the PHP container for debugging or direct command execution.

```bash
make shell
```

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

### Clear Symfony Cache

Source: https://github.com/phpdocker-io/phpdocker.io/blob/master/CLAUDE.md

Clears the Symfony application's cache files located in the var/cache directory.

```bash
make clear-cache
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.