Orderable Laravel Package

Getting Started

Install via Composer:

composer require vendor/package-name

Publish the package config (if needed) and service provider:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

The package now supports dynamic order-by rule manipulation—key for query builders where sorting logic must be conditionally applied or removed. Start by inspecting the new OrderByManager facade or helper methods like:

• applyOrderByRules($rules) – Applies a predefined set of order-by clauses.
• removeOrderByRules($rules) – Removes specific order-by clauses from the query.

First use case: Dynamically adjust sorting in a Model::query() chain based on user preferences or API parameters:

$query = User::query();
$query->applyOrderByRules(['created_at' => 'desc', 'name' => 'asc']); // Applies both
$query->removeOrderByRules(['name']); // Removes 'name' from the query

Implementation Patterns

Conditional Ordering

Use applyOrderByRules() to enforce consistent sorting across multiple query builders (e.g., admin vs. public views):

// Admin dashboard: Always sort by 'active' status first
$query->applyOrderByRules(['active' => 'desc']);

// Public API: Override with user-provided rules
if ($request->has('sort')) {
    $query->applyOrderByRules($request->sort);
}

Rule Composition

Combine rules dynamically for complex queries:

$baseRules = ['created_at' => 'desc'];
$dynamicRules = ['name' => 'asc'];

// Merge or override rules
$query->applyOrderByRules($baseRules + $dynamicRules);

Integration with Eloquent Scopes

Extend existing scopes to modify order-by rules:

public function scopeWithSort($query, $rules) {
    $query->applyOrderByRules($rules);
    return $query;
}

// Usage:
User::withSort(['email' => 'asc'])->get();

API Parameter Handling

Sanitize and parse API input before applying rules:

$rawSort = $request->input('sort', []); // e.g., ["-created_at", "name"]
$parsedRules = collect($rawSort)->mapWithKeys(fn ($value) => [
    str_replace('-', '', $value) => str_starts_with($value, '-') ? 'desc' : 'asc'
])->toArray();

$query->applyOrderByRules($parsedRules);

Gotchas and Tips

Pitfalls

1. Rule Conflict Resolution:

   • applyOrderByRules() overwrites existing rules by default. Use mergeOrderByRules() (if available) for additive behavior.
   • Test edge cases where rules conflict (e.g., applying ['id' => 'asc'] after ['id' => 'desc']).

2. Performance Impact:

   • Excessive rule manipulation can bloat queries. Cache parsed rules or use removeOrderByRules() to clean up unused clauses.

3. Database Compatibility:

   • Some databases (e.g., SQLite) may ignore case-insensitive collations in ORDER BY. Test with your target DB.

Debugging

• Inspect Applied Rules: Use toSql() to verify the final query:

  dd($query->toSql());
  

• Log Rule Changes: Enable debug mode in the package config to log rule applications/removals.

Extension Points

1. Custom Rule Parsers: Extend the package’s rule parser to support custom formats (e.g., sort=created_at:-desc):

   // In a service provider:
   $parser = app(\Vendor\PackageName\RuleParser::class);
   $parser->extend('custom', fn ($value) => [...]);
   

2. Event-Based Hooks: Listen for orderby.rules.applied events to log or modify rules:

   \Vendor\PackageName\Events\OrderByRulesApplied::class => function ($event) {
       // Modify $event->rules or log them
   };
   

3. Query Builder Integration: For raw DB::table() queries, wrap the query builder in the package’s OrderByManager:

   $manager = app(\Vendor\PackageName\OrderByManager::class);
   $query = $manager->applyTo(DB::table('users'), ['name' => 'asc']);
   

Config Quirks

• Default Rules: Set default rules in config/package-name.php to avoid repetitive code:

  'defaults' => [
      'admin' => ['active' => 'desc'],
      'api'   => ['created_at' => 'desc'],
  ],
  

  Then apply them via:

  $query->applyOrderByRules(config('package-name.defaults.api'));