Testcontainers for PHP

When writing tests with Testcontainers for PHP, follow these networking rules to ensure stability and avoid port collisions:

• Never hardcode localhost ports: Always resolve endpoints dynamically using $container->getHost() and the mapped port.
• Use dynamic resolution: Always use $container->getMappedPort($port) or $container->getFirstMappedPort() to find the host-side port.
• Leverage named networks: For container-to-container communication, use named Docker networks and withAliases() to allow containers to find each other by hostname.

Use GenericContainer to start any Docker image. You can configure environment variables, health checks, and volume mounts before starting the container.

<?php

use Testcontainers\Container\GenericContainer;

$container = new GenericContainer('nginx:alpine');

// set an environment variable
$container->withEnvironment([
    'key1' => 'val1',
    'key2' => 'val2'
]);

// enable health check for a container
$container->withHealthCheckCommand('curl --fail localhost');

// mount current dir to /var/www/html
$container->withMount(__DIR__, '/var/www/html');

To use Testcontainers in your PHP project, install the core package and any client libraries you intend to test against (e.g., predis/predis for Redis) via Composer.

composer require --dev testcontainers/testcontainers
composer require --dev predis/predis

The OpenSearchContainer class allows you to spin up an OpenSearch instance configured in single-node mode. It automatically waits for the container to be ready by monitoring startup logs.

By default, you may want to call withDisabledSecurityPlugin() to simplify testing by disabling the security plugin, which avoids the need for authentication during your tests.

<?php

declare(strict_types=1);

use Testcontainers//Modules//OpenSearchContainer;

$container = (new OpenSearchContainer())
    ->withDisabledSecurityPlugin()
    ->start();

try {
    // Use $container->getHost() and $container->getFirstMappedPort() to connect
} finally {
    $container->stop();
}

The MongoDBContainer class allows you to spin up a MongoDB instance in a container. It automatically configures the necessary credentials and implements a wait strategy that ensures the container is ready by waiting until mongosh can successfully execute a command.

<?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();
}

To use the MongoDBContainer module, you must have the following PHP extension installed and enabled:

• ext-mongodb

To enable container-to-container communication, you can connect multiple containers to the same Docker network.

Note: Testcontainers for PHP does not create Docker networks. You must create the network manually via the Docker CLI before starting your containers.

1. Create the network in your terminal:

   docker network create my-test-network

2. In your PHP code, use withNetwork() to join the network and withAliases() to assign a hostname that other containers on that network can use to reach this container.

<?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();

To use the PostgresContainer module, your PHP environment must have the following extension installed and enabled:

• ext-pdo_pgsql

If you are running your PHP tests inside a containerized environment (such as a CI runner), you must ensure the following:

1. Mount the Docker socket: The host's Docker socket (e.g., /var/run/docker.sock) must be mounted into the test container.
2. Network Routing: Ensure that the network routing between your test container and the containers started by Testcontainers is valid.
3. Host Overrides: Use TESTCONTAINERS_HOST_OVERRIDE if your specific CI or network topology requires a custom endpoint to reach the started containers.