sanmai/later

Later: a deferred object manager. Zero callbacks required. Futures for PHP.

This rigorously tested fully-typed library just works. It neither defines nor throws any exceptions.

Install

composer require sanmai/later

The latest version requires PHP 7.4 or greater.

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:

For example:

use function Later\later;

$deferred = later(function () {
    $deepThought = new DeepThought();
    $deepThought->solveTheQuestion();

    yield $deepThought;
});

And then call get() when needed, as many times as needed:

$deferred->get()->getAnswer(); // 42
$deferred->get()->getAnswer(); // same 42

Using a generator instead of a traditional callback comes with a major benefit: any generator is guaranteed by the language to be used exactly once. You can be sure that it won't be called twice.

But that's not all: read on.

No Callbacks Required

Making a closure generator on the spot isn't always convenient. And not to say these closures are much different from all-too-familiar callbacks. Not at all different from the looks of them.

The power of this pattern is in its ability to make use of any function, previously returning a single value, without any need for any additional callbacks or closures.

Consider this diff:

 private function makeFooBar()
 {
    //...

-    return $foo;
+    yield $foo;
 }

After adding Later\lazy to the mix:

 use function Later\lazy;

 public function __construct()
 {
-    $this->fooBar = $this->makeFooBar();
+    $this->lazyFooBar = lazy($this->makeFooBar());
 }

 public function usesFooBar()
 {
     if ($fooBarReallyRequired) {
-        $this->fooBar->getResult();
+        $this->lazyFooBar->get()->getResult();
     }
 }

We can see, this simple, single-line, change in the original method freed our program from creating things it may not need, postponing this process until the last moment, while also avoiding any use of callbacks.

Type Transparency

The library is completely typed. PHPStan, Psalm, and Phan are all routinely supported.

To exploit 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>:

use Later\Interfaces\Deferred;
use function Later\lazy;

final class HyperIntelligentMice
{
    /** @var Deferred<DeepThought> */
    private $supercomputer;

    public function __construct(DeepThought $deepThought)
    {
        $this->supercomputer = lazy(self::updateDeepThought($deepThought));
    }

    /** @return iterable<DeepThought> */
    private static function updateDeepThought(DeepThought $deepThought): iterable
    {
        $deepThought->solveTheQuestion();

        yield $deepThought;
    }

    public function getAnswer(): int
    {
        return $this->supercomputer->get()->getAnswer();
    }
}

Following this approach, a static analyzer will be able to understand what is called, and what is returned.

Eager Execution

What if a program calls for Deferred object, but lazy evaluation is not required? For example, because a result is already available being loaded from a cache.

No problem, there's a function for this:

use function Later\now;

$deferred = now($result);
$deferred->get(); // returns $result

This deferred-but-not-deferred object implements the same interface, and can be used anywhere where a normal Deferred object would go.

Writing Tests

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:

use function Later\lazy;

$this->lazyDependency = lazy([
    $myDependency,
]);

Yet for constant and already-known answers best to use a non-deferred variant:

use function Later\now;

$this->lazyDependency = now($myDependency);

And that's it. No need to go through loops assembling closures and whatnot.

If nothing else, one can make a common mock for it:

$deferredMock = $this->createMock(\Later\Interfaces\Deferred::class);
$deferredMock
    ->expects($this->once())
    ->method('get')
    ->willReturn($myDependency)
;

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>

later's Issues

Use of mutation testing in later - Help needed

Hello there!

My name is Ana. I noted that you use the mutation testing tool infection in the project.
I am a postdoctoral researcher at the University of Seville (Spain), and my colleagues and I are studying how mutation testing tools are used in practice. With this aim in mind, we have analysed over 3,500 public GitHub repositories using mutation testing tools, including yours! This work has recently been published in a journal paper available at https://link.springer.com/content/pdf/10.1007/s10664-022-10177-8.pdf.

To complete this study, we are asking for your help to understand better how mutation testing is used in practice, please! We would be extremely grateful if you could contribute to this study by answering a brief survey of 21 simple questions (no more than 6 minutes). This is the link to the questionnaire https://forms.gle/FvXNrimWAsJYC1zB9.

Drop me an e-mail if you have any questions or comments ([email protected]). Thank you very much in advance!!

Can we make an API for existing concurrency extensions?

• https://www.php.net/manual/en/class.parallel-channel.php
• https://www.php.net/manual/en/class.parallel-future.php
• https://www.php.net/manual/en/class.swoole-channel.php