Skip to main content
Docker PHP uses its bundled socket client by default. You can also pass a configured Guzzle 7 or 8 client to 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
To set a custom socket and a ten-second timeout directly in PHP:
Bundled custom socket
The fourth argument is 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:
These examples use an explicit cURL handler for Unix-socket and client-key support. The PHP process must have permission to access the socket or certificate files.

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.
Access to a Docker daemon is privileged. Plain HTTP is unencrypted; do not expose an unauthenticated daemon to an untrusted network.

Paths, timeouts and streaming

Use the daemon’s root URL for base_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.