Skip to content

Commit 950f8cd

Browse files
clueclue
committed
Documentation for public APIs
1 parent 360903b commit 950f8cd

3 files changed

Lines changed: 61 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,13 @@ $loop = React\EventLoop\Factory::create();
6767
$factory = new Factory($loop);
6868
```
6969

70+
If you need custom DNS, SSL/TLS or proxy settings, you can explicitly pass a
71+
custom [`Browser`](https://github.com/clue/php-buzz-react#browser) instance:
72+
73+
```php
74+
$factory = new Factory($loop, $browser);
75+
```
76+
7077
#### createClient()
7178

7279
The `createClient($url = null)` method can be used to create a new `Client`.

‎src/Client.php‎

Lines changed: 32 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,13 @@
44

55
use Clue\React\Buzz\Browser;
66
use Clue\React\Docker\Io\ResponseParser;
7-
use React\Promise\PromiseInterface as Promise;
7+
use React\Promise\PromiseInterface;
88
use Clue\React\Docker\Io\StreamingParser;
99
use React\Stream\ReadableStreamInterface;
1010
use Rize\UriTemplate;
1111

1212
/**
13-
* Docker Remote API client
14-
*
15-
* The Remote API can be used to control your local Docker daemon.
13+
* The Docker Remote API client can be used to control your (local) Docker daemon.
1614
*
1715
* This Client implementation provides a very thin wrapper around this
1816
* Remote API and exposes its exact data models.
@@ -65,7 +63,7 @@ public function __construct(Browser $browser, ResponseParser $parser = null, Str
6563
/**
6664
* Ping the docker server
6765
*
68-
* @return Promise Promise<string> "OK"
66+
* @return PromiseInterface Promise<string> "OK"
6967
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#ping-the-docker-server
7068
*/
7169
public function ping()
@@ -76,7 +74,7 @@ public function ping()
7674
/**
7775
* Display system-wide information
7876
*
79-
* @return Promise Promise<array> system info (see link)
77+
* @return PromiseInterface Promise<array> system info (see link)
8078
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#display-system-wide-information
8179
*/
8280
public function info()
@@ -87,7 +85,7 @@ public function info()
8785
/**
8886
* Show the docker version information
8987
*
90-
* @return Promise Promise<array> version info (see link)
88+
* @return PromiseInterface Promise<array> version info (see link)
9189
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#show-the-docker-version-information
9290
*/
9391
public function version()
@@ -100,7 +98,7 @@ public function version()
10098
*
10199
* @param boolean $all
102100
* @param boolean $size
103-
* @return Promise Promise<array> list of container objects
101+
* @return PromiseInterface Promise<array> list of container objects
104102
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#list-containers
105103
*/
106104
public function containerList($all = false, $size = false)
@@ -121,7 +119,7 @@ public function containerList($all = false, $size = false)
121119
*
122120
* @param array $config e.g. `array('Image' => 'busybox', 'Cmd' => 'date')` (see link)
123121
* @param string|null $name (optional) name to assign to this container
124-
* @return Promise Promise<array> container properties `array('Id' => $containerId', 'Warnings' => array())`
122+
* @return PromiseInterface Promise<array> container properties `array('Id' => $containerId', 'Warnings' => array())`
125123
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#create-a-container
126124
*/
127125
public function containerCreate($config, $name = null)
@@ -141,7 +139,7 @@ public function containerCreate($config, $name = null)
141139
* Return low-level information on the container id
142140
*
143141
* @param string $container container ID
144-
* @return Promise Promise<array> container properties
142+
* @return PromiseInterface Promise<array> container properties
145143
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#inspect-a-container
146144
*/
147145
public function containerInspect($container)
@@ -161,7 +159,7 @@ public function containerInspect($container)
161159
*
162160
* @param string $container container ID
163161
* @param string|null $ps_args (optional) ps arguments to use (e.g. aux)
164-
* @return Promise Promise<array>
162+
* @return PromiseInterface Promise<array>
165163
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#list-processes-running-inside-a-container
166164
*/
167165
public function containerTop($container, $ps_args = null)
@@ -181,7 +179,7 @@ public function containerTop($container, $ps_args = null)
181179
* Inspect changes on container id's filesystem
182180
*
183181
* @param string $container container ID
184-
* @return Promise Promise<array>
182+
* @return PromiseInterface Promise<array>
185183
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#inspect-changes-on-a-containers-filesystem
186184
*/
187185
public function containerChanges($container)
@@ -211,7 +209,7 @@ public function containerChanges($container)
211209
* work is clue/tar-react (see links).
212210
*
213211
* @param string $container container ID
214-
* @return Promise Promise<string> tar stream
212+
* @return PromiseInterface Promise<string> tar stream
215213
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#export-a-container
216214
* @link https://github.com/clue/php-tar-react library clue/tar-react
217215
* @see self::containerExportStream()
@@ -270,7 +268,7 @@ public function containerExportStream($container)
270268
* @param string $container container ID
271269
* @param int $w TTY width
272270
* @param int $h TTY height
273-
* @return Promise Promise<null>
271+
* @return PromiseInterface Promise<null>
274272
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#resize-a-container-tty
275273
*/
276274
public function containerResize($container, $w, $h)
@@ -292,7 +290,7 @@ public function containerResize($container, $w, $h)
292290
*
293291
* @param string $container container ID
294292
* @param array $config (optional) start config (see link)
295-
* @return Promise Promise<null>
293+
* @return PromiseInterface Promise<null>
296294
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#start-a-container
297295
*/
298296
public function containerStart($container, $config = array())
@@ -313,7 +311,7 @@ public function containerStart($container, $config = array())
313311
*
314312
* @param string $container container ID
315313
* @param null|int $t (optional) number of seconds to wait before killing the container
316-
* @return Promise Promise<null>
314+
* @return PromiseInterface Promise<null>
317315
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#stop-a-container
318316
*/
319317
public function containerStop($container, $t = null)
@@ -334,7 +332,7 @@ public function containerStop($container, $t = null)
334332
*
335333
* @param string $container container ID
336334
* @param null|int $t (optional) number of seconds to wait before killing the container
337-
* @return Promise Promise<null>
335+
* @return PromiseInterface Promise<null>
338336
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#restart-a-container
339337
*/
340338
public function containerRestart($container, $t = null)
@@ -355,7 +353,7 @@ public function containerRestart($container, $t = null)
355353
*
356354
* @param string $container container ID
357355
* @param string|int|null $signal (optional) signal name or number
358-
* @return Promise Promise<null>
356+
* @return PromiseInterface Promise<null>
359357
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#kill-a-container
360358
*/
361359
public function containerKill($container, $signal = null)
@@ -375,7 +373,7 @@ public function containerKill($container, $signal = null)
375373
* Pause the container id
376374
*
377375
* @param string $container container ID
378-
* @return Promise Promise<null>
376+
* @return PromiseInterface Promise<null>
379377
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#pause-a-container
380378
*/
381379
public function containerPause($container)
@@ -394,7 +392,7 @@ public function containerPause($container)
394392
* Unpause the container id
395393
*
396394
* @param string $container container ID
397-
* @return Promise Promise<null>
395+
* @return PromiseInterface Promise<null>
398396
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#unpause-a-container
399397
*/
400398
public function containerUnpause($container)
@@ -413,7 +411,7 @@ public function containerUnpause($container)
413411
* Block until container id stops, then returns the exit code
414412
*
415413
* @param string $container container ID
416-
* @return Promise Promise<array> `array('StatusCode' => 0)` (see link)
414+
* @return PromiseInterface Promise<array> `array('StatusCode' => 0)` (see link)
417415
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#wait-a-container
418416
*/
419417
public function containerWait($container)
@@ -434,7 +432,7 @@ public function containerWait($container)
434432
* @param string $container container ID
435433
* @param boolean $v Remove the volumes associated to the container. Default false
436434
* @param boolean $force Kill then remove the container. Default false
437-
* @return Promise Promise<null>
435+
* @return PromiseInterface Promise<null>
438436
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#remove-a-container
439437
*/
440438
public function containerRemove($container, $v = false, $force = false)
@@ -467,7 +465,7 @@ public function containerRemove($container, $v = false, $force = false)
467465
*
468466
* @param string $container container ID
469467
* @param array $config resources to copy `array('Resource' => 'file.txt')` (see link)
470-
* @return Promise Promise<string> tar stream
468+
* @return PromiseInterface Promise<string> tar stream
471469
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#copy-files-or-folders-from-a-container
472470
* @link https://github.com/clue/php-tar-react library clue/tar-react
473471
* @see self::containerCopyStream()
@@ -530,7 +528,7 @@ public function containerCopyStream($container, $config)
530528
* List images
531529
*
532530
* @param boolean $all
533-
* @return Promise Promise<array> list of image objects
531+
* @return PromiseInterface Promise<array> list of image objects
534532
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#list-images
535533
* @todo support $filters param
536534
*/
@@ -565,7 +563,7 @@ public function imageList($all = false)
565563
* @param string|null $tag (optional) (obsolete) tag, use $repo and $fromImage in the "name:tag" instead
566564
* @param string|null $registry the registry to pull from
567565
* @param array|null $registryAuth AuthConfig object (to send as X-Registry-Auth header)
568-
* @return Promise Promise<array> stream of message objects
566+
* @return PromiseInterface Promise<array> stream of message objects
569567
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#create-an-image
570568
* @uses self::imageCreateStream()
571569
*/
@@ -627,7 +625,7 @@ public function imageCreateStream($fromImage = null, $fromSrc = null, $repo = nu
627625
* Return low-level information on the image name
628626
*
629627
* @param string $image image ID
630-
* @return Promise Promise<array> image properties
628+
* @return PromiseInterface Promise<array> image properties
631629
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#inspect-an-image
632630
*/
633631
public function imageInspect($image)
@@ -646,7 +644,7 @@ public function imageInspect($image)
646644
* Return the history of the image name
647645
*
648646
* @param string $image image ID
649-
* @return Promise Promise<array> list of image history objects
647+
* @return PromiseInterface Promise<array> list of image history objects
650648
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#get-the-history-of-an-image
651649
*/
652650
public function imageHistory($image)
@@ -678,7 +676,7 @@ public function imageHistory($image)
678676
* @param string|null $tag (optional) the tag to associate with the image on the registry
679677
* @param string|null $registry (optional) the registry to push to (e.g. `registry.acme.com:5000`)
680678
* @param array|null $registryAuth (optional) AuthConfig object (to send as X-Registry-Auth header)
681-
* @return Promise Promise<array> list of image push messages
679+
* @return PromiseInterface Promise<array> list of image push messages
682680
* @uses self::imagePushStream()
683681
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#push-an-image-on-the-registry
684682
*/
@@ -738,7 +736,7 @@ public function imagePushStream($image, $tag = null, $registry = null, $registry
738736
* @param string $repo The repository to tag in
739737
* @param string|null $tag The new tag name
740738
* @param boolean $force 1/True/true or 0/False/false, default false
741-
* @return Promise Promise<null>
739+
* @return PromiseInterface Promise<null>
742740
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#tag-an-image-into-a-repository
743741
*/
744742
public function imageTag($image, $repo, $tag = null, $force = false)
@@ -762,7 +760,7 @@ public function imageTag($image, $repo, $tag = null, $force = false)
762760
* @param string $image image ID
763761
* @param boolean $force 1/True/true or 0/False/false, default false
764762
* @param boolean $noprune 1/True/true or 0/False/false, default false
765-
* @return Promise Promise<null>
763+
* @return PromiseInterface Promise<null>
766764
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#remove-an-image
767765
*/
768766
public function imageRemove($image, $force = false, $noprune = false)
@@ -783,7 +781,7 @@ public function imageRemove($image, $force = false, $noprune = false)
783781
* Search for an image on Docker Hub.
784782
*
785783
* @param string $term term to search
786-
* @return Promise Promise<array> list of image search result objects
784+
* @return PromiseInterface Promise<array> list of image search result objects
787785
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#search-images
788786
*/
789787
public function imageSearch($term)
@@ -803,7 +801,7 @@ public function imageSearch($term)
803801
*
804802
* @param string $container container ID
805803
* @param array $config `array('Cmd' => 'date')` (see link)
806-
* @return Promise Promise<array> with exec ID in the form of `array("Id" => $execId)`
804+
* @return PromiseInterface Promise<array> with exec ID in the form of `array("Id" => $execId)`
807805
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#exec-create
808806
*/
809807
public function execCreate($container, $config)
@@ -827,7 +825,7 @@ public function execCreate($container, $config)
827825
*
828826
* @param string $exec exec ID
829827
* @param array $config (see link)
830-
* @return Promise Promise<array> stream of message objects
828+
* @return PromiseInterface Promise<array> stream of message objects
831829
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#exec-start
832830
*/
833831
public function execStart($exec, $config)
@@ -851,7 +849,7 @@ public function execStart($exec, $config)
851849
* @param string $exec exec ID
852850
* @param int $w TTY width
853851
* @param int $h TTY height
854-
* @return Promise Promise<null>
852+
* @return PromiseInterface Promise<null>
855853
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#exec-resize
856854
*/
857855
public function execResize($exec, $w, $h)

‎src/Factory.php‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,25 @@
55
use React\EventLoop\LoopInterface;
66
use Clue\React\Buzz\Browser;
77
use Clue\React\Buzz\Io\Sender;
8-
use React\HttpClient\Client as HttpClient;
9-
use Clue\React\Docker\Io\UnixConnector;
108

9+
/**
10+
* The Factory is responsible for creating your Client instance.
11+
* It also registers everything with the main EventLoop.
12+
*/
1113
class Factory
1214
{
1315
private $loop;
1416
private $browser;
1517

18+
/**
19+
* Instantiate the Factory
20+
*
21+
* If you need custom DNS, SSL/TLS or proxy settings, you can explicitly
22+
* pass a custom Browser instance.
23+
*
24+
* @param LoopInterface $loop the event loop
25+
* @param null|Browser $browser (optional) custom Browser instance to use
26+
*/
1627
public function __construct(LoopInterface $loop, Browser $browser = null)
1728
{
1829
if ($browser === null) {
@@ -23,6 +34,12 @@ public function __construct(LoopInterface $loop, Browser $browser = null)
2334
$this->browser = $browser;
2435
}
2536

37+
/**
38+
* Creates a new Client instance and helps with constructing the right Browser object for the given remote URL
39+
*
40+
* @param null|string $url (optional) URL to your (local) Docker daemon, defaults to using local unix domain socket path
41+
* @return Client
42+
*/
2643
public function createClient($url = null)
2744
{
2845
if ($url === null) {
@@ -33,8 +50,9 @@ public function createClient($url = null)
3350

3451
if (substr($url, 0, 7) === 'unix://') {
3552
// send everything through a local unix domain socket
36-
$sender = Sender::createFromLoopUnix($this->loop, $url);
37-
$browser = $browser->withSender($sender);
53+
$browser = $this->browser->withSender(
54+
Sender::createFromLoopUnix($this->loop, $url)
55+
);
3856

3957
// pretend all HTTP URLs to be on localhost
4058
$url = 'http://localhost/';

0 commit comments

Comments
 (0)