Skip to main content
These calls need more than the usual request-model/response-model pattern. The table applies to every supported API line.

Callback streams

Register callbacks before calling wait(). The endpoint call obtains the response; wait() reads its body and invokes callbacks synchronously. Registering a callback alone does not consume output or finish the operation. onFrame() receives generated models for build, pull, push and event streams, and decoded objects for stats streams. Their responses contain multiple JSON documents, not one JSON array. onStdout() and onStderr() receive strings for logs and exec output. See output framing for the difference between output chunks and lines. Do not decode a whole progress stream with one json_decode() call. Check Docker\Stream\FrameError::message($frame) on every build, pull or push frame: HTTP 200 means the stream opened, not that the operation succeeded. The helper reads whichever error field the installed API line has.

Custom socket clients

DockerClientFactory::create() and Docker::create() without a supplied client already use Docker\Http\StreamingDecoderPlugin. You do not need to add it when using the bundled factory. If you build a socket client and its plugin chain yourself, use this plugin in place of Http\Client\Common\Plugin\DecoderPlugin. It decodes HTTP chunked responses incrementally and adapts socket reads so TTY output can arrive before the stream finishes:
Custom socket client
The generated server plugin supplies the installed API line’s path, such as /v1.57, in this example. If your custom chain already supplies the versioned path, disable the server plugins with Docker::create($httpClient, [], [], false) to avoid configuring it twice. Docker::create($httpClient) does not replace an existing client’s decoder. The streaming plugin handles HTTP transfer decoding, not Docker’s stdout/stderr frames, and cannot undo buffering inside another HTTP transport. In particular, adding it to Guzzle’s cURL handler does not make that handler stream responses. See HTTP clients for the transport comparison.

Lifetime, cancellation and timeouts

wait() blocks until the stream ends, stop() is called or an error interrupts it. A log follow or event subscription can remain open indefinitely. The client does not turn these calls into background jobs, promises or an event loop. Use bounded event queries for batch jobs. Set transport timeouts appropriate to the operation, and keep long-lived readers in a supervised worker rather than an ordinary web request. Reconnect and reconcile state in your application after a connection failure; there is no automatic durable event subscription. Call stop() on a callback stream to close its body and end wait(). From inside a frame callback, wait() returns after that frame’s callbacks have run. stop() requires 3.3.0 or later. Do not treat CallbackStream::closeAndRead() as a graceful stop signal: it closes the underlying body before calling wait(). For explicit stream ownership, use a raw endpoint, manage its PSR-7 body and close it in a finally block. Closing a build or pull connection can cancel the daemon operation.

Raw and generated endpoints

Docker\Docker’s convenience methods select the custom endpoint wrappers. Calling executeEndpoint(new Docker\API\Endpoint\SystemEvents(...)) directly selects the generated endpoint, not the event-stream wrapper. Likewise, a raw endpoint returns bytes and headers without either wrapper’s decoding. Choose deliberately between:
  • A Docker\Docker convenience method for supported callback streams.
  • A generated endpoint with executeRawEndpoint() for tar bodies, headers or streams that your application decodes itself.
See Requests and responses for status checks and raw-fetch error handling.

Attach and WebSocket limitations

containerAttach() attaches to the container’s existing process; it does not create a new command like containerExec() followed by execStart(). containerAttach() returns a DockerRawStream for plain and upgraded responses. Docker labels TTY output and framed non-TTY output on plain responses with the same content type, so the client inspects the container’s TTY setting to choose the decoder. TTY output arrives through onStdout(). Since 3.3.0, attaching to a TTY container no longer loses its output. containerAttachWebsocket() returns an AttachWebsocketStream with read(), write() and close(), not onStdout()/wait(). It is useful when you need to write to the container’s stdin over the attach connection:
read() waits up to the given seconds and microseconds for one frame. It returns the frame’s bytes, false when nothing arrived in time, or null once Docker has closed the connection. A frame is a chunk of output, not a line. Docker mixes stdout and stderr in the same frames, with no marker for which stream a chunk came from. The stream answers pings and closes itself when Docker sends a close frame. write() sends one binary frame. WebSocket attach needs 3.3.0 or later; earlier clients returned null instead of a stream. Docker Desktop’s socket proxy upgrades the connection but does not forward attach output; a Linux daemon or a remote engine works. For driving commands, interactive exec gives separate stdout and stderr, exit codes and deadlines. DockerRawStream::onStdin() is an output-channel callback; it is not a method for writing commands into a container. Prefer the exec recipe for non-interactive command execution.