Callback streams
Register callbacks before callingwait(). 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
/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\Dockerconvenience method for supported callback streams. - A generated endpoint with
executeRawEndpoint()for tar bodies, headers or streams that your application decodes itself.
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.