README

Testcontainers is a PHP package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The package is inspired by the Testcontainers project for Java.

Legacy PHP support

The official testcontainers/testcontainers-php library requires PHP 8.1 or newer. If you need to support older PHP versions, including those that are EOL, please check out the community-maintained k-kinzal/testcontainers-php project. The discussion about supporting legacy versions lives in issue #38.

Installation

Add this to your project with composer

composer req --dev testcontainers/testcontainers

Usage/Examples

Starting a general 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');

Normally, you have to wait until the Container is ready. For this you can define a wait rule:

use Testcontainers\Container\GenericContainer; use Testcontainers\Wait\WaitForExec; use Testcontainers\Wait\WaitForLog; use Testcontainers\Wait\WaitForHttp; use Testcontainers\Wait\WaitForHealthCheck; use Testcontainers\Wait\WaitForHostPort; $container = new GenericContainer('nginx:alpine'); // Run mysqladmin ping until the command returns exit code 0 $container->withWait(new WaitForExec(['mysqladmin', 'ping', '-h', '127.0.0.1'])); $container->withWait(new WaitForExec(['mysqladmin', 'ping', '-h', '127.0.0.1']), function($exitCode, $contents) { // throw exception if process result is bad }); // Wait until that message is in the logs $container->withWait(new WaitForLog('Ready to accept connections')); // Wait for an http request to succeed $container->withWait((new WaitForHttp($port))->withMethod('GET')->withPath('/')); // Wait for all bound ports to be open $container->withWait(new WaitForHostPort()); // Wait until the Docker heartcheck is green $container->withWait(new WaitForHealthCheck());

MySQL

<?php use Testcontainers\Modules\MySQLContainer; $container = (new MySQLContainer('8.0')) ->withMySQLDatabase('foo') ->withMySQLUser('bar', 'baz') ->start(); $pdo = new \PDO( sprintf( 'mysql:host=%s;port=%d', $container->getHost(), $container->getFirstMappedPort() ), 'bar', 'baz', ); // Do something with PDO

MariaDB

<?php use Testcontainers\Modules\MariaDBContainer; $container = $container = (new MariaDBContainer()) ->withMariaDBDatabase('foo') ->withMariaDBUser('bar', 'baz') ->start(); $pdo = new \PDO( sprintf( 'mysql:host=%s;port=%d', $container->getHost(), $container->getFirstMappedPort() ), 'bar', 'baz', ); // Do something with PDO

PostgreSQL

<?php use Testcontainers\Modules\PostgresContainer; $container = (new PostgresContainer()) ->withPostgresUser('bar') ->withPostgresDatabase('foo') ->start(); $pdo = new \PDO( sprintf( 'pgsql:host=%s;port=%d;dbname=foo', self::$container->getHost(), self::$container->getFirstMappedPort() ), 'bar', 'test', ); // Do something with PDO

Redis

use Testcontainers\Modules\RedisContainer; $container = (new RedisContainer()) ->start(); $redis = new \Redis(); $redis->connect($container->getHost(), $container->getFirstMappedPort()); // Do something with Redis

OpenSearch

use Testcontainers\Modules\OpenSearchContainer; $container = (new OpenSearchContainer()) ->withDisabledSecurityPlugin() ->start(); // Do something with opensearch

Use with symfony

# config/packages/test/services.yaml parameters: 'doctrine.dbal.connection_factory.class': App\Tests\TestConnectionFactory

namespace App\Tests; use Doctrine\Bundle\DoctrineBundle\ConnectionFactory; use Doctrine\Common\EventManager; use Doctrine\DBAL\Configuration; use Doctrine\DBAL\Tools\DsnParser; use Testcontainers\Modules\PostgresContainer; class TestConnectionFactory extends ConnectionFactory { static $testDsn; public function __construct(array $typesConfig, ?DsnParser $dsnParser = null) { if (!$this::$testDsn) { $psql = (new PostgresContainer()) ->withPostgresUser('user') ->withPostgresPassword('password') ->withPostgresDatabase('database') ->start(); $this::$testDsn = sprintf('postgresql://user:password@%s:%d/database?serverVersion=14&charset=utf8', $psql->getAddress(), $psql->getFirstMappedPort()); } parent::__construct($typesConfig, $dsnParser); } public function createConnection(array $params, ?Configuration $config = null, ?EventManager $eventManager = null, array $mappingTypes = []) { $params['url'] = $this::$testDsn; return parent::createConnection($params, $config, $eventManager, $mappingTypes); } }

License

MIT