Merge pull request #72 from SimonFrings/docs

clue · web-flow · commit 1813c6846c1e · 2021-09-30T13:31:44.000+02:00
Use new HTTP and Socket API and improve documentation and examples
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
-/vendor
 /composer.lock
+/vendor/
diff --git a/README.md b/README.md
@@ -58,6 +58,10 @@ Once [installed](#install), you can use the following code to access the
 Docker API of your local docker daemon:
 
 ```php
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
 $client = new Clue\React\Docker\Client();
 
 $client->imageSearch('clue')->then(function (array $images) {
@@ -379,7 +383,7 @@ See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
 
 This project aims to run on any platform and thus does not require any PHP
 extensions and supports running on legacy PHP 5.3 through current PHP 8+.
-It's *highly recommended to use PHP 7+* for this project.
+It's *highly recommended to use the latest supported PHP version* for this project.
 
 ## Tests
 
@@ -393,7 +397,7 @@ $ composer install
 To run the test suite, go to the project root and run:
 
 ```bash
-$ php vendor/bin/phpunit
+$ vendor/bin/phpunit
 ```
 
 ## License
diff --git a/composer.json b/composer.json
@@ -20,10 +20,10 @@
         "php": ">=5.3",
         "clue/json-stream": "^0.1",
         "react/event-loop": "^1.2",
-        "react/http": "^1.4",
+        "react/http": "^1.5",
         "react/promise": "^2.0 || ^1.1",
         "react/promise-stream": "^1.0",
-        "react/socket": "^1.8",
+        "react/socket": "^1.9",
         "react/stream": "^1.2",
         "rize/uri-template": "^0.3"
     },
diff --git a/examples/archive.php b/examples/archive.php
@@ -4,27 +4,22 @@
 // how it can be passed to a TAR decoder and how we can then pipe each
 // individual file to the console output.
 
-use Clue\CaretNotation\Encoder;
-use Clue\React\Docker\Client;
-use Clue\React\Tar\Decoder;
-use React\Stream\ReadableStreamInterface;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $container = isset($argv[1]) ? $argv[1] : 'asd';
 $path = isset($argv[2]) ? $argv[2] : '/etc/passwd';
 echo 'Container "' . $container . '" dumping "' . $path . '" (pass as arguments to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $stream = $client->containerArchiveStream($container, $path);
 
-$tar = new Decoder();
+$tar = new Clue\React\Tar\Decoder();
 
 // use caret notation for any control characters except \t, \r and \n
-$caret = new Encoder("\t\r\n");
+$caret = new Clue\CaretNotation\Encoder("\t\r\n");
 
-$tar->on('entry', function ($header, ReadableStreamInterface $file) use ($caret) {
+$tar->on('entry', function ($header, React\Stream\ReadableStreamInterface $file) use ($caret) {
     // write each entry to the console output
     echo '########## ' . $caret->encode($header['filename']) . ' ##########' . PHP_EOL;
     $file->on('data', function ($chunk) use ($caret) {
diff --git a/examples/attach-stream.php b/examples/attach-stream.php
@@ -6,18 +6,15 @@
 // $ docker run -it --rm --name=foo busybox sh
 // $ php examples/attach-stream.php foo
 
-use Clue\CaretNotation\Encoder;
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $container = isset($argv[1]) ? $argv[1] : 'foo';
 echo 'Dumping output of container "' . $container . '" (pass as argument to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 // use caret notation for any control characters except \t, \r and \n
-$caret = new Encoder("\t\r\n");
+$caret = new Clue\CaretNotation\Encoder("\t\r\n");
 
 $stream = $client->containerAttachStream($container, true, true);
 $stream->on('data', function ($data) use ($caret) {
diff --git a/examples/benchmark-attach.php b/examples/benchmark-attach.php
@@ -10,7 +10,6 @@
 //
 // $ docker run -i --rm --log-driver=none busybox dd if=/dev/zero bs=1M count=1000 status=none | dd of=/dev/null
 
-use Clue\React\Docker\Client;
 use React\EventLoop\Loop;
 
 require __DIR__ . '/../vendor/autoload.php';
@@ -27,7 +26,7 @@
     $cmd = array_slice($argv, 2);
 }
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->containerCreate(array(
     'Image' => $image,
diff --git a/examples/benchmark-exec.php b/examples/benchmark-exec.php
@@ -13,7 +13,6 @@
 //
 // $ docker exec foo dd if=/dev/zero bs=1M count=1000 | dd of=/dev/null
 
-use Clue\React\Docker\Client;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -29,7 +28,7 @@
     $cmd = array_slice($argv, 2);
 }
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->execCreate($container, $cmd)->then(function ($info) use ($client) {
     $stream = $client->execStartStream($info['Id'], true);
diff --git a/examples/events.php b/examples/events.php
@@ -3,11 +3,10 @@
 // this simple example displays all docker events that happen in the next 10s.
 // try starting / removing a container in the meantime to see some output.
 
-use Clue\React\Docker\Client;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 // get a list of all events that happened up until this point
 // expect this list to be limited to the last 64 (or so) events
diff --git a/examples/exec-inspect.php b/examples/exec-inspect.php
@@ -2,9 +2,6 @@
 
 // this simple example executes a "sleep 2" within the given running container
 
-use Clue\React\Buzz\Message\ResponseException;
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $container = 'asd';
@@ -18,7 +15,7 @@
     $cmd = array_slice($argv, 2);
 }
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->execCreate($container, $cmd)->then(function ($info) use ($client) {
     echo 'Created with info: ' . json_encode($info) . PHP_EOL;
@@ -38,7 +35,7 @@
 }, function (Exception $e) {
     echo 'ERROR: ' . $e->getMessage() . PHP_EOL;
 
-    if ($e instanceof ResponseException) {
+    if ($e instanceof React\Http\Message\ResponseException) {
         echo 'Response: ' . $e->getResponse()->getBody() . PHP_EOL;
     }
 });
diff --git a/examples/exec-stream.php b/examples/exec-stream.php
@@ -3,9 +3,7 @@
 // this example executes some commands within the given running container and
 // displays the streaming output as it happens.
 
-use Clue\React\Docker\Client;
 use React\EventLoop\Loop;
-use React\Stream\WritableResourceStream;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -24,10 +22,10 @@
     $cmd = array_slice($argv, 2);
 }
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
-$out = new WritableResourceStream(STDOUT);
-$stderr = new WritableResourceStream(STDERR);
+$out = new React\Stream\WritableResourceStream(STDOUT);
+$stderr = new React\Stream\WritableResourceStream(STDERR);
 
 // unkown exit code by default
 $exit = 1;
diff --git a/examples/export.php b/examples/export.php
@@ -3,9 +3,6 @@
 // this example shows how the containerExport() call returns a TAR stream
 // and how we it can be piped into a output tar file.
 
-use Clue\React\Docker\Client;
-use React\Stream\WritableResourceStream;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 if (DIRECTORY_SEPARATOR === '\\') {
@@ -16,7 +13,7 @@
 $target = isset($argv[2]) ? $argv[2] : ($container . '.tar');
 echo 'Exporting whole container "' . $container . '" to "' . $target .'" (pass as arguments to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $stream = $client->containerExportStream($container);
 
@@ -25,5 +22,5 @@
     echo 'ERROR requesting stream' . PHP_EOL . $e;
 });
 
-$out = new WritableResourceStream(fopen($target, 'w'));
+    $out = new React\Stream\WritableResourceStream(fopen($target, 'w'));
 $stream->pipe($out);
diff --git a/examples/info.php b/examples/info.php
@@ -2,11 +2,9 @@
 
 // this simple example displays system wide information from Docker as a simple JSON
 
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->info()->then(function ($info) {
     echo json_encode($info, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL;
diff --git a/examples/logs-stream.php b/examples/logs-stream.php
@@ -3,18 +3,15 @@
 // this example shows how the containerLogsStream() call can be used to get the logs of the given container.
 // demonstrates the streaming logs API, which can be used to dump the logs as they arrive
 
-use Clue\CaretNotation\Encoder;
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $container = isset($argv[1]) ? $argv[1] : 'asd';
 echo 'Dumping logs (last 100 lines) of container "' . $container . '" (pass as argument to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 // use caret notation for any control characters except \t, \r and \n
-$caret = new Encoder("\t\r\n");
+$caret = new Clue\CaretNotation\Encoder("\t\r\n");
 
 $stream = $client->containerLogsStream($container, true, true, true, 0, false, 100);
 $stream->on('data', function ($data) use ($caret) {
diff --git a/examples/logs.php b/examples/logs.php
@@ -15,14 +15,14 @@
 $container = isset($argv[1]) ? $argv[1] : 'foo';
 echo 'Dumping logs (last 100 lines) of container "' . $container . '" (pass as argument to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->containerLogs($container, false, true, true, 0, false, 100)->then(
     function ($logs) {
         echo 'Received the following logs:' . PHP_EOL;
 
         // escape control characters (dumping logs of vi/nano etc.)
-        $caret = new Encoder("\t\r\n");
+        $caret = new Clue\CaretNotation\Encoder("\t\r\n");
         echo $caret->encode($logs);
     },
     function ($error) use ($container) {
diff --git a/examples/pull.php b/examples/pull.php
@@ -3,14 +3,12 @@
 // this example shows how the imageCreateStream() call can be used to pull a given image.
 // demonstrates the JSON streaming API, individual progress events will be printed as they happen.
 
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $image = isset($argv[1]) ? $argv[1] : 'clue/redis-benchmark';
 echo 'Pulling image "' . $image . '" (pass as argument to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $stream = $client->imageCreateStream($image);
 
diff --git a/examples/push.php b/examples/push.php
@@ -3,15 +3,13 @@
 // this example shows how the imagePush() call can be used to publish a given image.
 // this requires authorization and this example includes some invalid defaults.
 
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $image = isset($argv[1]) ? $argv[1] : 'asd';
 $auth = json_decode('{"username": "string", "password": "string", "email": "string", "serveraddress" : "string", "auth": ""}');
 echo 'Pushing image "' . $image . '" (pass as argument to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->imagePush($image, null, null, $auth)->then(function ($result) {
     echo json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL;
diff --git a/examples/resize.php b/examples/resize.php
@@ -3,13 +3,11 @@
 // this example tries to adjust the TTY size of the given container to 10x10.
 // you can check this via "docker logs".
 
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $container = isset($argv[1]) ? $argv[1] : 'asd';
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $client->containerInspect($container)->then(function ($info) use ($client, $container) {
     $size = $info['HostConfig']['ConsoleSize'];
diff --git a/examples/stats.php b/examples/stats.php
@@ -3,14 +3,12 @@
 // this example shows how the `containerStatsStream()` method can be used show live container stats.
 // demonstrates the JSON streaming API, individual stats events will be printed as they happen.
 
-use Clue\React\Docker\Client;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 $container = isset($argv[1]) ? $argv[1] : 'asd';
 echo 'Monitoring "' . $container . '" (pass as argument to this example)' . PHP_EOL;
 
-$client = new Client();
+$client = new Clue\React\Docker\Client();
 
 $stream = $client->containerStatsStream($container);
 
diff --git a/src/Client.php b/src/Client.php
@@ -79,7 +79,7 @@ public function __construct(LoopInterface $loop = null, $url = null)
             throw new \InvalidArgumentException('Invalid Docker Engine API URL given');
         }
 
-        $browser = new Browser($loop, $connector);
+        $browser = new Browser($connector, $loop);
         $this->browser = $browser->withBase($url);
         $this->parser = new ResponseParser();
         $this->streamingParser = new StreamingParser();
diff --git a/tests/FunctionalClientTest.php b/tests/FunctionalClientTest.php
diff --git a/tests/IntegrationTest.php b/tests/IntegrationTest.php

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		`-/vendor`
`2`	`1`	`/composer.lock`
	`2`	`+/vendor/`