Comparison Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-standard-library/comparison
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Basic Equality Check

   use PhpStandardLibrary\Comparison\Comparator;
   
   $comparator = new Comparator();
   $isEqual = $comparator->equals(42, 42); // true
   $isNotEqual = $comparator->notEquals(42, "42"); // true (strict comparison)
   

3. Where to Look First

   • Comparator class: Core utility for equality checks.
   • OrderComparator class: For sorting and ordering logic.
   • ComparisonException: Handle edge cases (e.g., type mismatches).

Implementation Patterns

Standardizing Equality Checks

Replace ad-hoc ===/!== with reusable methods:

// Before
if ($user->age === 25) { ... }

// After
$comparator->equals($user->age, 25);

Sorting Collections

Use OrderComparator for consistent sorting logic:

use PhpStandardLibrary\Comparison\OrderComparator;

$orderComparator = new OrderComparator();
$users = collect($users)->sortBy(
    fn ($user) => $orderComparator->asc($user->created_at)
);

Domain-Specific Comparisons

Extend the package for custom logic (e.g., comparing DateTime objects):

$comparator->customEquals(
    fn ($a, $b) => $a->format('Y-m-d') === $b->format('Y-m-d'),
    $date1,
    $date2
);

Integration with Laravel

• Service Providers: Bind Comparator/OrderComparator as singletons.
• Form Requests: Validate equality in rules:

  public function rules()
  {
      return [
          'password' => ['required', function ($attribute, $value, $fail) {
              $comparator = app(Comparator::class);
              if (!$comparator->equals($value, $this->repeated_password)) {
                  $fail('Passwords do not match.');
              }
          }],
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Strict Comparisons by Default equals() uses ===; use looseEquals() for == behavior:

   $comparator->looseEquals(42, "42"); // true
   

2. Null Handling Explicitly check for null if needed:

   $comparator->equals($value, null); // false if $value is not null
   

3. Performance in Loops Instantiate comparators once (e.g., as a service container binding) to avoid overhead.

Debugging

• Type Mismatches: Wrap comparisons in try-catch for ComparisonException.
• Custom Logic Errors: Validate closures in customEquals()/customOrder():

  $comparator->customEquals(
      fn ($a, $b) => is_numeric($a) && is_numeric($b) ? $a == $b : false,
      $a,
      $b
  );
  

Extension Points

1. Custom Comparators Implement ComparatorInterface for domain-specific rules:

   class UserComparator implements ComparatorInterface {
       public function equals($a, $b): bool { ... }
   }
   

2. OrderComparator Extensions Add custom sort keys:

   $orderComparator->customOrder(
       fn ($user) => $user->priority ?? 0
   );
   

3. Laravel Macros Extend Comparator via service provider:

   Comparator::macro('isActive', function ($value) {
       return $this->equals($value, true) || $this->equals($value, 'active');
   });