Criteria: PHP package for managing Criteria Pattern

The Criteria Pattern stands as a powerful tool, often hidden in the shadows of more commonly discussed design patterns. This pattern empowers developers to implement dynamic and customizable queries in their applications, enhancing flexibility and maintainability To facilitate this process, Criteria package provides the shared domain logic that contains abstract criteria implementation that each specific criteria should extend from.

Criteria is a framework-agnostic PHP package that allows managing criteria pattern, streamlining data filtering, sorting, and pagination with ease. By Integrating Criteria into your PHP applications developers will easily adapt to evolving filtering requirements without the need for extensive code modifications.

Prerequisites

Take a look on how to install Composer 2 on your computer to manage packages and its dependencies. We also recommend to check the documentation related the repository pattern that includes useful information about criteria pattern.

Installation

Assuming that Composer is already installed, you can include the package using Composer:

composer require hibit-dev/criteria

Usage

A specific criteria must be created for each use case. It will extend the shared domain logic contained in the abstract criteria implementation. As an illustrative example, we generated UserCriteria that will help us to filter based on name, email, both, or neither of them. Additionally, paginating and sorting the results.

use Hibit\\Criteria;
use Hibit\\CriteriaPagination;

final class UserSearchCriteria extends Criteria
{
    public const PER_PAGE = 10;

    private ?string $email = null;
    private ?string $name = null;

    public static function create(
        string $email = null,
        string $name = null
    ): UserSearchCriteria {
        $criteria = new self(CriteriaPagination::create(self::PER_PAGE));

        if (!empty($email)) {
            $criteria->email = $email;
        }

        if (!empty($name)) {
            $criteria->name = $name;
        }

        return $criteria;
    }

    public function email(): ?string
    {
        return $this->email;
    }

    public function name(): ?string
    {
        return $this->name;
    }
}

Assuming the user repository already exists, the criteria usage will look like as following

use Hibit\\CriteriaPagination;
use Hibit\\CriteriaSort;
use Hibit\\CriteriaSortDirection;

class CriteriaTestClass
{
    public function __invoke(UserRepository $userRepository): array
    {
        // Pagination criteria: limit=10 offset=0
        $pagination = CriteriaPagination::create(10, 0);

        // Sorting criteria: created_at ASC
        $sorting = CriteriaSort::create('created_at', CriteriaSortDirection::ASC);

        // Filter criteria: name=John
        $userSearchCriteria = UserSearchCriteria::create(null, 'John');

        $userSearchCriteria->paginateBy($pagination)->sortBy($sorting);

        return $userRepository->searchByCriteria($userSearchCriteria);
    }
}

At the end, the criteria object is passed to the repository and applied when building the query to retrieve data. Following methods will be accessible within the repository's search function, ensuring the accurate filtering of results.

// Criteria filters
$userCriteria->email();
$userCriteria->name();

// Criteria pagination
$userCriteria->pagination()?->limit()->value();
$userCriteria->pagination()?->offset()->value();

// Criteria sorting
$userCriteria->sort()?->field()->value();
$userCriteria->sort()?->direction()->value();

Note that all values can be nullable when constructing the query within the repository.

Conclusion

The Criteria Pattern is a gem of a design pattern that deserves more recognition and adoption in the world of software development. Its universal applicability across different domains and project types demonstrates its versatility and power. By separating the criteria for queries from the query logic itself, developers can create applications that are flexible, maintainable, and responsive to changing user needs and business requirements.

Credits

Official GitHub: https://github.com/hibit-dev/criteria