GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — docs: document the 4.0 client · docker-php/docker-php@3df8a61

File tree

Expand file treeCollapse file tree

Open diff view settings

Filter options

CONTRIBUTING.md
DOCUMENTATION.md
README.md
docs
- api-versions.mdx
- connection.mdx
- contributing.mdx
- cookbook
  - build-image.mdx
  - container-run.mdx
- guides
- index.mdx
- installation.mdx
- migration.mdx
- reference
  - requests-and-responses.mdx
  - streams.mdx

Expand file treeCollapse file tree

Open diff view settings

Collapse file

`‎CONTRIBUTING.md‎`

Copy file name to clipboardExpand all lines: CONTRIBUTING.md

+1-1Lines changed: 1 addition & 1 deletion

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -69,7 +69,7 @@ $ git push -f origin feature-or-bug-fix-description`
`69`	`69`
`70`	`70`	`## Documentation`
`71`	`71`
`72`		-Documentation for the 3.0 release lives in `docs/` and uses Mintlify.
	`72`	+Documentation for the 4.0 release lives in `docs/` and uses Mintlify.
`73`	`73`	`See [DOCUMENTATION.md](DOCUMENTATION.md) for the local preview, validation commands`
`74`	`74`	`and hosted setup. Test examples against a development Docker daemon, and keep`
`75`	`75`	`instructions for unreleased packages clearly marked.`

Collapse file

`‎DOCUMENTATION.md‎`

Copy file name to clipboardExpand all lines: DOCUMENTATION.md

+2-2Lines changed: 2 additions & 2 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`# Documentation development`
`2`	`2`
`3`		-The Docker PHP 3.0 documentation uses Mintlify. Its source lives in `docs/` in
	`3`	+The Docker PHP 4.0 documentation uses Mintlify. Its source lives in `docs/` in
`4`	`4`	`this repository, alongside the client code. This replaces the legacy MkDocs`
`5`	`5`	`configuration; earlier documentation remains available in Git history.`
`6`	`6`
`@@ -89,7 +89,7 @@ review the draft and confirm the destination before doing that.`
`89`	`89`
`90`	`90`	`## Before publishing package releases`
`91`	`91`
`92`		`-- Review the v3.0 migration instructions and test their examples.`
	`92`	`+- Review the 4.0 migration instructions and test their examples.`
`93`	`93`	`- Confirm the connected repository, branch and docs path.`
`94`	`94`	`- Check the hosted site's navigation, mobile layout and internal links.`
`95`	`95`	`- Configure a custom documentation hostname and DNS separately if needed.`

Collapse file

`‎README.md‎`

Copy file name to clipboardExpand all lines: README.md

+43-38Lines changed: 43 additions & 38 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ This library aims to reach 100% API support of the Docker Engine.`
`11`	`11`
`12`	`12`	`## Documentation`
`13`	`13`
`14`		`-The [version 3.x documentation](https://docker-php.mintlify.site/) is available.`
	`14`	`+The [version 4.x documentation](https://docker-php.mintlify.site/) is available.`
`15`	`15`	`Its source lives in`
`16`	`16`	`[docs/](docs/); see [DOCUMENTATION.md](DOCUMENTATION.md) to preview and edit it`
`17`	`17`	`locally. The [legacy documentation](https://docker-php.readthedocs.io/en/latest/)`
@@ -28,25 +28,24 @@ maintenance of the original `docker-php/docker-php` repository to give you a
`28`	`28`	`better upgrade path. Development will continue here, and we will archive`
`29`	`29`	`beluga-php/docker-php` once the migration is complete.
`30`	`30`
`31`		`-Version 3.0 targets Docker Engine API v1.45. We plan`
`32`		`-to add the missing API versions and bring support up to the latest Docker Engine`
`33`		`-API. See [Upgrading to 3.0](#upgrading-to-30) below for how to migrate from`
`34`		`-existing releases.`
	`31`	`+Version 4.0 works with Docker Engine API v1.45 to v1.56. See`
	`32`	`+[Upgrading to 4.0](#upgrading-to-40) below for how to migrate from existing`
	`33`	`+releases.`
`35`	`34`
`36`	`35`	`## Requirements`
`37`	`36`
`38`	`37`	- PHP 8.1 or later, with the `mbstring` extension.
`39`	`38`	`- [Composer](https://getcomposer.org/).`
`40`		`-- Access to a Docker daemon that accepts API v1.45 requests.`
	`39`	`+- Access to a Docker daemon with API v1.45 or later (Docker Engine 26.0 or later).`
