Query Builder Parser Laravel Package

Technical Evaluation

Architecture Fit

• Eloquent/QueryBuilder Alignment: The package is tightly integrated with Laravel’s query builder, making it ideal for applications using Eloquent or raw QueryBuilder. It abstracts the complexity of translating jQuery QueryBuilder JSON rules into SQL/MongoDB queries, reducing boilerplate and manual SQL injection risks.
• Multi-Database Support: Works seamlessly with SQL (via Eloquent/QueryBuilder) and MongoDB (via jenssegers/mongodb), though MongoDB support requires additional setup. This aligns well with Laravel applications using multiple data stores.
• Extensibility: The JoinSupportingQueryBuilderParser extends core functionality for complex joins, though it adds complexity. For most use cases, the base QueryBuilderParser suffices.
• Frontend Agnostic: Designed to work with jQuery QueryBuilder, but the parsed rules can be adapted for other frontend query UIs (e.g., AG Grid, Tabulator) with minimal effort.

Integration Feasibility

• Laravel 12/13 Compatibility: Officially supports the latest LTS releases, ensuring no version conflicts. The package’s active maintenance (last release: 2026-05-07) mitigates long-term risk.
• Dependency Lightweight: Only requires illuminate/database (included in Laravel) and optionally jenssegers/mongodb for MongoDB support. No heavy dependencies or conflicts.
• API Simplicity: The parser follows a predictable pattern:

  $qbp = new QueryBuilderParser(['allowed_columns']);
  $query = $qbp->parse($frontendRules, $queryBuilder);
  $results = $query->get();
  

  This reduces integration complexity and onboarding time.

Technical Risk

• SQL Injection: The package sanitizes inputs by whitelisting allowed columns, but misconfigurations (e.g., passing unfiltered user input) could still pose risks. Mitigation: Enforce strict column whitelisting and validate frontend rules.
• MongoDB Limitations: While MongoDB support exists, it relies on jenssegers/mongodb, which may introduce additional dependencies and edge cases (e.g., schema validation). Risk: Medium if MongoDB is a primary use case.
• Complex Joins: The JoinSupportingQueryBuilderParser adds flexibility but increases integration complexity. Risk: Low for simple queries; high for deeply nested joins.
• Frontend Dependency: Requires jQuery QueryBuilder (or a compatible UI) to generate rules. Risk: Low if the frontend stack is already using this library.

Key Questions

1. Database Strategy:

   • Are we using SQL (Eloquent/QueryBuilder) or MongoDB? If MongoDB, is jenssegers/mongodb already in the stack?
   • Do we need custom query operators beyond what the package supports (e.g., window functions, CTEs)?

2. Frontend Compatibility:

   • Is jQuery QueryBuilder already in use, or will we need to adopt it? Are there alternatives (e.g., AG Grid) that could reuse the parsed rules?

3. Performance:

   • Will dynamic filtering impact query performance at scale? Should we cache parsed queries or optimize whitelisted columns?

4. Security:

   • How will we validate frontend rules before parsing? Are there additional safeguards (e.g., rate limiting) needed for public-facing APIs?

5. Long-Term Maintenance:

   • Does the team have capacity to monitor updates (e.g., Laravel 14 compatibility) or contribute fixes?
   • Are there alternative packages (e.g., Spatie’s query builder) that might better fit future needs?

6. Testing:

   • How will we test edge cases (e.g., malformed JSON, unsupported operators) in CI?
   • Should we mock the parser in unit tests to isolate query logic?

Integration Approach

Stack Fit

• Laravel Core: The package is native to Laravel’s ecosystem, leveraging Eloquent/QueryBuilder and Illuminate/Database. No framework modifications are required.
• Frontend: Primarily designed for jQuery QueryBuilder, but the parsed rules (JSON) can be adapted for other UIs. Example:
  • React/Vue: Use the same rules object to drive a custom query builder.
  • AG Grid/Tabulator: Reuse the parsed SQL/MongoDB query logic with their APIs.
