https://github.com/maartenpaauw/laravel-specification-pattern
Filter an Illuminate collection with specifications.
https://github.com/maartenpaauw/laravel-specification-pattern
laravel laravel-package php specification-pattern
Last synced: 10 months ago
JSON representation
Filter an Illuminate collection with specifications.
- Host: GitHub
- URL: https://github.com/maartenpaauw/laravel-specification-pattern
- Owner: maartenpaauw
- License: mit
- Created: 2022-01-02T11:14:32.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-08-18T07:21:59.000Z (11 months ago)
- Last Synced: 2025-08-18T13:44:32.434Z (11 months ago)
- Topics: laravel, laravel-package, php, specification-pattern
- Language: PHP
- Homepage:
- Size: 162 KB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Codeowners: CODEOWNERS
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Laravel specification pattern
[](https://packagist.org/packages/maartenpaauw/laravel-specification-pattern)
[](https://github.com/maartenpaauw/laravel-specification-pattern/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://github.com/maartenpaauw/laravel-specification-pattern/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
[](https://codecov.io/gh/maartenpaauw/laravel-specification-pattern)
[](https://packagist.org/packages/maartenpaauw/laravel-specification-pattern)
Filter an Illuminate collection with specifications.
## Support me
You can support me by [buying Pennant feature flags for Filament](https://filamentphp.com/plugins/maartenpaauw-pennant).
## Installation
You can install the package via composer:
```bash
composer require maartenpaauw/laravel-specification-pattern
```
You can publish the config file with:
```bash
php artisan vendor:publish --tag="laravel-specification-pattern-config"
```
This is the contents of the published config file:
```php
return [
'collection-method' => 'matching',
];
```
## Usage
Here's how you can create a specification:
```shell
php artisan make:specification AdultSpecification
```
This will generate a specification class within the `App\Specifications` namespace.
```php
*/
class AdultSpecification implements Specification
{
/**
* {@inheritDoc}
*/
public function isSatisfiedBy(mixed $candidate): bool
{
return true;
}
}
```
Imagine we have the following class which represents a person with a given age.
```php
class Person {
public function __construct(public int $age)
{}
}
```
Let's apply the business logic:
```diff
+ * @implements Specification
*/
class AdultSpecification implements Specification
{
/**
* {@inheritDoc}
*/
public function isSatisfiedBy(mixed $candidate): bool
{
- return true;
+ return $candidate->age >= 18;
}
}
```
After applying the bussiness logic we can use the specification by **directly** calling the `isSatisfiedBy`
method or **indirectly** be filtering an eloquent collection by calling the `matching` method.
### Direct
```php
$specification = new AdultSpecification();
// ...
$specification->isSatisfiedBy(new Person(16)); // false
$specification->isSatisfiedBy(new Person(32)); // true
```
### Indirect
```php
$persons = collect([
new Person(10),
new Person(17),
new Person(18),
new Person(32),
]);
// ...
// Returns a collection with persons matching the specification
$persons = $persons->matching(new AdultSpecification());
// ...
$persons->count(); // 2
```
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Maarten Paauw](https://github.com/maartenpaauw)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.