More docs and modules

Author: rw4lll

docs/configuration.md

@@ -0,0 +1,38 @@
+# Configuration
+
+## Container runtime access
+
+Testcontainers for PHP uses Docker APIs under the hood, so your test process must be able to reach a Docker-compatible daemon.
+
+- Local socket: `unix:///var/run/docker.sock`
+- Remote daemon: configure `DOCKER_HOST`
+
+## Environment variables
+
+### `DOCKER_HOST`
+
+Defines where the Docker API is available.  
+Examples:
+
+```bash
+export DOCKER_HOST=tcp://127.0.0.1:2375
+export DOCKER_HOST=unix:///var/run/docker.sock
+```
+
+### `TESTCONTAINERS_HOST_OVERRIDE`
+
+Overrides the host address returned by Testcontainers when your tests need a custom endpoint:
+
+```bash
+export TESTCONTAINERS_HOST_OVERRIDE=127.0.0.1
+```
+
+## Running inside containers
+
+If your tests run inside another container:
+
+- Mount the Docker socket.
+- Ensure network routing from test container to started containers is valid.
+- Set host overrides when needed for your CI/network topology.
+
+For startup and connectivity failures, see [troubleshooting](troubleshooting.md).

docs/features/containers.md

@@ -0,0 +1,86 @@
+# Containers
+
+## Starting a container
+
+Start any image with `GenericContainer`:
+
+```php
+<?php
+
+use Testcontainers\Container\GenericContainer;
+
+$container = (new GenericContainer('alpine:3.20'))
+    ->withCommand(['sleep', 'infinity'])
+    ->start();
+```
+
+## Common container options
+
+### Environment variables
+
+```php
+$container = (new GenericContainer('alpine:3.20'))
+    ->withEnvironment([
+        'APP_ENV' => 'test',
+        'FEATURE_X' => 'enabled',
+    ])
+    ->start();
+```
+
+### Exposed ports
+
+```php
+$container = (new GenericContainer('nginx:alpine'))
+    ->withExposedPorts(80)
+    ->start();
+
+$host = $container->getHost();
+$port = $container->getMappedPort(80);
+```
+
+### Files and directories
+
+```php
+$container = (new GenericContainer('alpine:3.20'))
+    ->withCommand(['sleep', 'infinity'])
+    ->withCopyFilesToContainer([
+        ['source' => __DIR__ . '/app.conf', 'target' => '/etc/app.conf'],
+    ])
+    ->withCopyContentToContainer([
+        ['content' => 'hello from php', 'target' => '/tmp/message.txt'],
+    ])
+    ->start();
+```
+
+### Networking
+
+`withNetwork()` connects the container to an existing Docker network. Create the network before starting the container, for example with `docker network create my-test-network`.
+
+```php
+$container = (new GenericContainer('alpine:3.20'))
+    ->withNetwork('my-test-network')
+    ->withAliases(['service-a'])
+    ->start();
+```
+
+### User, working directory, labels, and mounts
+
+```php
+$container = (new GenericContainer('alpine:3.20'))
+    ->withUser('1000:1000')
+    ->withWorkingDir('/app')
+    ->withLabels(['suite' => 'integration'])
+    ->withMount(__DIR__, '/workspace')
+    ->start();
+```
+
+## Stopping and restarting
+
+```php
+$container->restart();
+$container->stop();
+```
+
+`stop()` stops and removes the container.
+
+Related docs: [wait strategies](wait-strategies.md), [networking](networking.md).

docs/features/networking.md

@@ -0,0 +1,66 @@
+# Networking
+
+Testcontainers for PHP maps container ports to random host ports by default.
+
+## Access a service from your test process
+
+Use `getHost()` and `getMappedPort()`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Testcontainers\Container\GenericContainer;
+use Testcontainers\Wait\WaitForHttp;
+
+$container = (new GenericContainer('nginx:alpine'))
+    ->withExposedPorts(80)
+    ->withWait((new WaitForHttp(80))->withPath('/'))
+    ->start();
+
+$url = sprintf('http://%s:%d', $container->getHost(), $container->getMappedPort(80));
+echo $url . PHP_EOL;
+
+$container->stop();
+```
+
+## Use the first mapped port
+
+If a container exposes only one port, use `getFirstMappedPort()`:
+
+```php
+$port = $container->getFirstMappedPort();
+```
+
+## Join a Docker network
+
+Connect multiple containers to the same existing Docker network and use aliases. Testcontainers for PHP does not create Docker networks, so create the network before starting containers:
+
+```bash
+docker network create my-test-network
+```
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Testcontainers\Container\GenericContainer;
+
+$container = (new GenericContainer('alpine'))
+    ->withCommand(['tail', '-f', '/dev/null'])
+    ->withNetwork('my-test-network')
+    ->withAliases(['service-a'])
+    ->start();
+
+$container->stop();
+```
+
+## Notes
+
+- Do not hardcode localhost ports in tests.
+- Always resolve endpoints from `getHost()` and mapped ports.
+- Named networks and aliases are useful for container-to-container communication.
+
+Related docs: [containers](containers.md), [configuration](../configuration.md), [troubleshooting](../troubleshooting.md).

docs/features/wait-strategies.md