`41`	`40`
`42`	`41`	`## Installation`
`43`	`42`
`44`	`43`	```bash
`45`		`-composer require "docker-php/docker-php:^3.0"`
	`44`	`+composer require "docker-php/docker-php:^4.0"`
`46`	`45`	```
`47`	`46`
`48`		-Composer installs `docker-php/docker-php-api` as a dependency. The 3.0 release
`49`		`-targets Docker API v1.45 and requires the matching generated API package.`
	`47`	+Composer also installs `docker-php/docker-php-api`, choosing the newest API line
	`48`	`+unless you require one. See [Docker API versions](#docker-api-versions).`
`50`	`49`
`51`	`50`	`## Usage`
`52`	`51`
`@@ -79,58 +78,64 @@ These guides cover callback streams, TTY output and raw response framing.`
`79`	`78`
`80`	`79`	`## Docker API versions`
`81`	`80`
`82`		`-See the official [Docker Engine API v1.45 reference](https://docs.docker.com/reference/api/engine/version/v1.45/)`
`83`		`-for endpoint descriptions, parameters and response schemas matching this API line.`
	`81`	+Each Docker Engine API version has its own `docker-php/docker-php-api` line with
	`82`	`+generated endpoints and models. The line uses the four-part version`
	`83`	+`Jane-major.Docker-major.Docker-minor.revision`: `7.1.56.0` means Docker API 1.56,
	`84`	`+generated with Jane 7, revision 0. To use a specific version, require its line:`
`84`	`85`
`85`		`-The client package follows semantic versioning. The generated API package uses`
`86`		-`Jane-major.Docker-major.Docker-minor.revision`: `7.1.45.0` means Docker API 1.45,
`87`		`-generated with Jane 7, revision 0.`
`88`		`-`
`89`		`-Keep generated API dependencies within one Docker specification. The`
`90`		`-3.0 client uses this range:`
`91`		`-`
`92`		-```json
`93`		`-"docker-php/docker-php-api": ">=7.1.45.0 <7.1.46.0"`
	`86`	+```bash
	`87`	`+composer require "docker-php/docker-php:^4.0" "docker-php/docker-php-api:>=7.1.51.0 <7.1.52.0"`
