From 0a316d51c25730272d6a50ad35ecc56088c28b43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sat, 9 Oct 2021 09:57:04 +0200 Subject: [PATCH] Improve error reporting in examples and documentation --- README.md | 28 +++++++++++++++++++++++----- examples/archive.php | 9 +++++---- examples/attach-stream.php | 3 ++- examples/benchmark-attach.php | 10 +++++++--- examples/benchmark-exec.php | 11 +++++++---- examples/events.php | 5 +++-- examples/exec-inspect.php | 6 +----- examples/exec-stream.php | 12 +++++++++--- examples/export.php | 6 +++--- examples/info.php | 4 +++- examples/logs-stream.php | 5 +++-- examples/logs.php | 5 +++-- examples/pull.php | 4 ++++ examples/push.php | 4 +++- examples/resize.php | 4 +++- examples/stats.php | 6 +++++- 16 files changed, 84 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 033ef8d..06733ba 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,8 @@ $client = new Clue\React\Docker\Client(); $client->imageSearch('clue')->then(function (array $images) { var_dump($images); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); ``` @@ -131,15 +133,17 @@ Please see the following section about [promises](#promises) for more details. Sending requests is async (non-blocking), so you can actually send multiple requests in parallel. Docker will respond to each request with a response message, the order is not guaranteed. -Sending requests uses a [Promise](https://github.com/reactphp/promise)-based interface that makes it easy to react to when a request is fulfilled (i.e. either successfully resolved or rejected with an error): +Sending requests uses a [Promise](https://github.com/reactphp/promise)-based +interface that makes it easy to react to when a command is completed +(i.e. either successfully fulfilled or rejected with an error): ```php $client->version()->then( function ($result) { var_dump('Result received', $result); }, - function (Exception $error) { - var_dump('There was an error', $error->getMessage()); + function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; } }); ``` @@ -214,10 +218,16 @@ the normal stream events: ```php $stream = $client->execStartStream($exec, $tty); + $stream->on('data', function ($data) { // data will be emitted in multiple chunk echo $data; }); + +$stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); + $stream->on('close', function () { // the stream just ended, this could(?) be a good thing echo 'Ended' . PHP_EOL; @@ -233,9 +243,11 @@ Also note that this option has no effect if you execute with a TTY. ```php $stream = $client->execStartStream($exec, $tty, 'stderr'); + $stream->on('data', function ($data) { echo 'STDOUT data: ' . $data; }); + $stream->on('stderr', function ($data) { echo 'STDERR data: ' . $data; }); @@ -319,9 +331,9 @@ $client->imageCreate('clue/streamripper')->then( // $data is an array of *all* elements in the JSON stream var_dump($data); }, - function (Exception $error) { + function (Exception $e) { // an error occurred (possibly after receiving *some* elements) - echo 'Error: ' . $error->getMessage() . PHP_EOL; + echo 'Error: ' . $e->getMessage() . PHP_EOL; } ); ``` @@ -355,10 +367,16 @@ The resulting stream will emit the following events: ```php $stream = $client->imageCreateStream('clue/redis-benchmark'); + $stream->on('data', function (array $data) { // data will be emitted for *each* complete element in the JSON stream echo $data['status'] . PHP_EOL; }); + +$stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); + $stream->on('close', function () { // the JSON stream just ended, this could(?) be a good thing echo 'Ended' . PHP_EOL; diff --git a/examples/archive.php b/examples/archive.php index ff962de..754c6b3 100644 --- a/examples/archive.php +++ b/examples/archive.php @@ -27,13 +27,14 @@ }); }); -$tar->on('error', function ($e = null) { +$tar->on('error', function (Exception $e) { // should not be invoked, unless the stream is somehow interrupted - echo 'ERROR processing tar stream' . PHP_EOL . $e; + echo 'Error in TAR stream: ' . $e->getMessage() . PHP_EOL; }); -$stream->on('error', function ($e = null) { + +$stream->on('error', function (Exception $e) { // will be called if either parameter is invalid - echo 'ERROR requesting stream' . PHP_EOL . $e; + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); $stream->pipe($tar); diff --git a/examples/attach-stream.php b/examples/attach-stream.php index cae1035..5a9f2d5 100644 --- a/examples/attach-stream.php +++ b/examples/attach-stream.php @@ -17,13 +17,14 @@ $caret = new Clue\CaretNotation\Encoder("\t\r\n"); $stream = $client->containerAttachStream($container, true, true); + $stream->on('data', function ($data) use ($caret) { echo $caret->encode($data); }); $stream->on('error', function (Exception $e) { // will be called if either parameter is invalid - echo 'ERROR: ' . $e->getMessage() . PHP_EOL; + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); $stream->on('close', function () { diff --git a/examples/benchmark-attach.php b/examples/benchmark-attach.php index 8164065..86e759d 100644 --- a/examples/benchmark-attach.php +++ b/examples/benchmark-attach.php @@ -45,19 +45,23 @@ $client->containerStart($container['Id'])->then(null, 'printf'); }); - $start = microtime(true); $bytes = 0; $stream->on('data', function ($chunk) use (&$bytes) { $bytes += strlen($chunk); }); - $stream->on('error', 'printf'); + $stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; + }); // show stats when stream ends + $start = microtime(true); $stream->on('close', function () use ($client, &$bytes, $start, $container) { $time = microtime(true) - $start; $client->containerRemove($container['Id'])->then(null, 'printf'); echo 'Received ' . $bytes . ' bytes in ' . round($time, 1) . 's => ' . round($bytes / $time / 1000000, 1) . ' MB/s' . PHP_EOL; }); -}, 'printf'); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); diff --git a/examples/benchmark-exec.php b/examples/benchmark-exec.php index ee47d6d..08264eb 100644 --- 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 - require __DIR__ . '/../vendor/autoload.php'; if (extension_loaded('xdebug')) { @@ -33,18 +32,22 @@ $client->execCreate($container, $cmd)->then(function ($info) use ($client) { $stream = $client->execStartStream($info['Id'], true); - $start = microtime(true); $bytes = 0; $stream->on('data', function ($chunk) use (&$bytes) { $bytes += strlen($chunk); }); - $stream->on('error', 'printf'); + $stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; + }); // show stats when stream ends + $start = microtime(true); $stream->on('close', function () use ($client, &$bytes, $start) { $time = microtime(true) - $start; echo 'Received ' . $bytes . ' bytes in ' . round($time, 1) . 's => ' . round($bytes / $time / 1000000, 1) . ' MB/s' . PHP_EOL; }); -}, 'printf'); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); diff --git a/examples/events.php b/examples/events.php index 9612abc..57fafea 100644 --- a/examples/events.php +++ b/examples/events.php @@ -3,7 +3,6 @@ // 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. - require __DIR__ . '/../vendor/autoload.php'; $client = new Clue\React\Docker\Client(); @@ -22,4 +21,6 @@ echo json_encode($event) . PHP_EOL; }); -$stream->on('error', 'printf'); +$stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); diff --git a/examples/exec-inspect.php b/examples/exec-inspect.php index bc68aba..0952528 100644 --- a/examples/exec-inspect.php +++ b/examples/exec-inspect.php @@ -33,9 +33,5 @@ })->then(function ($info) { echo 'Inspected after execution: ' . json_encode($info, JSON_PRETTY_PRINT) . PHP_EOL; }, function (Exception $e) { - echo 'ERROR: ' . $e->getMessage() . PHP_EOL; - - if ($e instanceof React\Http\Message\ResponseException) { - echo 'Response: ' . $e->getResponse()->getBody() . PHP_EOL; - } + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); diff --git a/examples/exec-stream.php b/examples/exec-stream.php index 43ca3b8..67dc3a5 100644 --- a/examples/exec-stream.php +++ b/examples/exec-stream.php @@ -44,15 +44,21 @@ } }); - $stream->on('error', 'printf'); + $stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; + }); // remember exit code of executed command once it closes $stream->on('close', function () use ($client, $info, &$exit) { $client->execInspect($info['Id'])->then(function ($info) use (&$exit) { $exit = $info['ExitCode']; - }, 'printf'); + }, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; + }); }); -}, 'printf'); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); Loop::run(); diff --git a/examples/export.php b/examples/export.php index f45fbe0..9fc9fa2 100644 --- a/examples/export.php +++ b/examples/export.php @@ -17,10 +17,10 @@ $stream = $client->containerExportStream($container); -$stream->on('error', function ($e = null) { +$stream->on('error', function (Exception $e) { // will be called if the container is invalid/does not exist - echo 'ERROR requesting stream' . PHP_EOL . $e; + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); - $out = new React\Stream\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 index 0199c39..d798459 100644 --- a/examples/info.php +++ b/examples/info.php @@ -8,4 +8,6 @@ $client->info()->then(function ($info) { echo json_encode($info, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL; -}, 'printf'); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); diff --git a/examples/logs-stream.php b/examples/logs-stream.php index d031fa0..3aae06b 100644 --- a/examples/logs-stream.php +++ b/examples/logs-stream.php @@ -14,13 +14,14 @@ $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) { echo $caret->encode($data); }); -$stream->on('error', function ($e = null) { +$stream->on('error', function (Exception $e) { // will be called if either parameter is invalid - echo 'ERROR requesting stream' . PHP_EOL . $e; + echo 'Error: ' . $e->getMessage() . PHP_EOL; }); $stream->on('close', function ($e = null) { diff --git a/examples/logs.php b/examples/logs.php index 118eee1..9994bbf 100644 --- a/examples/logs.php +++ b/examples/logs.php @@ -25,7 +25,7 @@ function ($logs) { $caret = new Clue\CaretNotation\Encoder("\t\r\n"); echo $caret->encode($logs); }, - function ($error) use ($container) { + function (Exception $e) use ($container) { echo <<getMessage()} + EOT; } ); diff --git a/examples/pull.php b/examples/pull.php index b8613e6..90744cd 100644 --- a/examples/pull.php +++ b/examples/pull.php @@ -16,6 +16,10 @@ echo 'progress: '. json_encode($progress) . PHP_EOL; }); +$stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); + $stream->on('close', function () { echo 'stream closed' . PHP_EOL; }); diff --git a/examples/push.php b/examples/push.php index 5d4dd38..9195ed4 100644 --- a/examples/push.php +++ b/examples/push.php @@ -13,4 +13,6 @@ $client->imagePush($image, null, null, $auth)->then(function ($result) { echo json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL; -}, 'printf'); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); diff --git a/examples/resize.php b/examples/resize.php index d9f780d..2ea4d44 100644 --- a/examples/resize.php +++ b/examples/resize.php @@ -17,4 +17,6 @@ return $client->containerResize($container, $size[0] + 10, $size[1] + 10); })->then(function () use ($client) { echo 'Successfully set' . PHP_EOL; -}, 'printf'); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); diff --git a/examples/stats.php b/examples/stats.php index 07e531b..6a78105 100644 --- a/examples/stats.php +++ b/examples/stats.php @@ -24,7 +24,11 @@ echo round($memory, 3) . '% memory and ' . $received . '/' . $sent . ' bytes network I/O' . PHP_EOL; }); -$stream->on('error', 'printf'); + +$stream->on('error', function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); + $stream->on('close', function () { echo 'stream closed' . PHP_EOL; });