@@ -0,0 +1,101 @@
+# Wait strategies
+
+Wait strategies define when a container is ready to use.
+
+`GenericContainer` defaults to a running-state check (`WaitForContainer`).  
+For application readiness, prefer explicit strategies described below.
+
+## Host port (default-friendly)
+
+```php
+<?php
+
+use Testcontainers\Container\GenericContainer;
+use Testcontainers\Wait\WaitForHostPort;
+
+$container = (new GenericContainer('redis:7'))
+    ->withExposedPorts(6379)
+    ->withWait(new WaitForHostPort())
+    ->start();
+```
+
+## Log output
+
+```php
+use Testcontainers\Wait\WaitForLog;
+
+$container = (new GenericContainer('redis:7'))
+    ->withExposedPorts(6379)
+    ->withWait(new WaitForLog('Ready to accept connections'))
+    ->start();
+```
+
+With regular expression matching:
+
+```php
+$container = (new GenericContainer('opensearchproject/opensearch:latest'))
+    ->withExposedPorts(9200)
+    ->withWait(new WaitForLog('/\]\s+started\?\[/', true, 30_000))
+    ->start();
+```
+
+## HTTP checks
+
+```php
+use Testcontainers\Wait\WaitForHttp;
+
+$container = (new GenericContainer('nginx:alpine'))
+    ->withExposedPorts(80)
+    ->withWait(
+        (new WaitForHttp(80))
+            ->withPath('/')
+            ->withExpectedStatusCode(200)
+    )
+    ->start();
+```
+
+## Exec command
+
+```php
+use Testcontainers\Wait\WaitForExec;
+
+$container = (new GenericContainer('mysql:8.0'))
+    ->withExposedPorts(3306)
+    ->withEnvironment(['MYSQL_ROOT_PASSWORD' => 'root'])
+    ->withWait(new WaitForExec(['mysqladmin', 'ping', '-h', '127.0.0.1']))
+    ->start();
+```
+
+With custom validation:
+
+```php
+$container = (new GenericContainer('mysql:8.0'))
+    ->withExposedPorts(3306)
+    ->withEnvironment(['MYSQL_ROOT_PASSWORD' => 'root'])
+    ->withWait(
+        new WaitForExec(
+            ['mysqladmin', 'ping', '-h', '127.0.0.1'],
+            static function ($exitCode, $output): bool {
+                return $exitCode === 0 && str_contains($output, 'mysqld is alive');
+            }
+        )
+    )
+    ->start();
+```
+
+## Docker health check
+
+```php
+use Testcontainers\Wait\WaitForHealthCheck;
+
+$container = (new GenericContainer('alpine'))
+    ->withCommand(['tail', '-f', '/dev/null'])
+    ->withHealthCheckCommand('echo "healthy" || exit 1')
+    ->withWait(new WaitForHealthCheck())
+    ->start();
+```
+
+!!! tip
+    You can tune timeout and polling intervals in wait strategy constructors.
+
+Related docs: [containers](containers.md), [networking](networking.md), [troubleshooting](../troubleshooting.md).

docs/modules/mariadb.md

@@ -0,0 +1,33 @@
+# MariaDB
+
+`MariaDBContainer` configures MariaDB and waits for `mariadb-admin ping`.
+
+## Requirements
+
+- PHP extension: `ext-pdo_mysql`
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Testcontainers\Modules\MariaDBContainer;
+
+$container = (new MariaDBContainer())
+    ->withMariaDBDatabase('foo')
+    ->withMariaDBUser('bar', 'baz')
+    ->start();
+
+try {
+    $pdo = new PDO(
+        sprintf('mysql:host=%s;port=%d', $container->getHost(), $container->getFirstMappedPort()),
+        'bar',
+        'baz',
+    );
+
+    $query = $pdo->query('SHOW databases');
+    $databases = $query->fetchAll(PDO::FETCH_COLUMN);
+} finally {
+    $container->stop();
+}
+```

docs/modules/mongodb.md

@@ -0,0 +1,34 @@
+# MongoDB
+
+`MongoDBContainer` configures credentials and waits until `mongosh` can execute a command.
+
+## Requirements
+
+- PHP extension: `ext-mongodb`
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Testcontainers\Modules\MongoDBContainer;
+
+$container = (new MongoDBContainer())->start();
+
+try {
+    $pingResult = $container->exec([
+        'mongosh',
+        'admin',
+        '-u',
+        'test',
+        '-p',
+        'test',
+        '--eval',
+        '\'db.runCommand("ping").ok\'',
+    ]);
+
+    echo $pingResult;
+} finally {
+    $container->stop();
+}
+```

docs/modules/mysql.md

@@ -0,0 +1,33 @@
+# MySQL
+
+`MySQLContainer` configures MySQL and waits for `mysqladmin ping`.
+
+## Requirements
+
+- PHP extension: `ext-pdo_mysql`
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Testcontainers\Modules\MySQLContainer;
+
+$container = (new MySQLContainer())
+    ->withMySQLDatabase('foo')
+    ->withMySQLUser('bar', 'baz')
+    ->start();
+
+try {
+    $pdo = new PDO(
+        sprintf('mysql:host=%s;port=%d', $container->getHost(), $container->getFirstMappedPort()),
+        'bar',
+        'baz',
+    );
+
+    $query = $pdo->query('SHOW databases');
+    $databases = $query->fetchAll(PDO::FETCH_COLUMN);
+} finally {
+    $container->stop();
+}
+```