vjik/specification

Implementation of Specification pattern

1.0.0 2024-11-21 12:46 UTC

Requires

• php: ^8.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• maglnet/composer-require-checker: ^4.14
• phpunit/phpunit: ^10.5
• roave/infection-static-analysis-plugin: ^1.35
• vimeo/psalm: ^5.26

BSD-3-Clause

• php
• pattern
• specification

README

The package provides PHP implementation of "Specification" software design pattern:

• interface SpecificationInterface and abstract BaseSpecification to create user specifications;
• composite specifications AndSpecification and OrSpecification;
• negation specification NotSpecification.

Requirements

• PHP 8.2 or higher.

Installation

The package could be installed with composer:

composer require vjik/specification

General usage

You can create your own specifications by inheriting from the BaseSpecification class:

use Vjik\Specification\BaseSpecification;
    
/**
 * @template T as User
 * @template-extends BaseSpecification<T>
 */
final class UserIsAdultSpecification extends BaseSpecification
{
    /**
     * @param T $value
     */
    public function isSatisfiedBy(mixed $value): bool
    {
        return $value->age >= 18;
    }
}

$specification = new UserIsAdultSpecification();

// true or false
$specification->isSatisfiedBy($user); 

// throws an exception if user is not adult
$specification->satisfiedBy($user); 

We recommend use static analysis tools like Psalm and PHPStan to improve code quality.

Built-in specifications

You can combine specifications using composite specifications:

use Vjik\Specification\AndSpecification;
use Vjik\Specification\OrSpecification;

// User is adult AND active
$isActiveAdultUserSpecification = new AndSpecification([
    new UserIsAdultSpecification(),
    new UserIsActiveSpecification(),
]);

// User is adult OR user with parents
$userHasAccessSpecification = new OrSpecification([
    new UserIsAdultSpecification(),
    new UserWithParentsSpecification(),
]);

Also, you can use negation specification:

use Vjik\Specification\NotSpecification;

// User is not adult
$userIsNotAdultSpecification = new NotSpecification(
    new UserIsAdultSpecification()
);

Static analysis compatible

Static analysis tools like Psalm and PHPStan helps you to avoid mistakes. For example, Psalm issues:

$userIsAdultSpecification = new UserIsAdultSpecification();

// ERROR: InvalidArgument Argument 1 of UserIsAdultSpecification::isSatisfiedBy expects User, but 'test' provided
$userIsAdultSpecification->isSatisfiedBy('test');

// ERROR: InvalidArgument Argument 1 of UserIsAdultSpecification::satisfiedBy expects User, but 'test' provided
$userIsAdultSpecification->satisfiedBy('test');

// ERROR: InvalidArgument Incompatible types found for T (must have only one of User, Post)
$isActiveAdultUserSpecification = new AndSpecification([
    new UserIsAdultSpecification(),
    new PostIsActiveSpecificaion(),
]);

Documentation

• Internals

If you have any questions or problems with this package, use author telegram chat for communication.

License

The vjik/specification is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.