Weave Code
Rowcast Laravel Package
ascetic-soft/rowcast
Rowcast is a lightweight PDO DataMapper for PHP 8.4+. It maps DB rows to DTOs via reflection with auto/explicit mapping and type conversion, plus a fluent query builder with dialect-aware UPSERT.
Lightweight DataMapper and QueryBuilder over PDO with DTO hydration and type casting
Frequently asked questions about Rowcast
- Can Rowcast replace Eloquent models entirely in a Laravel application?
- Rowcast is designed for specific use cases like bulk operations, reporting, or performance-sensitive APIs rather than full Eloquent replacement. It excels at DTO-first workflows but lacks Eloquent’s built-in relationships, events, or observer patterns. Use it alongside Eloquent for hybrid architectures.
- How does Rowcast handle Laravel’s database connections (e.g., DB::connection())?
- Rowcast’s `Connection` class works directly with PDO, so you can wrap Laravel’s `DatabaseManager` to reuse existing connections. Register it as a singleton in Laravel’s service container for seamless integration. Example: `Connection::create(DB::connection('mysql')->getPdo())`.
- Does Rowcast support Laravel’s query builder features like joins, raw expressions, or scopes?
- Rowcast includes a fluent query builder but doesn’t natively support Laravel’s `DB::raw()` or Eloquent scopes. You’ll need to extend the `QueryBuilder` class or use raw SQL via `->raw()` for complex queries. Check the [documentation](https://ascetic-soft.github.io/Rowcast/) for custom extensions.
- What’s the best way to manage DTOs for Rowcast in a Laravel project?
- DTOs can be manually defined, auto-generated from migrations (e.g., using `laravel-shift/database-to-dto`), or hybrid via PHP 8.2+ attributes. For large projects, consider a code generator to sync DTOs with schema changes. Rowcast’s `Mapping` class lets you override defaults for specific cases.
- How does Rowcast handle database errors like unique constraint violations?
- Rowcast throws `PDOException` by default, which Laravel’s exception handler will catch. For custom handling, wrap operations in a `try-catch` or extend `DataMapper` to throw domain-specific exceptions. Example: `try { $mapper->insert(...); } catch (PDOException $e) { throw new UniqueConstraintViolation(...); }`.
- Is Rowcast compatible with Laravel’s migrations and schema builder?
- Rowcast doesn’t replace Laravel’s migrations but works alongside them. Use it to map DTOs to tables created via migrations. For schema-aware DTO generation, pair it with tools like `laravel-shift/database-to-dto` or write custom migration listeners to sync DTOs with schema changes.
- Can Rowcast handle complex SQL features like JSON columns or composite keys?
- Rowcast supports basic JSON columns via type conversion but requires custom `TypeConverter` implementations for advanced use cases (e.g., `jsonb_column->>'key'`). Composite keys or multi-column inserts need explicit `Mapping` configurations. Check the [query builder docs](https://ascetic-soft.github.io/Rowcast/) for dialect-specific examples.
- How do I test Rowcast in Laravel’s testing environment?
- Mock the `DataMapper` or `Connection` in unit tests using Laravel’s `Mockery` or PHPUnit. For integration tests, use in-memory databases (e.g., SQLite) or transaction rollbacks. Example: `$mapper = $this->mock(DataMapper::class)->makePartial();` Rowcast’s fluent API makes it easy to stub queries.
- What are the performance benefits of Rowcast over Eloquent for bulk operations?
- Rowcast avoids Eloquent’s hydration overhead by mapping rows directly to DTOs via reflection, reducing memory usage and GC pauses. For bulk inserts/updates, it supports batch operations with minimal object creation. Benchmark with tools like `laravel-debugbar` to compare against Eloquent’s `chunk()` or `insert()` methods.
- Are there alternatives to Rowcast for Laravel that support PHP 8.2 or earlier?
- For PHP 8.2 or earlier, consider `spatie/laravel-data` (DTOs without DB mapping) or `doctrine/dbal` (low-level PDO wrapper). For Eloquent-like but lighter alternatives, try `hyperf/database` (Hyperf’s ORM) or `illuminate/database` (Laravel’s core, but without Eloquent). Rowcast’s PHP 8.4 dependency is intentional for modern features like enums and attributes.
Weaver
How can I help you explore Laravel packages today?