Add magical calls to get() via __call() and __get() (#24)

Author: sanmai

.gitignore

@@ -1,3 +1,4 @@
 /composer.lock
 /vendor
 /build
+.?*

.phan/config.php

@@ -5,6 +5,7 @@
 return [
     'target_php_version' => '7.4',
     'backward_compatibility_checks' => false,
+    'read_mixin_annotations' => false,
     'exclude_analysis_directory_list' => [
         'vendor/',
     ],

README.md

@@ -7,11 +7,13 @@ This rigorously tested fully-typed library just works. It neither defines nor th
 
 # Install
 
-    composer require sanmai/later
+```
+composer require sanmai/later
+```
 
 The latest version requires PHP 7.4 or greater.
 
-# Use 
+# Use
 
 To use this pattern you need a generator function, yielding a single item of type you want to produce lazily. Pass it to `later()`, a static wrapper returning a `Deferred` object:
 
@@ -83,7 +85,7 @@ We can see, this simple, single-line, change in the original method freed our pr
 
 The library is completely typed. [PHPStan](https://github.com/phpstan/phpstan), [Psalm](https://github.com/vimeo/psalm), and [Phan](https://github.com/phan/phan) are all routinely supported.
 
-To exploit this capability it is recommended to declare a variable holding this object as `\Later\Interfaces\Deferred<Type>`.
+To use this capability it is recommended to declare a variable holding this object as `\Later\Interfaces\Deferred<Type>`.
 
 In this example it will be `Deferred<DeepThought>`:
 
@@ -116,7 +118,19 @@ final class HyperIntelligentMice
 }
 ```
 
-Following this approach, a static analyzer will be able to understand what is called, and what is returned.
+Following this approach, a static analyzer or IDE will be able to understand what is called, and what is returned.
+
+### Proxy Syntax
+
+The library supports convenient proxy syntax for accessing methods and properties directly from the deferred object:
+
+```php
+/** @var \Later\Interfaces\Deferred<DeepThought> $deferred */
+$deferred->getAnswer(); // 42
+$deferred->answer;      // 42
+```
+
+With the explicit type IDEs such as PhpStorm can autocomplete proxied members.
 
 ## Eager Execution
 
@@ -135,7 +149,7 @@ This deferred-but-not-deferred object implements the same interface, and can be
 
 # Writing Tests
 
-The underlying `Deferred` object is fairly lax about input types. It will be happy to accept any `iterable`, not just generators. 
+The underlying `Deferred` object is fairly lax about input types. It will be happy to accept any `iterable`, not just generators.
 
 This makes it super easy to use in mocks:
 
@@ -170,8 +184,8 @@ $deferredMock
 
 # API Overview
 
-|  Method            | Takes                         | Returns     |
-| ------------------ | ----------------------------- | ----------- |
-| `Later\lazy()` | `iterable<T>` | `\Later\Interfaces\Deferred<T>` |
-| `Later\later()` | A generator callback for `T`  | `\Later\Interfaces\Deferred<T>` |
-| `Later\now()` | `T`  | `\Later\Interfaces\Deferred<T>` |
+| Method          | Takes                        | Returns                         |
+| --------------- | ---------------------------- | ------------------------------- |
+| `Later\lazy()`  | `iterable<T>`                | `\Later\Interfaces\Deferred<T>` |
+| `Later\later()` | A generator callback for `T` | `\Later\Interfaces\Deferred<T>` |
+| `Later\now()`   | `T`                          | `\Later\Interfaces\Deferred<T>` |

src/Deferred.php

@@ -27,6 +27,7 @@
  * Deferred: a wrapper object.
  *
  * @template T
+ * @mixin T
  *
  * @template-implements Interfaces\Deferred<T>
  *
@@ -86,4 +87,21 @@ public function get()
 
         return $this->output;
     }
+
+    /**
+     * Forwards the call to the resolved object; PHP throws \Error if the method is missing.
+     * MixedMethodCall is suppressed because Psalm cannot infer methods on the generic type.
+     *
+     * @param array<mixed> $args Forwarded variadic arguments.
+     * @psalm-suppress MixedMethodCall
+     */
+    public function __call(string $name, array $args): mixed
+    {
+        return $this->get()->{$name}(...$args);
+    }
+
+    public function __get(string $name): mixed
+    {
+        return $this->get()->$name;
+    }
 }

src/Interfaces/Deferred.php

@@ -22,6 +22,7 @@
 
 /**
  * @template T
+ * @mixin T
  */
 interface Deferred
 {

tests/DeferredTest.php

@@ -23,6 +23,9 @@
 use Later\Deferred;
 use ReflectionClass;
 use InvalidArgumentException;
+use Tests\Later\Examples\MagicalFoo;
+
+use function Later\later;
 
 /**
  * @covers \Later\Deferred
@@ -124,4 +127,20 @@ private function generatorThrows(bool $throw = false): iterable
 
         yield 1;
     }
+
+    public function testMagicCall(): void
+    {
+        $deferred = later(fn() => yield new MagicalFoo());
+
+        /** @var Deferred<MagicalFoo> $deferred */
+        $this->assertSame(42, $deferred->getAnswer());
+    }
+
+    public function testMagicGet(): void
+    {
+        $deferred = later(fn() => yield new MagicalFoo());
+
+        /** @var Deferred<MagicalFoo> $deferred */
+        $this->assertSame(42, $deferred->answer);
+    }
 }

tests/Examples/MagicalFoo.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * Copyright 2020 Alexey Kopytko <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Tests\Later\Examples;
+
+class MagicalFoo
+{
+    public int $answer = 42;
+
+    public function getAnswer(): int
+    {
+        return 42;
+    }
+}