• Database:
  • SQL: Zero configuration for Eloquent/QueryBuilder.
  • MongoDB: Requires jenssegers/mongodb and minor setup (e.g., collection references).
• APIs: Works with REST/Laravel APIs or direct frontend integration (e.g., SPAs calling backend endpoints).

Migration Path

1. Assessment Phase:
   • Audit existing query logic to identify manual SQL parsing or hardcoded filters.
   • Document current frontend query UIs (e.g., jQuery QueryBuilder, custom inputs).
2. Pilot Integration:
   • Start with a non-critical feature (e.g., admin dashboard filters).
   • Replace manual query building with QueryBuilderParser:

     // Before:
     $query = DB::table('users')->where('active', 1)->where('name', 'like', '%tim%');
     
     // After:
     $qbp = new QueryBuilderParser(['active', 'name']);
     $query = $qbp->parse($request->queryBuilderRules, DB::table('users'));
     

3. Frontend Sync:
   • If using jQuery QueryBuilder, ensure the frontend sends rules in the expected format:

     {
       "condition": "AND",
       "rules": [
         {"field": "active", "operator": "equal", "value": 1},
         {"field": "name", "operator": "contains", "value": "tim"}
       ]
     }
     

   • For other UIs, map their inputs to the parser’s expected format.
4. Testing:
   • Validate parsed queries against existing SQL/MongoDB queries.
   • Test edge cases (e.g., empty rules, unsupported operators).
5. Rollout:
   • Gradually replace manual queries in controllers/services.
   • Update documentation for new teams (e.g., "How to Add a Filterable Table").

Compatibility

• Laravel Versions: Officially supports Laravel 12/13; tested down to Laravel 5.5. Use feature flags or composer platform checks to handle older versions if needed.
• PHP Versions: Aligns with Laravel’s requirements (PHP 8.1+ for Laravel 12/13).
• Database Drivers: Works with MySQL, PostgreSQL, SQLite (via Eloquent) and MongoDB (via jenssegers/mongodb).
• Third-Party Libraries:
  • jQuery QueryBuilder: Required for frontend rule generation.
  • yajra/laravel-datatables: Compatible for server-side processing (as shown in the README).

Sequencing

1. Phase 1: Core Integration
   • Replace 3–5 manual query examples with QueryBuilderParser.
   • Test with SQL and MongoDB (if applicable).
2. Phase 2: Frontend Sync
   • Integrate jQuery QueryBuilder (or adapt existing UI).
   • Add client-side rule serialization (e.g., JSON.stringify(rules)).
3. Phase 3: Advanced Features
   • Implement JoinSupportingQueryBuilderParser for complex joins.
   • Add caching for parsed queries (e.g., Laravel’s query cache).
4. Phase 4: Scaling
   • Optimize whitelisted columns for performance.
   • Add input validation for security.

Operational Impact

Maintenance

• Proactive Updates: The package is actively maintained (last release: 2026-05-07) with clear Laravel version support. Subscribe to GitHub releases and Laravel deprecation notices.
• Dependency Management:
  • Monitor illuminate/database and jenssegers/mongodb (if used) for breaking changes.
  • Use Composer’s platform-check to enforce Laravel version compatibility.
• Custom Extensions:
  • If extending functionality (e.g., new operators), document changes and test thoroughly.
  • Contribute fixes upstream if issues are found.

Support

• Troubleshooting:
  • Common issues: malformed JSON rules, unsupported operators, or MongoDB schema mismatches.
  • Debugging steps:
    1. Log the raw frontend rules to verify format.
    2. Check whitelisted columns for typos.
    3. Validate database schema against parsed queries.
• Community Resources:
  • GitHub Issues: 161 stars and active maintenance suggest responsive support.
  • Stack Overflow: Tag laravel and query-builder-parser for community help.
• Internal Documentation:
  • Create a runbook for:
    • Setting up the parser in new