Rowcast Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require ascetic-soft/rowcast-bundle
   

   Ensure AsceticSoft\RowcastBundle\RowcastBundle::class is registered in config/bundles.php.

2. Configure config/packages/rowcast.yaml:

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

3. First Use Case: Query Execution Inject DataMapper into a service/repository and execute queries:

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

Implementation Patterns

Core Workflows

1. Schema Definition

   • Attribute-Based: Annotate entities with #[Rowcast\Table] and related attributes:

     #[Rowcast\Table(name: 'users')]
     #[Rowcast\Column(name: 'id', type: 'integer', primary: true)]
     class User {}
     

   • File-Based: Define schema in schema.php or YAML/JSON files (pointed to by rowcast.schema.path).

2. Data Access

   • Use DataMapper for CRUD operations:

     // Insert
     $this->mapper->execute('INSERT INTO users (name) VALUES (:name)', ['name' => 'Alice']);
     
     // Fetch
     $users = $this->mapper->fetchAll('SELECT * FROM users WHERE active = :active', ['active' => true]);
     

3. Migrations

   • Generate migrations from schema:

     bin/console rowcast:make
     

   • Apply migrations:

     bin/console rowcast:migrate
     

4. Console Queries

   • Ad-hoc SQL execution:

     bin/console rowcast:query "SELECT * FROM users WHERE id = :id" --param id=1
     

Integration Tips

• Symfony Forms: Bind DataMapper results to form components for type-safe data handling.
• API Platform: Use DataMapper as a custom data provider for hydrating resources.
• Event Listeners: Decorate DataMapper to log queries or transform results (e.g., for API responses).

Gotchas and Tips

Pitfalls

1. Schema Parser Conflicts

   • If rowcast.schema.path points to a directory, ensure ascetic-soft/rowcast-schema is installed for attribute parsing. Otherwise, fall back to file-based parsing.
   • Fix: Install the schema package:

     composer require ascetic-soft/rowcast-schema
     

2. Profiler Overhead

   • The profiler (rowcast.profiler.enabled) collects query data in memory. For high-traffic apps, limit max_queries to avoid memory spikes.
   • Tip: Disable in production:

     # config/packages/prod/rowcast.yaml
     rowcast:
         profiler:
             enabled: false
     

3. Transaction Nesting

   • nest_transactions: true enables nested transactions. If your database driver doesn’t support savepoints (e.g., MySQL in some configurations), disable it:

     rowcast:
         connection:
             nest_transactions: false
     

4. Migration Table Collisions

   • The default migration table (_rowcast_migrations) might conflict with existing tables. Customize:

     rowcast:
         schema:
             migration_table: app_migrations
     

Debugging

• Query Logging: Enable PDO logging via options:

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

• Profiler Data: Check the Symfony profiler panel under the Rowcast tab for slow queries.

Extension Points

1. Custom Query Builders Override DataMapper to add domain-specific query methods:

   class CustomDataMapper extends DataMapper {
       public function findActiveUsers(): array {
           return $this->fetchAll('SELECT * FROM users WHERE active = 1');
       }
   }
   

   Register it as a service alias.

2. Schema Extensions Extend SchemaParserInterface to support custom attributes or validation rules.

3. Connection Decorators Decorate Connection to add middleware (e.g., query logging, caching):

   $connection = new ConnectionDecorator($originalConnection, function ($query) {
       // Log or transform $query
   });