Remove promise progress events, use streaming API instead

Author: clue

README.md

@@ -153,10 +153,7 @@ What this means is that these endpoints actually emit any number of progress
 events (individual JSON objects).
 
 The user-facing API hides this fact by resolving with an array of all individual
-progress events once the stream ends.
-
-These progress events can also be accessed individually via the Promise
-progress handler like this:
+progress events once the stream ends:
 
 ```php
 $client->imageCreate('clue/streamripper')->then(
@@ -165,9 +162,6 @@ $client->imageCreate('clue/streamripper')->then(
     },
     function ($error) {
         // an error occurred (possibly after receiving *some* elements)
-    },
-    function ($element) {
-        // will be invoked for *each* complete $element in the JSON stream
     }
 );
 ```
@@ -177,8 +171,9 @@ this API has to keep all event objects in memory until the Promise resolves.
 This is easy to get started and usually works reasonably well for the above
 API endpoints.
 
-If you're dealing with lots of concurrent requests (100+),
-it could be a better idea to use a streaming approach,
+If you're dealing with lots of concurrent requests (100+) or 
+if you want to access the individual progress events as they happen, you
+should consider using a streaming approach instead,
 where only individual progress event objects have to be kept in memory.
 The following API endpoints complement the default Promise-based API and return
 a [`Stream`](https://github.com/reactphp/stream) instance instead:

examples/pull.php

@@ -1,4 +1,6 @@
 <?php
+// 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.
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -13,14 +15,14 @@
 $factory = new Factory($loop);
 $client = $factory->createClient();
 
-$client->imageCreate($image)->then(
-    function ($response) {
-        echo 'response: ' . json_encode($response) . PHP_EOL;
-    },
-    'var_dump',
-    function ($info) {
-        echo 'update: ' . json_encode($info) . PHP_EOL;
-    }
-);
+$stream = $client->imageCreateStream($image);
+
+$stream->on('progress', function ($progress) {
+    echo 'progress: '. json_encode($progress) . PHP_EOL;
+});
+
+$stream->on('close', function () {
+    echo 'stream closed' . PHP_EOL;
+});
 
 $loop->run();

examples/push.php

@@ -20,10 +20,7 @@
     function ($response) {
         echo 'response: ' . json_encode($response) . PHP_EOL;
     },
-    'var_dump',
-    function ($info) {
-        echo 'update: ' . json_encode($info) . PHP_EOL;
-    }
+    'var_dump'
 );
 
 $loop->run();

src/Client.php

@@ -387,8 +387,8 @@ public function imageList($all = false)
      * This is a JSON streaming API endpoint that resolves with an array of all
      * individual progress events.
      *
-     * These progress events can also be accessed individually via the Promise
-     * progress handler.
+     * If you want to access the individual progress events as they happen, you
+     * should consider using `imageCreateStream()` instead.
      *
      * Pulling a private image from a remote registry will likely require authorization, so make
      * sure to pass the $registryAuth parameter, see `self::authHeaders()` for
@@ -477,8 +477,8 @@ public function imageHistory($image)
      * This is a JSON streaming API endpoint that resolves with an array of all
      * individual progress events.
      *
-     * These progress events can also be accessed individually via the Promise
-     * progress handler.
+     * If you need to access the individual progress events as they happen, you
+     * should consider using `imagePushStream()` instead.
      *
      * Pushing to a remote registry will likely require authorization, so make
      * sure to pass the $registryAuth parameter, see `self::authHeaders()` for

src/Io/StreamingParser.php

@@ -99,11 +99,10 @@ public function deferredStream(ReadableStreamInterface $stream, $progressEventNa
         });
 
         if ($stream->isReadable()) {
-            // buffer all data events and emit as progress
+            // buffer all data events for deferred resolving
             $buffered = array();
-            $stream->on($progressEventName, function ($data) use ($deferred, &$buffered) {
+            $stream->on($progressEventName, function ($data) use (&$buffered) {
                 $buffered []= $data;
-                $deferred->progress($data);
             });
 
             // error event rejects