Criteria: PHP package for managing Criteria Pattern

  • avatar
  • 5 mins read

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.


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.


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

composer require hibit-dev/criteria


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');


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

// Criteria pagination

// Criteria sorting

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


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.


Official GitHub:

 Join Our Monthly Newsletter

Get the latest news and popular articles to your inbox every month

We never send SPAM nor unsolicited emails


Leave a Reply

Your email address will not be published.

Replying to the message: View original

Hey visitor! Unlock access to featured articles, remove ads and much more - it's free.