Database Laravel Package

Technical Evaluation

Architecture Fit

• PDO-like API with enhanced capabilities: The package provides a familiar PDO interface while adding advanced features like ActiveRow, Selection, and Explorer abstractions, making it a strong fit for Laravel applications where query complexity and maintainability are priorities.
• Multi-driver support: Native drivers for MySQL, PostgreSQL, SQLite, MS SQL Server, and Oracle align with Laravel’s polyglot persistence needs, though Laravel’s Eloquent primarily uses MySQL/PostgreSQL/SQLite.
• Fluent query builder: The Selection API enables method chaining (e.g., $selection->where()->orderBy()), which is intuitive for Laravel developers accustomed to Eloquent’s query builder.
• Reflection layer: Schema introspection (Table, Column, ForeignKey) can complement Laravel’s migrations and model metadata, though Eloquent already handles this via Schema and Blueprint.
• Transaction management: Built-in transaction() support with nested transactions is a plus for Laravel’s service-layer use cases, though Laravel’s DB::transaction() is already robust.

Integration Feasibility

• Laravel’s dependency injection (DI) compatibility:
  • The package uses Nette DI, which is not native to Laravel (Laravel uses PHP-DI or Laravel’s service container). Integration would require:
    • Wrapping the package in a Laravel service provider to bridge DI containers.
    • Exposing Laravel’s DB facade or PDO connections as nette/database Connection instances.
  • Risk: DI container mismatches could lead to configuration complexity or runtime errors.
• Eloquent vs. nette/database:
  • Overlap: Both provide query builders, ORM-like features (ActiveRow ≈ Eloquent models), and migrations.
  • Divergence: Eloquent’s active record pattern is tightly coupled with Laravel’s ecosystem (e.g., events, observers), while nette/database is more procedural/fluent.
  • Recommendation: Use nette/database for complex queries (e.g., multi-table joins, dynamic SQL) while keeping Eloquent for model-centric CRUD.
• Database agnosticism:
  • Laravel’s Eloquent is MySQL-first, with partial PostgreSQL/SQLite support. nette/database’s uniform API across drivers could simplify multi-database projects (e.g., read replicas, analytics databases).

Technical Risk

• Breaking changes in v4.0.0:
  • Removal of Connection::getPdo() and getDsn() could break Laravel’s DB::connection() integration if not abstracted.
  • Mitigation: Use adapter classes to translate Laravel’s Connection to nette/database’s Explorer.
• PHP 8.1+ requirement:
  • Laravel 10+ supports PHP 8.1+, so this is non-blocking for modern stacks.
• Performance implications:
  • ActiveRow and Selection add abstraction layers. Benchmark against Eloquent’s raw queries for write-heavy workloads.
  • Risk: Overhead in high-frequency queries (e.g., API rate-limited endpoints).
• Missing Laravel integrations:
  • No native support for:
    • Laravel’s query scopes (would need custom macros).
    • Eloquent events (e.g., retrieved, saved).
    • Model observers (would require event listeners).
  • Workaround: Use Laravel’s event system to bridge gaps.

Key Questions

1. Use Case Alignment:
   • Is nette/database being considered for complex reporting queries, legacy system migration, or replacing Eloquent entirely?
   • If the latter, assess the effort to port Eloquent models to ActiveRow.
2. Driver Prioritization:
   • Which databases are in scope? (e.g., Oracle/MS SQL Server may need extra validation.)
3. DI Strategy:
   • How will the Nette DI container coexist with Laravel’s service container? (e.g., hybrid binding, facade wrappers).
4. Testing Overhead:
   • Will existing Laravel tests (e.g., Pest/PHPUnit) need adapters for nette/database’s exceptions (e.g., DeadlockException)?
5. Migration Path:
   • Can queries be gradually migrated from Eloquent to nette/database, or is a big-bang rewrite required?

Integration Approach

Stack Fit

• Laravel Core Compatibility:
  • Database: Works with Laravel’s DB facade via PDO abstraction (all supported drivers are PDO-compatible).
  • Query Builder: Can replace or extend Laravel’s query builder for custom syntax (e.g., Selection::joinLeft()).
  • Migrations: Schema reflection (Table, Column) can generate migration files or validate existing ones.
  • Eloquent: Not a drop-in replacement, but ActiveRow can mirror Eloquent’s active record pattern with custom traits.
• Ecosystem Gaps:
  • No Laravel-specific features: Missing support for:
    • Soft deletes (use ActiveRow events or custom logic).
    • Global scopes (implement via Selection macros).
    • Relationships (e.g., hasMany): Would require manual Selection chaining or a custom ORM layer.
  • Workaround: Build a thin adapter layer to translate Laravel conventions to nette/database methods.

Migration Path

1. Phase 1: Query Layer Replacement

   • Replace raw SQL and complex Eloquent queries with nette/database’s Selection.
   • Example:

     // Eloquent
     User::whereHas('posts')->with(['posts' => fn($q) => $q->where('published', true)])->get();
     
     // nette/database
     $selection = $db->table('users')
         ->join('posts', 'users.id = posts.user_id')
         ->where('posts.published', true)
         ->fetchAll();
     

   • Tooling: Use static analysis (e.g., PHPStan) to identify replaceable queries.

2. Phase 2: Model Layer Adaptation

   • Convert Eloquent models to ActiveRow with traits for shared behavior:

     class User extends ActiveRow
     {
         use \Nette\Database\ActiveRowTrait;
     
         public function getPosts()
         {
             return $this->related('posts', fn($db) => $db->where('published', true));
         }
     }
     

   • Challenge: Eloquent’s magic methods (e.g., user->posts) require manual implementation.

3. Phase 3: Full ORM Replacement (Optional)

   • Build a Laravel-compatible facade over nette/database to unify APIs:

     // Hypothetical facade
     $users = DB::table('users')->where(...)->get(); // Uses nette/database internally
     

   • Risk: High maintenance overhead for Laravel-specific features.

Compatibility

• PDO Abstraction:
  • Laravel’s DB::connection() returns a Connection object. nette/database’s Connection can wrap this:

    $pdo = DB::connection()->getPdo();
    $netteConnection = new \Nette\Database\Connection($pdo, $driver);
    

  • Limitation: Some Laravel-specific PDO attributes (e.g., ATTR_EMULATE_PREPARES) may not translate cleanly.
• Exception Handling:
  • nette/database’s granular exceptions (e.g., DeadlockException) can be caught and re-thrown as Laravel’s QueryException for consistency.
• Type Safety:
  • PHP 8.1+ type hints in nette/database align with Laravel 10+, but return types (e.g., ActiveRow) may clash with Eloquent’s Model expectations.

Sequencing

1. Start with Read-Only Queries:
   • Replace SELECT queries first (lowest risk).
2. Then Write Operations:
   • Test INSERT/UPDATE/DELETE with ActiveRow and transactions.
3. Finally, Migrations:
   • Use Table reflection to generate migration files or validate schemas.
4. Parallelize by Feature:
   • Reporting: Use nette/database for analytics queries.
   • Legacy Systems: Migrate old PDO codebases first.
   • New Features: Adopt nette/database for greenfield components.

Operational Impact

Maintenance

• Dependency Management:
  • nette/database is independent of Laravel, reducing vendor lock-in but increasing manual integration effort.
  • Versioning: Laravel’s LTS cycles (e.g., 10.x) may not align with nette/database’s releases (e.g., v3.x → v4.x).
  • Mitigation: Pin to a stable minor version (e.g., ^3.2) and monitor for Laravel-breaking changes.