API Reference

Complete API documentation for the Laravel Specifications package. This reference covers all interfaces, classes, and methods available in the package.

Core Interfaces

SpecificationInterface

The fundamental contract that all specifications must implement. Defines methods for evaluating candidates and building queries.

Base Classes

AbstractSpecification

The base implementation providing composite operations (AND, OR, NOT) and caching support.

Built-in Specifications

Common Specifications

• WhereSpecification - Basic WHERE clause conditions
• WhereInSpecification - WHERE IN conditions
• WhereBetweenSpecification - BETWEEN range conditions
• WhereNullSpecification - NULL/NOT NULL checks
• WhereHasSpecification - Relationship existence checks

Composite Specifications

• AndSpecification - Combine specifications with AND logic
• OrSpecification - Combine specifications with OR logic
• NotSpecification - Negate a specification

Builders & Facades

SpecificationBuilder

Fluent interface for building complex specifications with method chaining.

Specification Facade

Laravel facade providing convenient access to the builder.

Artisan Commands

make:specification

Generate specification classes with various templates and options.

Traits

CacheableSpecification

Add caching capabilities to your specifications.

Quick Reference

Creating a Specification

use DangerWayne\Specification\Specifications\AbstractSpecification;

class ActiveUserSpecification extends AbstractSpecification
{
    public function isSatisfiedBy(mixed $candidate): bool
    {
        return $candidate->status === 'active';
    }
    
    public function toQuery(Builder $query): Builder
    {
        return $query->where('status', 'active');
    }
}

Using the Fluent Builder

use DangerWayne\Specification\Facades\Specification;

$spec = Specification::create()
    ->where('status', 'active')
    ->whereNotNull('email_verified_at')
    ->whereBetween('age', 18, 65)
    ->build();

$users = User::whereSpecification($spec)->get();

Combining Specifications

$activeSpec = new ActiveUserSpecification();
$premiumSpec = new PremiumUserSpecification();

// AND combination
$activePremium = $activeSpec->and($premiumSpec);

// OR combination
$activeOrPremium = $activeSpec->or($premiumSpec);

// NOT operation
$notActive = $activeSpec->not();

Generating Specifications

# Basic specification
php artisan make:specification UserActiveSpecification

# With model binding
php artisan make:specification UserPremiumSpecification --model=User

# Composite with caching
php artisan make:specification ComplexFilterSpecification --composite --cacheable

Method Index

SpecificationInterface Methods

• isSatisfiedBy() - Evaluate a candidate
• toQuery() - Apply to query builder
• and() - AND combination
• or() - OR combination
• not() - Negation
• getCacheKey() - Cache key generation

SpecificationBuilder Methods

• where() - Add WHERE condition
• whereIn() - Add WHERE IN condition
• whereBetween() - Add BETWEEN condition
• whereNull() - Add NULL check
• whereNotNull() - Add NOT NULL check
• whereHas() - Add relationship check
• build() - Build the specification

Type Reference

Parameter Types

• mixed $candidate - The object or value to evaluate
• Builder $query - Eloquent query builder instance
• SpecificationInterface $specification - Specification instance
• string $field - Database column or field name
• array $values - Array of values for IN conditions

Return Types

• bool - Boolean result from isSatisfiedBy()
• Builder - Modified query builder from toQuery()
• SpecificationInterface - New specification from composite operations
• string - Cache key from getCacheKey()