Query Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require onemustcode/query
   

   Ensure your project uses Laravel 5.x (last release was 2017).

2. Basic Usage

   use OneMustCode\Query\QueryBuilder;
   
   $query = QueryBuilder::forModel(User::class)
       ->applyRequest($request) // Automatically parses filters, sorting, and pagination
       ->get();
   

3. First Use Case: API Filtering

   // In a controller
   public function index(Request $request) {
       $users = QueryBuilder::forModel(User::class)
           ->applyRequest($request)
           ->get();
   
       return response()->json($users);
   }
   

   Send a request with query params like:

   /api/users?name=John&sort=-created_at&page=2
   

Implementation Patterns

1. Filtering

• Basic Filtering

  QueryBuilder::forModel(User::class)
      ->where('name', 'John')
      ->where('active', true)
      ->get();
  

• Dynamic Filtering from Request

  $query = QueryBuilder::forModel(User::class)
      ->applyRequest($request, [
          'name',       // Exact match
          'email',      // Exact match
          'active',     // Boolean
          'role',       // IN query
          'created_at'  // Date range (format: `created_at[from]=2020-01-01&created_at[to]=2020-12-31`)
      ]);
  

2. Sorting

• Default Sorting

  QueryBuilder::forModel(User::class)
      ->orderBy('name', 'asc')
      ->get();
  

• Dynamic Sorting from Request

  $query = QueryBuilder::forModel(User::class)
      ->applyRequest($request, [], ['name', 'email', 'created_at']);
  

  Request format:

  /api/users?sort=-created_at,name
  

3. Pagination

• Manual Pagination

  QueryBuilder::forModel(User::class)
      ->paginate(10);
  

• Dynamic Pagination from Request

  $query = QueryBuilder::forModel(User::class)
      ->applyRequest($request);
  

  Request format:

  /api/users?page=2&per_page=20
  

4. Relationships

• Eager Loading

  QueryBuilder::forModel(User::class)
      ->with('posts')
      ->applyRequest($request)
      ->get();
  

5. Custom Query Logic

• Extend QueryBuilder

  use OneMustCode\Query\QueryBuilder as BaseQueryBuilder;
  
  class CustomQueryBuilder extends BaseQueryBuilder {
      public function activeOnly() {
          return $this->where('active', true);
      }
  }
  
  // Usage
  CustomQueryBuilder::forModel(User::class)
      ->activeOnly()
      ->applyRequest($request)
      ->get();
  

Gotchas and Tips

Pitfalls

1. Deprecated Laravel Version

   • Last release was for Laravel 5.x. Test thoroughly if using newer versions (e.g., 6.x+).
   • May require polyfills or manual adjustments for newer Laravel features.

2. SQL Injection Risks

   • Always validate/sanitize request inputs before passing to applyRequest().
   • Example:

     $validated = $request->validate([
         'name' => 'sometimes|string',
         'email' => 'sometimes|email',
     ]);
     $query = QueryBuilder::forModel(User::class)
         ->applyRequest($validated);
     

3. Date Range Handling

   • Date ranges (e.g., created_at[from]) assume from and to params. Validate these exist to avoid errors:

     if ($request->has('created_at.from') && $request->has('created_at.to')) {
         $query->whereBetween('created_at', [
             $request->input('created_at.from'),
             $request->input('created_at.to')
         ]);
     }
     

4. Boolean Fields

   • Boolean fields (e.g., active) expect 1/0 or true/false in the request. Explicitly cast if needed:

     $query->where('active', (bool) $request->input('active'));
     

Debugging Tips

1. Log the Final Query

   $query = QueryBuilder::forModel(User::class)
       ->applyRequest($request)
       ->toSql(); // Log this to debug
   dd($query->getBindings());
   

2. Disable Automatic Application

   • Temporarily bypass applyRequest() to debug:

     $query = QueryBuilder::forModel(User::class);
     // Manually add conditions for testing
     

3. Check for Deprecated Methods

   • Some methods may have changed in newer Laravel versions. Refer to the source code for exact implementations.

Extension Points

1. Custom Filter Logic

   • Override the applyFilters method in a custom builder:

     class CustomQueryBuilder extends BaseQueryBuilder {
         protected function applyFilters(array $filters) {
             foreach ($filters as $field => $value) {
                 if ($field === 'custom_field') {
                     $this->where('custom_logic', $value);
                     continue;
                 }
                 parent::applyFilters([$field => $value]);
             }
         }
     }
     

2. Add Custom Sorting Rules

   • Extend the applySorting method to handle custom sort fields:

     protected function applySorting(array $sorts) {
         foreach ($sorts as $sort) {
             if (strpos($sort, 'custom_') === 0) {
                 $this->orderBy('custom_logic_column', $sort[7] ?? 'asc');
                 continue;
             }
             parent::applySorting([$sort]);
         }
     }
     

3. Integration with API Resources

   • Combine with Laravel's API Resources for structured responses:

     return UserResource::collection(
         QueryBuilder::forModel(User::class)
             ->applyRequest($request)
             ->get()
     );
     

Performance Tips

1. Select Specific Columns

   QueryBuilder::forModel(User::class)
       ->select(['id', 'name', 'email'])
       ->applyRequest($request)
       ->get();
   

2. Avoid N+1 Queries

   • Always use with() for relationships:

     QueryBuilder::forModel(User::class)
         ->with('posts.comments')
         ->applyRequest($request)
         ->get();
     

3. Cache Query Results

   • For read-heavy APIs, cache the paginated results:

     return Cache::remember("users_{$request->page}", now()->addHours(1), function() {
         return QueryBuilder::forModel(User::class)
             ->applyRequest($request)
             ->paginate(10);
     });