Home

Awesome

Div PHP Laze

laze is a PHP library designed for defining lazy evaluation. Values are set as closures and only materialize upon first access, ensuring efficient and controlled initialization. Once a closure function is evaluated, it becomes immutable and cannot be redefined as a different value. However, it can be redefined as a closure until it’s accessed, at which point it transforms into a non-closure value.

laze might be an English word that suggests relaxation or laziness, but in this context, it’s actually an acronym derived from Lazy Evaluation. This refers to a programming technique where the evaluation of an expression is delayed until its value is needed. With laze, once the value is evaluated, it becomes an immutable value. In other words, a value that, although evaluated with delay, cannot be modified after its initial evaluation. Thus, laze encapsulates the concept of deferred evaluation that results in a definitive value, combining flexibility and robustness into one concept.

Installation

You can install laze using Composer:

composer require divengine/laze

Usage

Defining a Lazy Constant

To define a lazy constant, use the laze::define method. The value must be provided as a closure.


use divengine\laze;

// Define a lazy constant
laze::define('MY_CONSTANT', fn() => computeExpensiveValue());

Reading a Lazy Constant

To access the value, use the Laze::read method. The closure will be evaluated on the first access, and the result will be stored as the constant's value.

$value = laze::read('MY_CONSTANT');

Basic example

use divengine\laze;

// Define a lazy constant. Simulate an expensive computation
laze::define('MY_CONSTANT', fn() => return rand(1, 100)); 

// First access, the closure is evaluated
$value = laze::read('MY_CONSTANT');
echo $value; // Outputs the evaluated value

// Subsequent access returns the stored value
$value = laze::read('MY_CONSTANT');
echo $value; // Outputs the same value as before

Comprehensive example

This example covers the full range of Laze's capabilities in a concise manner suitable for a README, showing how it can be applied in real-world scenarios.


interface Configurable {
    public function configure(array $settings): void;
}

class AppConfig implements Configurable {
    private array $settings;

    public function configure(array $settings): void {
        $this->settings = $settings;
    }

    public function getSetting(string $key) {
        return $this->settings[$key] ?? null;
    }
}

// 1. Add a constraint to ensure a value implements the Configurable interface
laze::constraint(
    name: 'Must implement Configurable interface',
    fn($key, $value) => $key == 'APP_CONFIG' ? $value instanceof Configurable : true
);

// 2. Define a lazy value that returns a closure
laze::define('MY_FUNCTION', function() {
    return function() {
        return "Function Result";
    };
});

// 3. Define a lazy value with an object instance
laze::define('APP_CONFIG', function() {
    $config = new AppConfig();
    $config->configure([
        'timezone' => 'UTC',
        'locale' => 'en_US'
    ]);
    return $config;
});

// 4. Reuse define and read within each other
laze::define('FINAL_MESSAGE', function() {
    $config = laze::read('APP_CONFIG');
    $timezone = $config->getSetting('timezone');
    return laze::read('MY_FUNCTION')() . " in timezone $timezone";
});

$finalMessage = laze::read('FINAL_MESSAGE');
echo $finalMessage; // Outputs: "Function Result in timezone UTC"

// 5. PHPUnit Test - Redefining a value
class LazeTest extends \PHPUnit\Framework\TestCase {
    public function testAppConfigCanBeMocked() {

        // mock function
        laze::define('MY_FUNCTION', function() {
            return function() {
                return "Mocked Result";
            };
        });

        // mock object
        laze::define('APP_CONFIG', function() {
            $mockConfig = $this->createMock(Configurable::class);
            $mockConfig->method('getSetting')->willReturn('mocked_timezone');
            return $mockConfig;
        });

        $message = laze::read('FINAL_MESSAGE');
        $this->assertEquals("Mocked Result in timezone mocked_timezone", $message);
    }
}

How to reset Laze during testing

If you need to reset Laze during testing, you have two options:

  1. Using reflection to reset the internal state of Laze.

    class LazeTest extends \PHPUnit\Framework\TestCase {

    public $lazeBackup;

    public function setUp(): void {
        parent::setUp();
        $reflection = new ReflectionClass(laze::class);
        $property = $reflection->getProperty('store');
        $property->setAccessible(true);
        $this->lazeBackup = $property->getValue();
    }

    public function tearDown(): void {
        $reflection = new ReflectionClass(laze::class);
        $property = $reflection->getProperty('store');
        $property->setAccessible(true);
        $property->setValue($this->lazeBackup);
        parent::tearDown();
    }
}

  2. If you are using phpunit, then use it with the parameter --process-isolation to run each test in a separate process.

    vendor/bin/phpunit --process-isolation

Utility of this library

License

This project is licensed under the GNU GENERAL PUBLIC LICENSE. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.

About

laze is developed and maintained by Divengine Software Solutions. If you find this library useful, please consider starring the repository and sharing it with others.