Table Laravel Package

Technical Evaluation

Architecture Fit

• Pattern Alignment: The Table Data Gateway pattern is a strong fit for Laravel applications requiring explicit SQL control without the overhead of Eloquent’s active record. It excels in:
  • Microservices/data layers where raw SQL or Query Builder is preferred over ORM abstractions.
  • Legacy system modernization (e.g., replacing spaghetti queries with structured gateways).
  • Atlas ecosystem integration (if already using Atlas.Mapper or other Atlas packages).
• Separation of Concerns: Encourages clear division between domain logic and persistence, reducing coupling between business rules and database operations.
• Event-Driven Extensibility: Pre/post-event hooks (beforeInsertRow, afterUpdateRow) enable cross-cutting concerns (e.g., logging, validation) without polluting model logic. This aligns with Laravel’s service layer patterns but at a lower level.
• Type Safety: IDE-friendly features (e.g., _TableSelect classes, IteratorAggregate for Row) improve developer velocity and reduce runtime errors (e.g., column typos).

Integration Feasibility

• Laravel Stack Fit:
  • Database Layer: Compatible with Laravel’s connection system (via Atlas’s ConnectionLocator), but requires manual query building (no integration with Laravel’s Builder or Query).
  • Primary Key Constraints: Methods like updateRowPerform() mandate a primary key, which may conflict with:
    • Laravel’s composite keys (e.g., ['user_id', 'post_id']).
    • UUID-based PKs (requires custom adaptation).
  • No Eloquent Replacement: Not designed to replace Eloquent; better suited for data-intensive services or batch operations where Eloquent’s overhead is prohibitive.
• Atlas Synergy:
  • Atlas.Mapper Compatibility: If using Atlas.Mapper, this package provides a consistent data layer for both ORM and raw table operations.
  • Standalone Usability: Can be used independently but lacks Laravel-specific conveniences (e.g., no Model binding, no HasMany relationships).
• Query Builder Gaps:
  • No Laravel Query Builder Integration: Requires manual SQL construction or adaptation of Atlas’s Select objects to Laravel’s Builder.
  • Limited Joins/Aggregations: Focused on single-table operations; complex queries (e.g., joins, subqueries) may require hybrid approaches (e.g., using Laravel’s Query Builder for complex logic, Atlas.Table for CRUD).

Technical Risk

• Stale Codebase:
  • Last Release (2020): Potential risks include:
    • PHP 8.x Incompatibilities: Older versions may lack return_type_declaration, named arguments, or union types.
    • Deprecated Dependencies: Atlas ecosystem packages may have evolved without updates.
  • No Dependents: Lack of adoption suggests untested edge cases (e.g., edge-case SQL dialects, large-scale data operations).
• Breaking Changes:
  • Event Hook Signatures: BC breaks in TableEvents (e.g., beforeUpdateRow() returning ?array) require refactoring existing event listeners.
  • Primary Key Assumption: Hard dependency on PKs may limit flexibility in:
    • Polymorphic relationships.
    • Multi-table inheritance scenarios.
    • Tables without explicit PKs (e.g., some legacy schemas).
• Performance Overhead:
  • Row Validation: Row::assertValidValue() adds runtime checks, which may impact:
    • Bulk operations (e.g., INSERT/UPDATE batches).
    • High-throughput APIs (e.g., 10K+ rows/sec).
  • IteratorAggregate: While useful for iteration, it may introduce memory overhead for large rows.
• Laravel-Specific Gaps:
  • No Migration Support: Requires manual schema management (Laravel’s migrations are not integrated).
  • No Eloquent Events: Missing Laravel’s saving, saved, deleting events; requires custom event mapping.
  • No Soft Deletes: No built-in support for Laravel’s SoftDeletes trait.

Key Questions for TPM

1. Strategic Fit:
   • Is Atlas.Table being considered as a replacement for Eloquent in specific services, or as a complementary layer?
   • Are we already using Atlas.Mapper or other Atlas packages? If not, what’s the justification for adopting Atlas.Table?
2. Technical Debt:
   • How will we handle PHP 8.x compatibility and deprecated dependencies? Will we fork or maintain a patched version?
   • What’s the migration path for existing Laravel models using Eloquent or Query Builder?
3. Primary Key Constraints:
   • Do our tables guarantee primary keys? If not, how will we adapt updateRowPerform()/deleteRowPerform()?
   • How will this interact with composite keys or UUID-based PKs?
4. Performance:
   • Have we benchmarked the overhead of Row::assertValidValue() in bulk operations?
   • Will the IteratorAggregate feature impact memory usage for large rows?
5. Maintenance:
   • Who will triage and apply fixes if critical bugs are found (e.g., SQL injection, edge-case dialect issues)?
   • Is there a plan for long-term maintenance given the stale codebase?
6. Alternatives:
   • Have we compared this to Laravel’s Query Builder, Doctrine DBAL, or custom gateways? What’s the ROI justification?
   • Would Atlas.Mapper alone suffice, or is the Table Data Gateway pattern critical for our use case?

Integration Approach

Stack Fit

• Laravel Integration Points:
  • Database Connections: Atlas.Table uses Atlas’s ConnectionLocator, which can be bridged to Laravel’s DB facade via a custom ConnectionLocator implementation.
  • Query Building: Requires manual adaptation of Atlas’s Select objects to Laravel’s Builder or hybrid usage (e.g., use Atlas.Table for CRUD, Laravel Query Builder for complex queries).
  • Service Container: Can be registered as a Laravel service provider to bind table gateways to interfaces (e.g., TableGatewayInterface).
• Atlas Ecosystem:
  • Atlas.Mapper Integration: If using Atlas.Mapper, Atlas.Table provides a consistent data layer for both ORM and raw table operations.
  • Standalone Usage: For non-Atlas projects, requires manual setup of Atlas’s dependency injection and connection management.
• Complementary Tools:
  • Laravel Migrations: Atlas.Table does not integrate with migrations; schema changes must be managed separately (e.g., via Laravel’s Schema builder).
  • Eloquent Models: Can coexist but requires custom logic to bridge Atlas.Table’s Row objects to Eloquent entities.

Migration Path

1. Assessment Phase:
   • Audit existing Eloquent models and Query Builder usage to identify candidates for Atlas.Table migration.
   • Prioritize high-CRUD services (e.g., admin panels, bulk import/export) where the Table Data Gateway pattern offers the most value.
2. Pilot Implementation:
   • Start with a single table/service to test integration (e.g., a users table with basic CRUD).
   • Implement a custom ConnectionLocator to bridge Atlas.Table to Laravel’s DB facade.
   • Adapt primary key constraints (e.g., add composite key support via custom methods).
3. Hybrid Approach:
   • Use Atlas.Table for CRUD and Laravel Query Builder for complex queries (e.g., joins, aggregations).
   • Example:

     // Atlas.Table for simple CRUD
     $table = new UserTable($connectionLocator);
     $user = $table->fetchRow(1);
     
     // Laravel Query Builder for complex logic
     $query = DB::table('users')->whereHas('posts')->get();
     

4. Event-Driven Extensions:
   • Replace Eloquent observers with Atlas.Table events (e.g., beforeInsertRow for validation).
   • Example:

     class UserTableEvents implements TableEvents {
         public function beforeInsertRow(?array $values): ?array {
             if (empty($values['email'])) {
                 throw new \InvalidArgumentException("Email is required.");
             }
             return $values;
         }
     }
     

5. Full Migration:
   • Gradually replace Eloquent models with Atlas.Table gateways for services where the pattern is beneficial.
   • Update tests to use the new gateway API.

Compatibility