Skip to content
A magic memoization function
PHP
Branch: master
Clone or download
Latest commit d721d3e Oct 30, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Differentiate between closures Oct 26, 2019
tests Differentiate between closures Oct 26, 2019
.editorconfig add skeleton Nov 6, 2016
.gitattributes add skeleton Nov 6, 2016
.gitignore
.scrutinizer.yml add skeleton Nov 6, 2016
.styleci.yml remove unused option Jan 31, 2018
.travis.yml wip Jun 19, 2019
CHANGELOG.md Update CHANGELOG.md Oct 31, 2019
CONTRIBUTING.md add skeleton Nov 6, 2016
LICENSE.md Enable MIT badge on GitHub Oct 11, 2017
README.md wip Jun 19, 2019
composer.json wip Jun 19, 2019
phpunit.xml.dist

README.md

A magic memoization function

Latest Version on Packagist Software License Build Status Quality Score StyleCI Total Downloads

This package contains a once function. You can pass a callable to it. Here's quick example:

class MyClass
{
    public function getNumber()
    {
        return once(function () {
            return rand(1, 10000);
        });
    }
}

No matter how many times you run (new MyClass())->getNumber() inside the same request you'll always get the same number.

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Installation

You can install the package via composer:

composer require spatie/once

Usage

The once function accepts a callable.

class MyClass
{
    public function getNumber()
    {
        return once(function () {
            return rand(1, 10000);
        });
    }
}

No matter how many times you run (new MyClass())->getNumber() you'll always get the same number.

The once function will only run once per combination of argument values the containing method receives.

class MyClass
{
    /**
     * It also works in static context!
     */
    public static function getNumberForLetter($letter)
    {
        return once(function () use ($letter) {
            return $letter . rand(1, 10000000);
        });
    }
}

So calling MyClass::getNumberForLetter('A') will always return the same result, but calling MyClass::getNumberForLetter('B') will return something else.

Flushing the cache

To flush the entire cache you can call:

Spatie\Once\Cache::flush();

Disabling the cache

In your test you probably don't want to cache values. To disable the cache you can call:

Spatie\Once\Cache::disable();

You can re-enable the cache with

Spatie\Once\Cache::enable();

Behind the curtains

Let's go over the code of the once function to learn how all the magic works.

In short: it will execute the given callable and save the result in the static $values property of Spatie\Once\Cache. When we detect that once has already run before, we're just going to return the value stored inside the $values array instead of executing the callable again.

The first thing it does is calling debug_backtrace. We'll use the output to determine in which function and class once is called and to get access to the object that function is running in. Yeah, we're already in voodoo-land. The output of the debug_backtrace is passed to a new instance of Backtrace. That class is just a simple wrapper so we can work more easily with the backtrace.

$trace = debug_backtrace(
    DEBUG_BACKTRACE_PROVIDE_OBJECT, 2
)[1];

$backtrace = new Backtrace($trace);

$object = $backtrace->getObject();

Next, we calculate a hash of the backtrace. This hash will be unique per function once was called in and the values of the arguments that function receives.

$hash = $backtrace->getHash();

Finally we will check if there's already a value stored for the given hash. If not, then execute the given $callback and store the result in Spatie\Once\Cache. In the other case just return the value from that cache (the $callback isn't executed).

if (! Cache::has($object, $hash)) {
    $result = call_user_func($callback, $backtrace->getArguments());

    Cache::set($object, $hash, $result);
}

return Cache::get($object, $hash);

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

We publish all received postcards on our company website.

Credits

Credit for the idea of the once function goes to Taylor Otwell. The code for this package is based upon the code he was kind enough to share with us.

Support us

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.

License

The MIT License (MIT). Please see License File for more information.

You can’t perform that action at this time.