Download the PHP package tiny-blocks/docker-container without Composer

Docker container

• Overview
• Installation
• How to use
  • Creating a container
  • Running a container
  • Running if not exists
  • Pulling images in parallel
  • Setting network
  • Setting port mappings
  • Setting volume mappings
  • Setting environment variables
  • Disabling auto-remove
  • Copying files to a container
  • Stopping a container
  • Stopping on shutdown
  • Executing commands after startup
  • Wait strategies
• MySQL container
  • Configuring MySQL options
  • Setting readiness timeout
  • Retrieving connection data
    • Environment-aware connection
• Flyway container
  • Setting the database source
  • Configuring migrations
  • Configuring Flyway options
  • Running Flyway commands
• Usage examples
  • MySQL with Flyway migrations
• License
• Contributing

Overview

Manages Docker containers programmatically for PHP, enabling integration tests and disposable infrastructure to be orchestrated directly from code. Supports container definitions, port and volume mappings, environment variables, readiness probes, shutdown hooks, and orphan reaping.

Installation

How to use

Creating a container

Creates a container from a specified image and an optional name.

Running a container

Starts a container. Optionally accepts commands to run on startup and a wait strategy applied after the container starts.

With commands:

With commands and a wait strategy:

Running if not exists

Starts a container only if a container with the same name is not already running.

Pulling images in parallel

Calling pullImage() starts downloading the image in the background via a non-blocking process. When run() or runIfNotExists() is called, it waits for the pull to complete before starting the container.

To pull multiple images in parallel, call pullImage() on all containers before calling run() on any of them. This way the downloads happen concurrently:

Setting network

Sets the Docker network the container should join. The network is created automatically when the container is started via run() or runIfNotExists(), if it does not already exist. Networks created by the library are labeled with tiny-blocks.docker-container=true for safe cleanup.

Setting port mappings

Maps a port from the host to the container.

After the container starts, both ports are available through the Address:

Setting volume mappings

Mounts a directory from the host into the container.

Setting environment variables

Adds an environment variable to the container.

Disabling auto-remove

By default, containers are removed when stopped. This disables that behavior.

Copying files to a container

Registers files or directories to be copied from the host into the container after it starts.

Stopping a container

Stops a running container. An optional timeout (in seconds) controls how long to wait before forcing the stop. The default timeout is 300 seconds.

With a custom timeout:

Stopping on shutdown

Registers the container to be forcefully removed when the PHP process exits. On shutdown, the following cleanup is performed automatically:

• The container is killed and removed (docker rm --force --volumes).
• Anonymous volumes created by the container (e.g., MySQL's /var/lib/mysql) are removed.
• Unused networks created by the library are pruned.

Only resources labeled with tiny-blocks.docker-container=true are affected. Containers, volumes, and networks from other environments are never touched.

Executing commands after startup

Runs commands inside an already-started container.

The returned ExecutionCompleted provides the command output and success status:

Wait strategies

Waiting for a fixed time

Pauses execution for a specified number of seconds before or after starting a container.

Waiting for a dependency

Blocks until a readiness condition is satisfied, with a configurable timeout. This is useful when one container depends on another being fully ready.

MySQL container

MySQLDockerContainer provides a specialized container for MySQL databases. It extends the generic container with MySQL-specific configuration and automatic readiness detection.

Configuring MySQL options

Setting readiness timeout

Configures how long the MySQL container waits for the database to become ready before throwing a ContainerWaitTimeout exception. The default timeout is 30 seconds.

Retrieving connection data

After the MySQL container starts, connection details are available through the MySQLContainerStarted instance.

Use firstExposedPort() when connecting from another container in the same network. Use firstHostPort() when connecting from the host machine (e.g., tests running outside Docker).

Environment-aware connection

The Address and Ports contracts provide environment-aware methods that automatically resolve the correct host and port for connecting to a container. These methods detect whether the caller is running inside Docker or on the host machine:

This is useful when the same test suite runs both locally (inside a Docker Compose stack) and in CI (on the host). Instead of manually checking the environment and switching between getHostname()/getIp() or firstExposedPort()/ firstHostPort(), the environment-aware methods handle it transparently.

Flyway container

FlywayDockerContainer provides a specialized container for running Flyway database migrations. It encapsulates Flyway configuration, database source detection, and migration file management.

Setting the database source

Configures the Flyway container to connect to a running MySQL container. Automatically detects the JDBC URL and target schema from MYSQL_DATABASE, and sets the history table to schema_history.

The schema and table can be overridden after calling withSource():

Configuring migrations

Sets the host directory containing Flyway migration SQL files. The files are copied into the container at /flyway/migrations.

Configuring Flyway options

Running Flyway commands

Usage examples

• When running the containers from the library on a host (your local machine), map the volume /var/run/docker.sock:/var/run/docker.sock so the container has access to the Docker daemon on the host machine.
• In some cases, it may be necessary to add the docker-cli dependency to your PHP image to interact with Docker from within the container.

MySQL with Flyway migrations

Configure both containers and start image pulls in parallel before running either one:

License

Docker container is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.