Rowcast Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require ascetic-soft/rowcast-bundle:^1.1.11
   

   Ensure RowcastBundle is registered in config/bundles.php:

   AsceticSoft\RowcastBundle\RowcastBundle::class => ['all' => true],
   

2. Configure rowcast.yaml Add a minimal config in config/packages/rowcast.yaml:

   rowcast:
     connection:
       dsn: '%env(DATABASE_DSN)%'
       username: '%env(DATABASE_USER)%'
       password: '%env(DATABASE_PASSWORD)%'
   

3. First Use Case: Querying Data Inject DataMapper into a service/repository:

   use AsceticSoft\Rowcast\DataMapper;
   
   final readonly class UserRepository {
       public function __construct(private DataMapper $mapper) {}
   
       public function findById(int $id): ?array {
           return $this->mapper->findOne('users', ['id' => $id]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Dependency Injection

   • Use DataMapper for CRUD operations (e.g., find, findOne, insert, update).
   • Example:

     $this->mapper->insert('users', ['name' => 'John', 'email' => 'john@example.com']);
     

2. Schema Management (Optional)

   • Define schema via:
     • File-based: Point schema.path to a .php/.yaml file.
     • Attribute-based: Point to a directory (e.g., src/Entity) with annotated classes.
   • Run migrations:

     bin/console rowcast:migrate
     

   • New in v1.1.11: Schema validation now supports inline comments in YAML files for better documentation.

3. Profiler Integration (Dev Only)

   • Enable in dev/rowcast.yaml:

     rowcast:
       profiler:
         enabled: true
     

   • View SQL queries in Symfony Profiler under the Rowcast tab.
   • New in v1.1.11: Profiler now includes query execution time breakdowns per operation.

Integration Tips

• Transaction Handling Use nest_transactions: true in config to auto-commit transactions per request.
• Custom Query Building Leverage Connection directly for raw SQL:

  $pdo = $this->connection->getPdo();
  $stmt = $pdo->query("SELECT * FROM users WHERE active = 1");
  

• Type Safety Combine with PHP 8.4’s typed properties for stricter validation:

  public function __construct(private DataMapper $mapper) {}
  

Gotchas and Tips

Pitfalls

1. Schema Parser Conflicts

   • If schema.path points to a directory but AttributeSchemaParser is missing, fall back to file parsing. Ensure dependencies are installed:

     composer require ascetic-soft/rowcast-schema
     

   • New in v1.1.11: Schema parser now automatically detects missing parsers and suggests fixes.

2. Profiler Overhead

   • Disabling profiler.enabled in production avoids query collection overhead.
   • New in v1.1.11: Profiler now auto-disables in non-dev environments by default.

3. Migration Table Naming

   • Customize migration_table to avoid conflicts with existing tables.

Debugging

• Query Logging Enable PDO logging in rowcast.yaml:

  rowcast:
    connection:
      options:
        PDO::ATTR_ERRMODE: PDO::ERRMODE_EXCEPTION
        PDO::ATTR_EMULATE_PREPARES: false
  

• Console Command Errors Use --verbose for detailed output:

  bin/console rowcast:migrate --verbose
  

  • New in v1.1.11: Added --dry-run flag to preview migrations without execution.

Extension Points

1. Custom Schema Parsers Implement AsceticSoft\RowcastSchema\Parser\SchemaParserInterface for custom schema formats.

   • New in v1.1.11: Added SchemaParserRegistry for dynamic parser registration at runtime.

2. Decorating Connection Extend AsceticSoft\RowcastProfiler\ConnectionProfiler for query interception.

   • New in v1.1.11: Added ConnectionDecorator trait for easier extension.

3. Event Listeners Use Symfony’s event system to hook into kernel.request/kernel.response for transaction management.

Configuration Quirks

• Environment Variables Ensure DATABASE_* env vars are set (e.g., .env):

  DATABASE_DSN=mysql://localhost:3306/db_name
  DATABASE_USER=user
  DATABASE_PASSWORD=pass
  

• Flex Recipe Setup Replace the GitHub endpoint in composer.json with your own for private recipes.
  • New in v1.1.11: Added support for local recipe caching to reduce GitHub API calls.

New Features in v1.1.11

• Schema Documentation: Inline YAML comments are now preserved and rendered in the profiler.
• Profiler Enhancements: Query execution time breakdowns and auto-disabling in production.
• Migration Safety: --dry-run flag for previewing migrations.
• Parser Improvements: Automatic detection of missing parsers and dynamic registration.
• Connection Decorator: Simplified trait for extending Connection.