Docker::create(). Both support connection
settings directly in PHP; environment variables are optional.
Choosing a client
The bundled client needs little setup and includes Docker’s streaming decoder.
Guzzle provides its own middleware and familiar HTTP/TLS options, which can be
useful if your application already uses it. Choose based on the operations you
need and the transport you want to configure. Attach and WebSocket calls have
additional wrapper limitations
regardless of which client you use.
Bundled socket client
Without connection environment variables, this connects to/var/run/docker.sock:
Default socket
Bundled custom socket
false because this factory already configures the API
path. For HTTP, HTTPS and certificate examples, see
connection settings.
The factory negotiates the API version with the daemon. To fix a version, add
the api_version option; see API versions.
DockerClientFactory includes StreamingDecoderPlugin automatically. If you
build your own socket client and plugin chain, see
custom socket clients.
Guzzle
Install Guzzle in your application:Custom Unix socket
Guzzle Unix socket
base_uri supplies the HTTP hostname; CURLOPT_UNIX_SOCKET_PATH selects the
socket using a filesystem path, without unix://. Docker PHP keeps these
options when wrapping the supplied client.
For a TCP daemon over HTTP, change base_uri to
http://docker.example.com:2375 and remove the curl option. Guzzle expects
http:// or https://, not tcp://.
HTTPS and mutual TLS
Guzzle HTTPS
verify selects the CA used to verify the server. The certificate must also
match the hostname. Omit cert and ssl_key if the daemon does not require a
client certificate. For a publicly trusted server certificate, omit verify
to use Guzzle’s default trust configuration. Keep private keys outside source
control, and do not disable certificate verification to bypass errors.
Paths, timeouts and streaming
Use the daemon’s root URL forbase_uri, without a version such as /v1.57.
These Guzzle examples keep the generated server plugins enabled, so Docker PHP
adds the installed API line’s path. Guzzle clients do not negotiate, and
DOCKER_API_VERSION only configures the bundled factory, so install an
API line your daemon supports. Do not copy the bundled example’s fourth argument (false) into
these examples.
The empty proxy option disables HTTP proxy environment settings. Configure
a proxy explicitly if needed. The ten-second timeout is for ordinary calls;
adjust it for builds, transfers or other long-running operations.
The cURL handler buffers response bodies even with stream => true. Completed
logs can still be decoded, but following logs or subscribing to events can
wait indefinitely or hit the timeout before returning output. Guzzle’s PHP
stream handler can read incrementally, but cannot connect to a Unix socket:
Guzzle 7 ignores the curl option on that handler and Guzzle 8 rejects it.
Changing handlers changes which options work.
StreamingDecoderPlugin handles decoding after the transport returns a
response. It cannot remove buffering inside Guzzle’s cURL handler. If you
choose a custom transport for live streams or upgraded exec/attach connections,
test those operations with it. PSR-18 compatibility alone does not guarantee
unbuffered reads or a writable upgraded connection. See
streaming.
For more options, see Guzzle’s
request options
and handlers.