Phql Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (though note: this is a PHP package for Phalcon, not Laravel—adaptation required):

   composer require phalcon/phql
   

   For Laravel, you’d need to integrate it via a bridge (e.g., phalcon/incubator or a custom wrapper).

2. First Use Case Write a basic PHQL query in a Laravel service:

   use Phalcon\Db\Adapter\Pdo\Mysql as DbAdapter;
   use Phalcon\Phql\Parser;
   
   // Initialize (adapt to Laravel's DB config)
   $db = new DbAdapter(['host' => 'localhost', 'username' => 'root', 'password' => '', 'dbname' => 'test']);
   $parser = new Parser($db);
   
   // Execute a query
   $result = $parser->parse("SELECT * FROM users WHERE id = :id:", ['id' => 1]);
   

3. Where to Look First

   • PHQL Documentation (core syntax).
   • Laravel’s DB facade for integration hints (e.g., query builder patterns).
   • phalcon/incubator for Laravel-Phalcon bridges (if available).

Implementation Patterns

Workflows

1. Query Building Use PHQL for complex queries where Laravel’s query builder falls short (e.g., nested subqueries, advanced joins):

   $phql = "SELECT u.*, COUNT(r.id) as review_count
            FROM users u
            LEFT JOIN reviews r ON u.id = r.user_id
            WHERE u.status = :status
            GROUP BY u.id";
   $result = $parser->parse($phql, ['status' => 'active']);
   

2. Integration with Eloquent

   • Option 1: Use PHQL in a custom repository layer:

     class UserRepository {
         public function findActiveWithReviews() {
             $phql = "SELECT * FROM users WHERE status = 'active'";
             return $this->parser->parse($phql)->toArray();
         }
     }
     

   • Option 2: Override Eloquent’s query builder (advanced):

     // In a service provider
     Eloquent::macro('phql', function ($query) {
         return $this->parser->parse($query);
     });
     

3. Migrations Use PHQL for data seeding or complex migration logic:

   $parser->parse("INSERT INTO users (name, email) VALUES (:name, :email)",
       ['name' => 'John', 'email' => '[email protected]']
   );
   

Tips

• Leverage Laravel’s DB Facade: Pass Laravel’s connection to PHQL’s adapter:

  $db = DB::connection()->getPdo();
  $parser = new Parser($db);
  

• Hybrid Approach: Use Laravel’s query builder for simple queries and PHQL for complex ones.
• Caching Parsed Queries: Cache parsed PHQL objects if reused (e.g., in a repository).

Gotchas and Tips

Pitfalls

1. Laravel-Phalcon Mismatch

   • PHQL expects Phalcon’s Db\Adapter; Laravel’s DB facade uses PDO directly. Ensure compatibility:

     // May throw errors; test thoroughly
     $pdo = DB::connection()->getPdo();
     $adapter = new DbAdapter(['pdo' => $pdo]);
     

   • Fix: Use phalcon/incubator or a custom adapter wrapper.

2. Parameter Binding Quirks PHQL uses :named placeholders, while Laravel uses ? or named bindings. Ensure consistency:

   // PHQL expects named params
   $parser->parse("SELECT * FROM users WHERE id = :id", ['id' => 1]);
   

3. No ORM Integration PHQL works with raw queries; avoid mixing with Eloquent’s active record unless manually bridged.

4. Performance Overhead PHQL parsing adds a layer of abstraction. Benchmark against raw PDO or Laravel’s query builder for critical paths.

Debugging

• Enable PHQL Logging:

  $parser->setLogger(new \Phalcon\Logger\File('phalcon.log'));
  

• Validate SQL: Use ->getRealSQL() to inspect generated queries:

  $query = $parser->parse("SELECT * FROM users");
  dd($query->getRealSQL());
  

Extension Points

1. Custom Functions Extend PHQL with custom functions via Phalcon\Db\Functions\Specific:

   class CustomFunctions extends \Phalcon\Db\Functions\Specific {
       public function myCustomFunction($parser, $arguments) {
           return "MY_CUSTOM_FUNC({$arguments})";
       }
   }
   $parser->registerFunction('myCustomFunc', new CustomFunctions());
   

2. Query Builder Hooks Intercept PHQL queries in Laravel’s DB facade by extending the query builder:

   DB::extend('phalcon', function ($connection, $query) {
       $parser = new Parser($connection->getPdo());
       return $parser->parse($query->toSql(), $query->getBindings());
   });
   

3. Event Listeners Use Phalcon’s events to modify queries before execution:

   $eventsManager = new \Phalcon\Events\Manager();
   $eventsManager->attach('db', function ($event, $connection) {
       // Modify query here
   });
   $parser->setEventsManager($eventsManager);