`94`	`88`	```
`95`	`89`
`96`		-With the default connection factory, `DOCKER_API_VERSION` overrides the version
`97`		`-in request URLs:`
	`90`	`+Pin a line if your code names generated models or calls methods that differ`
	`91`	`+between versions. See the official`
	`92`	`+[Docker Engine API reference](https://docs.docker.com/reference/api/engine/) for`
	`93`	`+each version's endpoints, parameters and response schemas.`
`98`	`94`
`99`		-```bash
`100`		`-DOCKER_API_VERSION=1.52 php your-script.php`
`101`		-```
	`95`	`+The bundled connection factory negotiates the version in request URLs: it uses`
	`96`	`+the lower of the installed line and the daemon's maximum API version, as the`
	`97`	+Docker CLI does. `DOCKER_API_VERSION` or the factory's `api_version` option fix
	`98`	`+the version instead. Changing the URL version does not change the generated`
	`99`	`+models. See [API versions](https://docker-php.mintlify.site/api-versions).`
	`100`	`+`
	`101`	`+## Upgrading to 4.0`
`102`	`102`
`103`		-Since 3.1.0, the factory's `api_version` option can pin the request version
`104`		-directly in PHP. It takes precedence over `DOCKER_API_VERSION`. See
`105`		`-[connection settings](https://docker-php.mintlify.site/connection#factory-options).`
	`103`	`+### From docker-php 3.x`
`106`	`104`
`107`		`-The generated endpoints and models still describe API v1.45. Changing the URL`
`108`		`-version does not add newer API fields or endpoints. The client does not`
`109`		`-automatically negotiate an API version with the daemon.`
	`105`	`+- Composer now installs the newest API line unless you require one. Require`
	`106`	+ `docker-php/docker-php-api:>=7.1.45.0 <7.1.46.0` to keep the 3.x models.
	`107`	`+- Requests negotiate the API version with the daemon unless you set one.`
	`108`	`+- Error statuses the generated endpoints do not handle throw an`
	`109`	+ `UnexpectedStatusCodeException`. Call `throwOnUnexpectedStatus(false)` to
	`110`	+ return `null` instead.
	`111`	+- `Context` applies `.dockerignore`. Call `applyDockerignore(false)` to archive
	`112`	`+ the whole directory.`
`110`	`113`
`111`		`-## Upgrading to 3.0`
	`114`	+Applications that cannot upgrade yet can stay on `^3.3`. See the
	`115`	`+[upgrade guide](https://docker-php.mintlify.site/migration#from-3-x) for model`
	`116`	`+changes between API versions.`
`112`	`117`
`113`	`118`	`### From docker-php 2.x`
`114`	`119`
`115`		`-Version 3.0 requires PHP 8.1 or later, PSR-7 v2 and Jane 7-generated models.`
	`120`	`+Version 4.0 requires PHP 8.1 or later, PSR-7 v2 and Jane 7-generated models.`
`116`	`121`	`Review endpoint signatures, model types and HTTP client dependencies before`
`117`	`122`	`upgrading. Check log and exec consumers against the`
`118`	`123`	`[streaming documentation](https://docker-php.mintlify.site/reference/streams).`
`119`	`124`
`120`		-Change the client requirement to `docker-php/docker-php:^3.0`. Remove an explicit
`121`		-`docker-php/docker-php-api:4.1.*` requirement, or change it to the API 1.45 range
	`125`	+Change the client requirement to `docker-php/docker-php:^4.0`. Remove an explicit
	`126`	+`docker-php/docker-php-api:4.1.*` requirement, or change it to one API line as
`122`	`127`	`shown above. Update dependencies, test your application and commit its updated`
`123`	`128`	`composer.lock`.
`124`	`129`
`125`	`130`	`### From beluga-php`
`126`	`131`
`127`		-Version 3.0 continues the client maintained under `beluga-php/docker-php`.
	`132`	+Version 4.0 continues the client maintained under `beluga-php/docker-php`.
`128`	`133`	The PHP namespaces remain `Docker` and `Docker\API`.
`129`	`134`
`130`	`135`	Remove the `beluga-php/docker-php` requirement and any explicit
`131`	`136`	`beluga-php/docker-php-api` requirement from `composer.json`. Add
`132`		-`docker-php/docker-php:^3.0`; add the API 1.45 range above if your application
`133`		`-requires the generated API package directly. Resolve the package changes`
	`137`	+`docker-php/docker-php:^4.0`; to keep the Beluga v1.45 models, also require
	`138`	+`docker-php/docker-php-api:>=7.1.45.0 <7.1.46.0`. Resolve the package changes
`134`	`139`	together, then test the application and commit its updated `composer.lock`.
`135`	`140`
`136`	`141`	`Install one package family at a time: the Beluga and original packages contain`

Collapse file

`‎docs/api-versions.mdx‎`

Copy file name to clipboardExpand all lines: docs/api-versions.mdx

+50-48Lines changed: 50 additions & 48 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -1,53 +1,57 @@`
`1`	`1`	`---`
`2`	`2`	`title: "API versions"`
`3`		`-description: "Pin generated models to one Docker Engine API specification."`
	`3`	`+description: "Choose a Docker Engine API version and how requests negotiate with the daemon."`
`4`	`4`	`---`
`5`	`5`
`6`		`-## Docker Engine API reference`
	`6`	`+## Choose an API version`
`7`	`7`
`8`		`-The official [Docker Engine API v1.45 reference](https://docs.docker.com/reference/api/engine/version/v1.45/)`
`9`		`-describes the endpoints, parameters and response schemas used by this API line.`
`10`		`-Use it alongside these PHP examples; generated method signatures and model`
`11`		`-setters describe how to pass those values in PHP.`
	`8`	`+Docker PHP 4.0 works with Docker Engine API v1.45 to v1.56. Each version has its`
	`9`	+own `docker-php/docker-php-api` release line with generated endpoints and
	`10`	`+models. Without a direct API requirement, Composer installs the newest line.`
`12`	`11`
`13`		`-## Two package versions`
	`12`	`+To use a specific version, require its line next to the client:`
`14`	`13`
`15`		-`docker-php/docker-php` follows semantic versioning. Its 3.0 release
`16`		`-targets Docker Engine API v1.45.`
`17`		`-`
`18`		-`docker-php/docker-php-api` uses a four-part scheme:
`19`		-`Jane-major.Docker-major.Docker-minor.revision`. For example, `7.1.45.0` means
`20`		`-Docker Engine API v1.45, generated with Jane 7, revision 0. It is not the version`
`21`		`-of the high-level client.`
`22`		`-`
`23`		`-Keep generated API requirements within one specification:`
`24`		`-`
`25`		-```json
`26`		`-{`
`27`		`- "require": {`
`28`		`- "docker-php/docker-php": "^3.0",`
`29`		`- "docker-php/docker-php-api": ">=7.1.45.0 <7.1.46.0"`
`30`		`- }`
`31`		`-}`
	`14`	+```bash
	`15`	`+composer require "docker-php/docker-php:^4.0" "docker-php/docker-php-api:>=7.1.51.0 <7.1.52.0"`
`32`	`16`	```
`33`	`17`
`34`		`-The client already requires that API range. Add a direct API requirement only`
`35`		-if your application needs one. Avoid broad API constraints such as `^7.1.45.0`:
`36`		`-they also allow other Docker specifications.`
	`18`	`+Pin a line if your code names generated models or calls methods that differ`
	`19`	`+between versions. Docker renames models and changes fields between API versions;`
	`20`	+for example, API 1.48 replaced `ContainersIdJsonGetResponse200` with
	`21`	+`ContainerInspectResponse`, and API 1.52 removed `getError()` from build, pull and
	`22`	`+push progress frames. Check Docker's`
	`23`	`+[API version history](https://docs.docker.com/reference/api/engine/version-history/)`
	`24`	`+and the [Docker Engine API reference](https://docs.docker.com/reference/api/engine/)`
	`25`	`+for the version you use.`
	`26`	`+`
	`27`	`+## Package versions`
	`28`	`+`
	`29`	+`docker-php/docker-php` follows semantic versioning.
	`30`	`+`
	`31`	+`docker-php/docker-php-api` uses a four-part scheme:
	`32`	+`Jane-major.Docker-major.Docker-minor.revision`. For example, `7.1.56.0` means
	`33`	`+Docker Engine API v1.56, generated with Jane 7, revision 0. Keep a direct API`
	`34`	+requirement within one line, as above. A constraint such as `^7.1.45.0` allows
	`35`	`+every newer Docker specification.`
`37`	`36`
`38`	`37`	`## Request URL version`
`39`	`38`
`40`		-The default factory uses `/v1.45` in request URLs. `DOCKER_API_VERSION` can
`41`		`-override the URL version:`
	`39`	`+The bundled factory negotiates the version in request URLs. Before the first`
	`40`	+request it sends an unversioned `/_ping` and reads the daemon's maximum API
	`41`	`+version from the response. Requests then use the lower of that version and the`
	`42`	`+installed API line, as the Docker CLI does. An older daemon keeps working with a`
	`43`	`+newer API package, and requests never ask for a version the installed models do`
	`44`	+not describe. `DockerClientFactory::defaultApiVersion()` returns the installed
	`45`	`+line's version.`
	`46`	`+`
	`47`	+To skip negotiation, set the version yourself. `DOCKER_API_VERSION` sets it from
	`48`	`+the environment:`
`42`	`49`
`43`	`50`	```bash
`44`		`-DOCKER_API_VERSION=1.45 php your-script.php`
	`51`	`+DOCKER_API_VERSION=1.51 php your-script.php`
`45`	`52`	```
`46`	`53`
`47`		-Both `1.45` and `v1.45` are accepted. Choose a version supported by your daemon
`48`		`-and compatible with the endpoints you use.`
`49`		`-`
`50`		`-Since client 3.1.0, you can pin the request version directly in PHP:`
	`54`	+The factory's `api_version` option sets it in PHP and overrides the environment:
`51`	`55`
`52`	`56`	```php
`53`	`57`	`<?php`
`@@ -57,29 +61,27 @@ use Docker\DockerClientFactory;`
`57`	`61`
`58`	`62`	`$httpClient = DockerClientFactory::create([`
`59`	`63`	`'remote_socket' => 'unix:///var/run/docker.sock',`
`60`		`- 'api_version' => '1.45',`
	`64`	`+ 'api_version' => '1.51',`
`61`	`65`	`]);`
`62`	`66`	`$docker = Docker::create($httpClient, [], [], false);`
`63`	`67`	```
`64`	`68`
`65`		-An explicit `api_version` overrides `DOCKER_API_VERSION`. Without it, the
`66`		`-environment setting and default remain unchanged. The fourth argument disables`
`67`		`-the generated server plugins because the factory already adds the API path.`
	`69`	+Both `1.51` and `v1.51` are accepted. The fourth argument disables the generated
	`70`	`+server plugins because the factory already adds the API path.`
	`71`	`+`
	`72`	`+A client you build yourself, such as [Guzzle](/guides/guzzle), does not negotiate.`
	`73`	`+The generated server plugins prefix requests with the installed line's version,`
	`74`	`+so install a line your daemon supports.`
`68`	`75`
`69`	`76`	`<Warning>`
`70`	`77`	`Changing the URL version does not regenerate models or add newer fields and`
`71`		`-endpoints. The client does not automatically negotiate an API version with the`
`72`		`-daemon.`
	`78`	`+endpoints. With an older daemon, fields added after its API version are absent`
	`79`	`+from responses and ignored in requests.`
`73`	`80`	`</Warning>`
`74`	`81`
`75`	`82`	`## Generated code`
`76`	`83`
`77`		`-The API repository contains the`
`78`		`-[v1.45 specification](https://github.com/docker-php/docker-php-api/blob/main/spec/v1.45.json)`
`79`		`-and [Jane configuration](https://github.com/docker-php/docker-php-api/blob/main/.jane-openapi).`
`80`		`-Generation requires Jane 7.14.4 or later within the Jane 7 release line and`
`81`		`-uses upstream output without local patches. See the`
	`84`	`+Each line is generated from Docker's specification for that version with Jane`
	`85`	`+7.14.4, without local patches. The API repository has one branch per line,`
	`86`	+such as [`7.1.56`](https://github.com/docker-php/docker-php-api/tree/7.1.56); see its
`82`	`87`	`[generation instructions](https://github.com/docker-php/docker-php-api#generation).`
`83`		`-`
`84`		`-Newer API lines will need their own generated code and compatible client`
`85`		`-requirements. They are separate work after the initial restored release.`

Collapse file

`‎docs/connection.mdx‎`

Copy file name to clipboardExpand all lines: docs/connection.mdx

+6-5Lines changed: 6 additions & 5 deletions

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -86,7 +86,7 @@ use Docker\DockerClientFactory;`
`86`	`86`
`87`	`87`	`$httpClient = DockerClientFactory::create([`
`88`	`88`	`'remote_socket' => 'unix:///var/run/docker.sock',`
`89`		`- 'api_version' => '1.45',`
	`89`	`+ 'api_version' => '1.51',`
`90`	`90`	`'timeout' => 10000,`
`91`	`91`	`]);`
`92`	`92`
`@@ -98,10 +98,11 @@ adds the daemon address and versioned path. See`
`98`	`98`	`[the factory implementation](https://github.com/docker-php/docker-php/blob/main/src/DockerClientFactory.php)`
`99`	`99`	`for the plugins it configures.`
`100`	`100`
`101`		-`api_version` pins the request path in PHP, even if `DOCKER_API_VERSION` is set
`102`		-on the process. It accepts `1.45`, `v1.45` or `/v1.45`. If omitted, the factory
`103`		-uses `DOCKER_API_VERSION`, falling back to `1.45`. The timeout is in milliseconds.
`104`		-The `api_version` option requires client `3.1.0` or later.
	`101`	+`api_version` fixes the request path in PHP, even if `DOCKER_API_VERSION` is set
	`102`	+on the process. It accepts `1.51`, `v1.51` or `/v1.51`. If omitted, the factory
	`103`	+uses `DOCKER_API_VERSION`; without either, it
	`104`	`+[negotiates](/api-versions#request-url-version) with the daemon. The timeout is`
	`105`	`+in milliseconds.`
`105`	`106`
`106`	`107`	`For a private CA without client certificates, pass the CA file directly:`
`107`	`108`

Collapse file

`‎docs/contributing.mdx‎`

Copy file name to clipboardExpand all lines: docs/contributing.mdx

+1-1Lines changed: 1 addition & 1 deletion

Display the source diff
Display the rich diff

Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ keep examples aligned with the current API models. Do not edit generated API`
`49`	`49`	`code to make an example work.`
`50`	`50`
`51`	`51`	`Keep unreleased instructions clearly marked until their packages are published.`
`52`		-Avoid documenting legacy `DockerAsync` behavior as part of 3.0.
	`52`	+Avoid documenting legacy `DockerAsync` behavior as part of 4.0.
`53`	`53`
`54`	`54`	`## Pull requests`
`55`	`55`

0 commit comments

Comments

0 (0)

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.