Add optional callback data param in Deferred::__construct()

CHANGELOG.md

@@ -5,6 +5,10 @@
   implementation is now dependent upon the AMP_DEBUG constant.
 - Renamed Future -> Deferred
 - Renamed Unresolved -> PrivatePlaceholder
+- Support optional callbackData in Deferred::__construct(). Promisors
+  specifying the optional data will receive it as the third parameter
+  to associated when() callbacks. If not specified callbacks are passed
+  null at Argument 3.
 
 v1.0.0-beta3
 ------------

lib/Failure.php

@@ -16,7 +16,7 @@ class Failure implements Promise {
      * {@inheritDoc}
      */
     public function when(callable $func) {
-        $func($this->error, $result = null);
+        $func($this->error, $result = null, $callbackData = null);
     }
 
     /**

lib/Placeholder.php

@@ -7,12 +7,17 @@ namespace Amp;
  * the Promisor that created it.
  */
 trait Placeholder {
+    private $callbackData = null;
     private $isResolved = false;
     private $watchers = [];
     private $whens = [];
     private $error;
     private $result;
 
+    public function __construct($callbackData = null) {
+        $this->callbackData = $callbackData;
+    }
+
     /**
      * Notify the $func callback when the promise resolves (whether successful or not)
      *
@@ -21,7 +26,7 @@ trait Placeholder {
      */
     public function when(callable $func) {
         if ($this->isResolved) {
-            call_user_func($func, $this->error, $this->result);
+            call_user_func($func, $this->error, $this->result, $this->callbackData);
         } else {
             $this->whens[] = $func;
         }
@@ -73,7 +78,7 @@ trait Placeholder {
             $this->error = $error;
             $this->result = $result;
             foreach ($this->whens as $when) {
-                call_user_func($when, $error, $result);
+                call_user_func($when, $error, $result, $this->callbackData);
             }
             $this->whens = $this->watchers = [];
         }

lib/PrivatePromisor.php

@@ -12,13 +12,15 @@ trait PrivatePromisor {
     private $updater;
     private $promise;
 
-    public function __construct() {
-        $placeholder = new PrivatePlaceholder;
+    public function __construct($callbackData = null) {
+        $placeholder = new PrivatePlaceholder($callbackData);
         $resolver = function(\Exception $error = null, $result = null) {
-            $this->resolve($error, $result); // bound to private PrivatePlaceholder::resolve()
+            // bound to private PrivatePlaceholder::resolve()
+            $this->resolve($error, $result);
         };
         $updater = function($progress) {
-            $this->update($progress); // bound to private PrivatePlaceholder::update()
+            // bound to private PrivatePlaceholder::update()
+            $this->update($progress);
         };
         $this->resolver = $resolver->bindTo($placeholder, $placeholder);
         $this->updater = $updater->bindTo($placeholder, $placeholder);

lib/Success.php

@@ -22,7 +22,7 @@ class Success implements Promise {
      * the specified $func callback immediately.
      */
     public function when(callable $func) {
-        call_user_func($func, $error = null, $this->result);
+        call_user_func($func, $error = null, $this->result, $callbackData = null);
         return $this;
     }
 

test/PromisorPrivateTest.php

@@ -6,7 +6,7 @@ use Amp\Promisor;
 use Amp\Test\PromisorPrivateImpl;
 
 class PromisorPrivateTest extends PromisorTest {
-    protected function getPromisor() {
-        return new PromisorPrivateImpl;
+    protected function getPromisor($callbackData = null) {
+        return new PromisorPrivateImpl($callbackData);
     }
 }

test/PromisorPublicTest.php

@@ -6,8 +6,8 @@ use Amp\Promisor;
 use Amp\Test\PromisorPublicImpl;
 
 class PromisorPublicTest extends PromisorTest {
-    protected function getPromisor() {
-        return new PromisorPublicImpl;
+    protected function getPromisor($callbackData = null) {
+        return new PromisorPublicImpl($callbackData);
     }
 
     public function testPromiseReturnsSelf() {

test/PromisorTest.php

@@ -17,17 +17,35 @@ abstract class PromisorTest extends \PHPUnit_Framework_TestCase {
             $this->assertNull($e);
             ++$invoked;
         });
+        $this->assertSame(1, $invoked);
+    }
+
+    public function testPromisorPassesCallbackDataToCallbacks() {
+        $invoked = 0;
+        $promisor = $this->getPromisor("zanzibar");
+        $promise = $promisor->promise();
+        $promisor->succeed(42);
+        $promise->when(function($e, $r, $d) use (&$invoked) {
+            $this->assertNull($e);
+            $this->assertSame(42, $r);
+            $this->assertSame("zanzibar", $d);
+            ++$invoked;
+        });
+        $this->assertSame(1, $invoked);
     }
 
     public function testWhenInvokesCallbackWithErrorIfAlreadyFailed() {
+        $invoked = 0;
         $promisor = $this->getPromisor();
         $promise = $promisor->promise();
         $exception = new \Exception('test');
         $promisor->fail($exception);
-        $promise->when(function($e, $r) use ($exception) {
+        $promise->when(function($e, $r) use ($exception, &$invoked) {
+            $invoked++;
             $this->assertSame($exception, $e);
             $this->assertNull($r);
         });
+        $this->assertSame(1, $invoked);
     }
 
     /**