Comparison Laravel Package

Product Decisions This Supports

• Standardizing comparison logic across domain models (e.g., User, Product, Order) to eliminate inconsistencies in sorting/filtering operations, reducing technical debt.
• Accelerating feature development for dynamic sorting/filtering (e.g., e-commerce product listings, admin dashboards, or API endpoints) by replacing ad-hoc usort/array_filter implementations.
• Enabling reusable business logic (e.g., "find all users with balances > $X" or "sort invoices by due date") via consistent Comparable/Equalable interfaces.
• Roadmap alignment: Supports a "build vs. buy" decision by offering a lightweight, dependency-free alternative to custom solutions or heavier libraries (e.g., Doctrine Comparator).
• Use cases:
  • Dynamic UI sorting: Replace frontend JavaScript sorting with backend-validated PHP comparisons (e.g., "Sort by custom priority score").
  • Data validation: Enforce object equality (e.g., Order::equals($request->order)) to prevent duplicate submissions.
  • Analytics/aggregations: Efficiently find min/max values (e.g., Comparator->min($orders) for lowest-priority items).
  • Legacy system integration: Standardize comparisons for migrating from older PHP apps with inconsistent logic.

When to Consider This Package

• Adopt if:

  • Your Laravel/PHP app frequently sorts or filters custom objects (e.g., Eloquent models, DTOs, or value objects) beyond primitive types.
  • You need type-safe, consistent comparisons (e.g., User->greaterThan($threshold)) to replace unreliable >/< operators or usort callbacks.
  • Your team prioritizes maintainability over minimal dependencies (package is ~100 LOC, no external libs, and supports PHP 7.1–8.1).
  • You’re building features requiring complex filtering (e.g., multi-criteria sorts, nested object comparisons) that would otherwise bloat your codebase.
  • You’re using PHP 7.1+ and want to avoid reinventing comparison interfaces/traits.

• Look elsewhere if:

  • Your comparisons are trivial (e.g., only sorting arrays of integers/strings) or handled natively by Laravel (e.g., Collection->sortBy(), Query Builder).
  • You need database-level comparisons (e.g., ORDER BY, WHERE)—this package is for in-memory operations only.
  • Your app has strict dependency restrictions (though this package is zero-dependency).
  • You require advanced features like multi-dimensional sorting, fuzzy matching, or nested object traversal (would need custom extensions).
  • You’re using PHP <7.1 or PHP 8.2+ (package supports 7.1–8.1; check for updates).

How to Pitch It (Stakeholders)

For Executives/Stakeholders: *"This package standardizes how we compare and sort objects in our app—like products, users, or orders—so we can build features faster and with fewer bugs. For example:

• E-commerce: Dynamically sort products by price, rating, or custom priority without writing custom sorting logic every time.
• Admin tools: Filter user lists or transactions with clean syntax (e.g., ‘show only active users with balances > $100’).
• APIs: Return sorted/filtered data consistently without backend inconsistencies.

It’s a 10-line drop-in that replaces hours of custom code, reduces technical debt, and makes our backend more predictable. The tradeoff? A tiny dependency (~100 LOC) that only adds value where we’re comparing objects—not for simple cases. For features like dynamic sorting or complex filtering, this is a no-brainer."*

For Engineers/Developers: *"The phrity/comparison package gives us two powerful tools:

1. Interfaces/traits (Equalable, Comparable, ComparisonTrait) to enforce consistent comparison methods across our domain models. For example:

   class Product implements Comparable {
       use ComparisonTrait;
       public compare($other): int { /* custom logic */ }
   }
   

   Now Product objects can be sorted/filtered anywhere with $product->greaterThan($threshold) or $comparator->sort($products).

2. A Comparator utility to sort/filter collections of these objects with clean, reusable methods:

   $comparator = new Comparator($users);
   $highBalances = $comparator->greaterThan($minBalance);
   $sorted = $comparator->sort();
   

   This replaces messy usort/array_filter calls and works seamlessly with Laravel Collections or Eloquent results.

Why use it?

• Consistency: No more ‘does > work here?’—every object follows the same comparison rules.
• Reusability: Write comparison logic once (e.g., in User or Order), reuse everywhere.
• Performance: Optimized for in-memory operations (benchmarked against native PHP sorting).
• Laravel-friendly: Works with Eloquent models, DTOs, and Collections.

Where to avoid it?

• For primitive types (use native PHP operators).
• For database queries (use Query Builder or raw SQL).
• If you’re already happy with ad-hoc sorting (but ask yourself: how much time will this save long-term?).

Integration tips:

• Add use ComparisonTrait to your models for instant comparison support.
• Extend Laravel’s Collection to include Comparator methods (e.g., Collection::compare()).
• Use Comparator in API controllers or admin panels for dynamic sorting/filtering.

Risk: Minimal—this is a battle-tested, lightweight utility. The only cost is adopting the interfaces, but the payoff is cleaner, faster development for comparison-heavy features."*