Skip to content

Commit d58542f

Browse files
shyimshyim
authored
Merge pull request #67 from rw4lll/feat/docs
Docs and website for php.testcontainers.org
2 parents 466bb96 + 10e4589 commit d58542f

46 files changed

Lines changed: 2200 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
11
/vendor/
22
/.php-cs-fixer.cache
33
/.phpunit.cache
4-
/composer.lock
4+
/composer.lock
5+
6+
# IDEs and editors
7+
/.idea
8+
.project
9+
.classpath
10+
.c9/
11+
*.launch
12+
.settings/
13+
*.sublime-workspace
14+
15+
# IDE - VSCode
16+
.vscode/*
17+
!.vscode/settings.json
18+
!.vscode/tasks.json
19+
!.vscode/launch.json
20+
!.vscode/extensions.json

‎composer.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,8 @@
5252
"integration": "paratest tests/ --bootstrap vendor/autoload.php -f",
5353
"cs": "php-cs-fixer fix --dry-run",
5454
"cs:fix": "php-cs-fixer fix",
55-
"phpstan": "phpstan analyse --memory-limit=256M"
55+
"phpstan": "phpstan analyse --memory-limit=256M",
56+
"docs:serve": "docker compose up"
5657
},
5758
"config": {
5859
"allow-plugins": {

‎docker-compose.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
services:
2+
docs:
3+
image: python:3.14
4+
command: sh -c "pip install -r requirements.txt && mkdocs serve -a 0.0.0.0:8000"
5+
working_dir: /docs
6+
volumes:
7+
- ./:/docs
8+
ports:
9+
- 8000:8000

‎docs/configuration.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Configuration
2+
3+
## Container runtime access
4+
5+
Testcontainers for PHP uses Docker APIs under the hood, so your test process must be able to reach a Docker-compatible daemon.
6+
7+
- Local socket: `unix:///var/run/docker.sock`
8+
- Remote daemon: configure `DOCKER_HOST`
9+
10+
## Environment variables
11+
12+
### `DOCKER_HOST`
13+
14+
Defines where the Docker API is available.
15+
Examples:
16+
17+
```bash
18+
export DOCKER_HOST=tcp://127.0.0.1:2375
19+
export DOCKER_HOST=unix:///var/run/docker.sock
20+
```
21+
22+
### `TESTCONTAINERS_HOST_OVERRIDE`
23+
24+
Overrides the host address returned by Testcontainers when your tests need a custom endpoint:
25+
26+
```bash
27+
export TESTCONTAINERS_HOST_OVERRIDE=127.0.0.1
28+
```
29+
30+
## Running inside containers
31+
32+
If your tests run inside another container:
33+
34+
- Mount the Docker socket.
35+
- Ensure network routing from test container to started containers is valid.
36+
- Set host overrides when needed for your CI/network topology.
37+
38+
For startup and connectivity failures, see [troubleshooting](troubleshooting.md).

‎docs/features/containers.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Containers
2+
3+
## Starting a container
4+
5+
Start any image with `GenericContainer`:
6+
7+
```php
8+
<?php
9+
10+
use Testcontainers\Container\GenericContainer;
11+
12+
$container = (new GenericContainer('alpine:3.20'))
13+
->withCommand(['sleep', 'infinity'])
14+
->start();
15+
```
16+
17+
## Common container options
18+
19+
### Environment variables
20+
21+
```php
22+
$container = (new GenericContainer('alpine:3.20'))
23+
->withEnvironment([
24+
'APP_ENV' => 'test',
25+
'FEATURE_X' => 'enabled',
26+
])
27+
->start();
28+
```
29+
30+
### Exposed ports
31+
32+
```php
33+
$container = (new GenericContainer('nginx:alpine'))
34+
->withExposedPorts(80)
35+
->start();
36+
37+
$host = $container->getHost();
38+
$port = $container->getMappedPort(80);
39+
```
40+
41+
### Files and directories
42+
43+
```php
44+
$container = (new GenericContainer('alpine:3.20'))
45+
->withCommand(['sleep', 'infinity'])
46+
->withCopyFilesToContainer([
47+
['source' => __DIR__ . '/app.conf', 'target' => '/etc/app.conf'],
48+
])
49+
->withCopyContentToContainer([
50+
['content' => 'hello from php', 'target' => '/tmp/message.txt'],
51+
])
52+
->start();
53+
```
54+
55+
### Networking
56+
57+
`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`.
58+
59+
```php
60+
$container = (new GenericContainer('alpine:3.20'))
61+
->withNetwork('my-test-network')
62+
->withAliases(['service-a'])
63+
->start();
64+
```
65+
66+
### User, working directory, labels, and mounts
67+
68+
```php
69+
$container = (new GenericContainer('alpine:3.20'))
70+
->withUser('1000:1000')
71+
->withWorkingDir('/app')
72+
->withLabels(['suite' => 'integration'])
73+
->withMount(__DIR__, '/workspace')
74+
->start();
75+
```
76+
77+
## Stopping and restarting
78+
79+
```php
80+
$container->restart();
81+
$container->stop();
82+
```
83+
84+
`stop()` stops and removes the container.
85+
86+
Related docs: [wait strategies](wait-strategies.md), [networking](networking.md).

‎docs/features/networking.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Networking
2+
3+
Testcontainers for PHP maps container ports to random host ports by default.
4+
5+
## Access a service from your test process
6+
7+
Use `getHost()` and `getMappedPort()`:
8+
9+
```php
10+
<?php
11+
12+
declare(strict_types=1);
13+
14+
use Testcontainers\Container\GenericContainer;
15+
use Testcontainers\Wait\WaitForHttp;
16+
17+
$container = (new GenericContainer('nginx:alpine'))
18+
->withExposedPorts(80)
19+
->withWait((new WaitForHttp(80))->withPath('/'))
20+
->start();
21+
22+
$url = sprintf('http://%s:%d', $container->getHost(), $container->getMappedPort(80));
23+
echo $url . PHP_EOL;
24+
25+
$container->stop();
26+
```
27+
28+
## Use the first mapped port
29+
30+
If a container exposes only one port, use `getFirstMappedPort()`:
31+
32+
```php
33+
$port = $container->getFirstMappedPort();
34+
```
35+
36+
## Join a Docker network
37+
38+
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:
39+
40+
```bash
41+
docker network create my-test-network
42+
```
43+
44+
```php
45+
<?php
46+
47+
declare(strict_types=1);
48+
49+
use Testcontainers\Container\GenericContainer;
50+
51+
$container = (new GenericContainer('alpine'))
52+
->withCommand(['tail', '-f', '/dev/null'])
53+
->withNetwork('my-test-network')
54+
->withAliases(['service-a'])
55+
->start();
56+
57+
$container->stop();
58+
```
59+
60+
## Notes
61+
62+
- Do not hardcode localhost ports in tests.
63+
- Always resolve endpoints from `getHost()` and mapped ports.
64+
- Named networks and aliases are useful for container-to-container communication.
65+
66+
Related docs: [containers](containers.md), [configuration](../configuration.md), [troubleshooting](../troubleshooting.md).

‎docs/features/wait-strategies.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Wait strategies
2+
3+
Wait strategies define when a container is ready to use.
4+
5+
`GenericContainer` defaults to a running-state check (`WaitForContainer`).
6+
For application readiness, prefer explicit strategies described below.
7+
8+
## Host port (default-friendly)
9+
10+
```php
11+
<?php
12+
13+
use Testcontainers\Container\GenericContainer;
14+
use Testcontainers\Wait\WaitForHostPort;
15+
16+
$container = (new GenericContainer('redis:7'))
17+
->withExposedPorts(6379)
18+
->withWait(new WaitForHostPort())
19+
->start();
20+
```
21+
22+
## Log output
23+
24+
```php
25+
use Testcontainers\Wait\WaitForLog;
26+
27+
$container = (new GenericContainer('redis:7'))
28+
->withExposedPorts(6379)
29+
->withWait(new WaitForLog('Ready to accept connections'))
30+
->start();
31+
```
32+
33+
With regular expression matching:
34+
35+
```php
36+
$container = (new GenericContainer('opensearchproject/opensearch:latest'))
37+
->withExposedPorts(9200)
38+
->withWait(new WaitForLog('/\]\s+started\?\[/', true, 30_000))
39+
->start();
40+
```
41+
42+
## HTTP checks
43+
44+
```php
45+
use Testcontainers\Wait\WaitForHttp;
46+
47+
$container = (new GenericContainer('nginx:alpine'))
48+
->withExposedPorts(80)
49+
->withWait(
50+
(new WaitForHttp(80))
51+
->withPath('/')
52+
->withExpectedStatusCode(200)
53+
)
54+
->start();
55+
```
56+
57+
## Exec command
58+
59+
```php
60+
use Testcontainers\Wait\WaitForExec;
61+
62+
$container = (new GenericContainer('mysql:8.0'))
63+
->withExposedPorts(3306)
64+
->withEnvironment(['MYSQL_ROOT_PASSWORD' => 'root'])
65+
->withWait(new WaitForExec(['mysqladmin', 'ping', '-h', '127.0.0.1']))
66+
->start();
67+
```
68+
69+
With custom validation:
70+
71+
```php
72+
$container = (new GenericContainer('mysql:8.0'))
73+
->withExposedPorts(3306)
74+
->withEnvironment(['MYSQL_ROOT_PASSWORD' => 'root'])
75+
->withWait(
76+
new WaitForExec(
77+
['mysqladmin', 'ping', '-h', '127.0.0.1'],
78+
static function ($exitCode, $output): bool {
79+
return $exitCode === 0 && str_contains($output, 'mysqld is alive');
80+
}
81+
)
82+
)
83+
->start();
84+
```
85+
86+
## Docker health check
87+
88+
```php
89+
use Testcontainers\Wait\WaitForHealthCheck;
90+
91+
$container = (new GenericContainer('alpine'))
92+
->withCommand(['tail', '-f', '/dev/null'])
93+
->withHealthCheckCommand('echo "healthy" || exit 1')
94+
->withWait(new WaitForHealthCheck())
95+
->start();
96+
```
97+
98+
!!! tip
99+
You can tune timeout and polling intervals in wait strategy constructors.
100+
101+
Related docs: [containers](containers.md), [networking](networking.md), [troubleshooting](../troubleshooting.md).

‎docs/index.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Testcontainers for PHP
2+
3+
<p style="text-align: center"><strong>Not using PHP? Here are other supported languages.</strong></p>
4+
<div class="card-grid">
5+
<a href="https://java.testcontainers.org/" class="card-grid-item"><img src="/site/language-logos/java.svg" alt="Java"/>Java</a>
6+
<a href="https://golang.testcontainers.org/" class="card-grid-item"><img src="/site/language-logos/go.svg" alt="Go"/>Go</a>
7+
<a href="https://dotnet.testcontainers.org/" class="card-grid-item"><img src="/site/language-logos/dotnet.svg" alt=".NET"/>.NET</a>
8+
<a href="https://node.testcontainers.org/" class="card-grid-item"><img src="/site/language-logos/nodejs.svg" alt="Node.js"/>Node.js</a>
9+
<a href="https://cljdoc.org/d/clj-test-containers/clj-test-containers/0.7.4/doc/readme/" class="card-grid-item"><img src="/site/language-logos/clojure.svg" alt="Clojure"/>Clojure</a>
10+
<a href="https://github.com/testcontainers/testcontainers-elixir/" class="card-grid-item"><img src="/site/language-logos/elixir.svg" alt="Elixir"/>Elixir</a>
11+
<a href="https://github.com/testcontainers/testcontainers-hs/" class="card-grid-item"><img src="/site/language-logos/haskell.svg" alt="Haskell"/>Haskell</a>
12+
<a href="https://testcontainers-python.readthedocs.io/en/latest/" class="card-grid-item"><img src="/site/language-logos/python.svg" alt="Python"/>Python</a>
13+
<a href="https://github.com/testcontainers/testcontainers-ruby/" class="card-grid-item"><img src="/site/language-logos/ruby.svg" alt="Ruby"/>Ruby</a>
14+
<a href="https://docs.rs/testcontainers/latest/testcontainers/" class="card-grid-item"><img src="/site/language-logos/rust.svg" alt="Rust"/>Rust</a>
15+
<a class="card-grid-item"><img src="/site/language-logos/php.svg" alt="PHP"/>PHP</a>
16+
<a href="https://github.com/testcontainers/testcontainers-scala/" class="card-grid-item"><img style="width:30px; height:30px" src="/site/language-logos/scala.svg" alt="Scala"/>Scala</a>
17+
</div>
18+
19+
## About
20+
21+
Testcontainers for PHP is a composer package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.
22+
23+
## Documentation
24+
25+
- [Install](quickstart/install.md)
26+
- [Usage](quickstart/usage.md)
27+
- [Containers](features/containers.md)
28+
- [Wait strategies](features/wait-strategies.md)
29+
- [Networking](features/networking.md)
30+
- [Modules](modules/redis.md)
31+
- [Configuration](configuration.md)
32+
- [Troubleshooting](troubleshooting.md)
33+
34+
## License
35+
36+
This project is open source and you can have a look at the code on [GitHub](https://github.com/testcontainers/testcontainers-php). See [LICENSE](https://raw.githubusercontent.com/testcontainers/testcontainers-php/main/LICENSE).
37+
38+
## Copyright
39+
40+
Copyright (c) 2022-present Soner Sayakci, Sergei Shitikov and other authors. Check out our [lovely contributors](https://github.com/testcontainers/testcontainers-php/graphs/contributors).
41+
42+
---
43+
44+
Join our [Slack workspace](https://slack.testcontainers.org/) | [Testcontainers OSS](https://java.testcontainers.org/) | [Testcontainers Cloud](https://www.testcontainers.cloud/)

0 commit comments

Comments
 (0)