Pasm Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require boson-php/pasm
   

   Add the service provider to config/app.php under providers:

   Boson\Pasm\PasmServiceProvider::class,
   

2. First Use Case: Basic Query Execution Pasm is a lightweight query builder for working with PASM (PASM Abstract Syntax Model)—likely used for parsing or generating structured queries (e.g., for a custom query language or DSL). Example:

   use Boson\Pasm\Pasm;
   
   $query = Pasm::parse('SELECT * FROM users WHERE id = 1');
   // $query now contains a structured AST (Abstract Syntax Tree) for manipulation.
   

3. Where to Look First

   • src/Pasm.php: Core class for parsing and manipulating queries.
   • tests/: Example usage and edge cases (if available).
   • Documentation (if any): Check for a README.md or inline PHPDoc comments.

Implementation Patterns

1. Query Parsing and Transformation

Use Pasm to parse raw strings into structured ASTs, then modify or validate them:

$ast = Pasm::parse('UPDATE users SET name = ?', ['John']);
$ast->setField('name', 'Jane'); // Hypothetical method; verify API.
$sql = Pasm::compile($ast); // Reconstruct query.

2. Integration with Eloquent

Extend Eloquent queries by intercepting raw SQL:

// In a model or service:
$query = Pasm::parse($user->toSql());
$modifiedAst = $query->addCondition('active', true);
$user->setRawSql(Pasm::compile($modifiedAst));

3. Dynamic Query Building

Build queries programmatically:

$query = Pasm::select()
    ->from('users')
    ->where('id', '=', 1)
    ->where('status', 'IN', ['active', 'pending']);
$sql = Pasm::compile($query);

4. Validation and Sanitization

Use Pasm to validate user input against a schema:

$input = Pasm::parse($userInput);
if ($input->isValid()) {
    // Proceed with safe query.
}

5. Extending the Parser

Register custom syntax or keywords:

Pasm::extend('CUSTOM_KEYWORD', function ($parser) {
    // Custom logic for parsing.
});

Gotchas and Tips

Pitfalls

1. No Official Docs

   • The package is a subtree split of boson-php/boson, so consult its parent repo for context.
   • Assume minimal error messages; debug with var_dump($ast) or Xdebug.

2. AST Structure Assumptions

   • The AST structure may not match SQL directly (e.g., WHERE might be nested under conditions). Inspect parsed output:

     $ast = Pasm::parse('SELECT * FROM users');
     print_r($ast->toArray()); // Reverse-engineer structure.
     

3. Compilation Quirks

   • Pasm::compile() might not handle all SQL dialects. Test with your DB (PostgreSQL, MySQL, etc.).
   • Placeholders (e.g., ?) may require binding separately.

4. Thread Safety

   • Pasm appears stateless, but avoid sharing a single instance across requests if it caches state.

Debugging Tips

• Enable Verbose Parsing:

  Pasm::debug(true); // Hypothetical; check if supported.
  

• Log ASTs:

  file_put_contents(
      'debug_ast.json',
      json_encode(Pasm::parse($query)->toArray(), JSON_PRETTY_PRINT)
  );
  

Extension Points

1. Custom Parsers Override Pasm::parse() or extend the base parser class (if exposed):

   class CustomPasm extends \Boson\Pasm\Pasm {
       protected function parseCustomSyntax($input) { ... }
   }
   

2. Compiler Hooks If Pasm::compile() is extensible, hook into it:

   Pasm::onCompile(function ($ast) {
       // Modify AST before compilation.
   });
   

3. Integration with Boson Since Pasm is part of the boson-php/boson ecosystem, explore how it fits into Boson’s workflow (e.g., for API query building).

Performance

• Avoid Repeated Parsing: Cache parsed ASTs if queries are reused.
• Batch Operations: If supporting bulk queries, parse once and compile in bulk.