Skip to content

Commit 10b3d9a

Browse files
clueclue
committed
Improve documentation
1 parent e8d3f18 commit 10b3d9a

1 file changed

Lines changed: 114 additions & 15 deletions

File tree

‎src/Client.php‎

Lines changed: 114 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,32 @@
55
use Clue\React\Buzz\Browser;
66
use Clue\React\Buzz\Message\Response;
77
use Clue\React\Docker\Io\ResponseParser;
8+
use React\Promise\PromiseInterface as Promise;
89

910
/**
11+
* Docker Remote API client
1012
*
11-
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#attach-to-a-container
13+
* Primarily tested against current v1.15 API, but should also work against
14+
* other versions.
15+
*
16+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/
1217
*/
1318
class Client
1419
{
1520
private $browser;
1621
private $url;
1722
private $parser;
1823

24+
/**
25+
* Instantiate new Client
26+
*
27+
* SHOULD NOT be called manually, see Factory::createClient() instead
28+
*
29+
* @param Browser $browser
30+
* @param string $url
31+
* @param ResponseParser|null $parser
32+
* @see Factory::createClient()
33+
*/
1934
public function __construct(Browser $browser, $url, ResponseParser $parser = null)
2035
{
2136
if ($parser === null) {
@@ -27,93 +42,177 @@ public function __construct(Browser $browser, $url, ResponseParser $parser = nul
2742
$this->parser = $parser;
2843
}
2944

45+
/**
46+
* Ping the docker server
47+
*
48+
* @return Promise Promise<string> "OK"
49+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#ping-the-docker-server
50+
*/
3051
public function ping()
3152
{
3253
return $this->browser->get($this->url('/_ping'))->then(array($this->parser, 'expectPlain'));
3354
}
3455

56+
/**
57+
* Display system-wide information
58+
*
59+
* @return Promise Promise<array> system info (see link)
60+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#display-system-wide-information
61+
*/
3562
public function info()
3663
{
3764
return $this->browser->get($this->url('/info'))->then(array($this->parser, 'expectJson'));
3865
}
3966

67+
/**
68+
* Show the docker version information
69+
*
70+
* @return Promise Promise<array> version info (see link)
71+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#show-the-docker-version-information
72+
*/
4073
public function version()
4174
{
4275
return $this->browser->get($this->url('/version'))->then(array($this->parser, 'expectJson'));
4376
}
4477

78+
/**
79+
* List containers
80+
*
81+
* @param boolean $all
82+
* @param boolean $size
83+
* @return Promise Promise<array> list of container objects
84+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#list-containers
85+
*/
4586
public function containerList($all = false, $size = false)
4687
{
4788
return $this->browser->get($this->url('/containers/json?all=%u&size=%u', $all, $size))->then(array($this->parser, 'expectJson'));
4889
}
4990

91+
/**
92+
* Return low-level information on the container id
93+
*
94+
* @param string $container container ID
95+
* @return Promise Promise<array> container properties
96+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#inspect-a-container
97+
*/
5098
public function containerInspect($container)
5199
{
52100
return $this->browser->get($this->url('/containers/%s/json', $container))->then(array($this->parser, 'expectJson'));
53101
}
54102

103+
/**
104+
* List processes running inside the container id
105+
*
106+
* @param string $container container ID
107+
* @return Promise Promise<array>
108+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#list-processes-running-inside-a-container
109+
*/
55110
public function containerTop($container)
56111
{
57112
return $this->browser->get($this->url('/containers/%s/top', $container))->then(array($this->parser, 'expectJson'));
58113
}
59114

60-
public function containerWait($container)
115+
/**
116+
* Resize the TTY of container id
117+
*
118+
* @param string $container container ID
119+
* @param int $w TTY width
120+
* @param int $h TTY height
121+
* @return Promise Promise<null>
122+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#resize-a-container-tty
123+
*/
124+
public function containerResize($container, $w, $h)
61125
{
62-
return $this->browser->post($this->url('/containers/%s/wait', $container))->then(array($this->parser, 'expectJson'));
126+
return $this->browser->get($this->url('/containers/%s/resize?w=%u&h=%u', $container, $w, $h))->then(array($this->parser, 'expectEmpty'));
63127
}
64128

65129
/**
130+
* Stop the container id
66131
*
67-
*
68-
* @param string $container
132+
* @param string $container container ID
69133
* @param int $t number of seconds to wait before killing the container
134+
* @return Promise Promise<null>
135+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#stop-a-container
70136
*/
71137
public function containerStop($container, $t)
72138
{
73139
return $this->browser->post($this->url('/containers/%s/stop?t=%u', $container, $t))->then(array($this->parser, 'expectEmpty'));
74140
}
75141

76142
/**
143+
* Restart the container id
77144
*
78-
*
79-
* @param string $container
145+
* @param string $container container ID
80146
* @param int $t number of seconds to wait before killing the container
147+
* @return Promise Promise<null>
148+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#restart-a-container
81149
*/
82150
public function containerRestart($container, $t)
83151
{
84152
return $this->browser->post($this->url('/containers/%s/restart?t=%u', $container, $t))->then(array($this->parser, 'expectEmpty'));
85153
}
86154

155+
/**
156+
* Kill the container id
157+
*
158+
* @param string $container container ID
159+
* @param string|int|null $signal (optional) signal name or number
160+
* @return Promise Promise<null>
161+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#kill-a-container
162+
*/
87163
public function containerKill($container, $signal = null)
88164
{
89165
return $this->browser->post($this->url('/containers/%s/kill?signal=%s', $container, $signal))->then(array($this->parser, 'expectEmpty'));
90166
}
91167

168+
/**
169+
* Pause the container id
170+
*
171+
* @param string $container container ID
172+
* @return Promise Promise<null>
173+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#pause-a-container
174+
*/
92175
public function containerPause($container)
93176
{
94177
return $this->browser->post($this->url('/containers/%s/pause', $container))->then(array($this->parser, 'expectEmpty'));
95178
}
96179

180+
/**
181+
* Unpause the container id
182+
*
183+
* @param string $container container ID
184+
* @return Promise Promise<null>
185+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#unpause-a-container
186+
*/
97187
public function containerUnpause($container)
98188
{
99189
return $this->browser->post($this->url('/containers/%s/unpause', $container))->then(array($this->parser, 'expectEmpty'));
100190
}
101191

102192
/**
193+
* Block until container id stops, then returns the exit code
103194
*
104-
*
105-
* @param string $container
106-
* @param string $v Remove the volumes associated to the container. Default false
107-
* @param string $force Kill then remove the container. Default false
195+
* @param string $container container ID
196+
* @return Promise Promise<array> `array('StatusCode' => 0)` (see link)
197+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#wait-a-container
108198
*/
109-
public function containerDelete($container, $v = false, $force = false)
199+
public function containerWait($container)
110200
{
111-
return $this->browser->delete($this->url('/containers/%s?v=%u&force=%u', $container, $v, $force))->then(array($this->parser, 'expectEmpty'));
201+
return $this->browser->post($this->url('/containers/%s/wait', $container))->then(array($this->parser, 'expectJson'));
112202
}
113203

114-
public function containerResize($container, $w, $h)
204+
/**
205+
* Remove the container id from the filesystem
206+
*
207+
* @param string $container container ID
208+
* @param boolean $v Remove the volumes associated to the container. Default false
209+
* @param boolean $force Kill then remove the container. Default false
210+
* @return Promise Promise<null>
211+
* @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#remove-a-container
212+
*/
213+
public function containerDelete($container, $v = false, $force = false)
115214
{
116-
return $this->browser->get($this->url('/containers/%s/resize?w=%u&h=%u', $container, $w, $h))->then(array($this->parser, 'expectEmpty'));
215+
return $this->browser->delete($this->url('/containers/%s?v=%u&force=%u', $container, $v, $force))->then(array($this->parser, 'expectEmpty'));
117216
}
118217

119218
private function url($url)

0 commit comments

Comments
 (0)