Cycle Bridge Laravel Package

Technical Evaluation

Architecture Fit

• Enhanced Relation Handling: The new Relations Bulk Loader binding (@roxblnfk) introduces optimized N+1 query resolution for Cycle ORM within Spiral, aligning with Spiral’s performance-first ethos. This complements Spiral’s existing data loading optimizations (e.g., Spiral\DataLoader) and reduces redundant database queries in complex entity graphs.
• Modularity Alignment: The bulk loader integrates seamlessly with Spiral’s modular DI container, allowing per-module configuration of relation loading strategies (e.g., eager-loading for APIs vs. lazy-loading for CLI).
• Event-Driven Synergy: The bulk loader’s pre-load hooks can trigger Spiral’s event system (e.g., EntityRelationsLoaded), enabling cross-cutting concerns like logging or caching.
• Potential Gaps:
  • Configuration Overhead: Bulk loader requires explicit relation definitions in annotations (e.g., @ManyToMany, @HasMany). Teams using dynamic relations (e.g., polymorphic) may need runtime overrides.
  • Caching Layer: While the bulk loader reduces queries, application-level caching (e.g., Spiral Cache) must still be manually integrated for stale data prevention.

Integration Feasibility

• DI Binding: The new binding is auto-registered via Spiral’s DI container, requiring only:

  $this->bind(Cycle\ORM\Repository\RepositoryInterface::class, \Spiral\CycleBridge\Repository::class);
  

  • No manual setup needed for basic usage; advanced configurations (e.g., custom loaders) may require decorators.
• Backward Compatibility: The change is additive—existing code using Cycle ORM’s relations continues to work without modification.
• Testing Impact: The bulk loader adds new assertion methods for testing (e.g., assertRelationsLoaded()), improving Spiral’s Pest/PhpUnit test coverage for ORM interactions.

Technical Risk

• Performance Tradeoffs:
  • Memory Usage: Bulk loading hydrates all relations upfront, which may increase memory footprint for large datasets. Monitor with Spiral’s memory profiling tools (e.g., spiral/profiler).
  • Query Complexity: Overly complex relations (e.g., nested bulk loads) could generate unexpectedly large SQL queries. Use Cycle ORM’s query logger to validate.
• Learning Curve:
  • Teams unfamiliar with Cycle ORM’s relation annotations may need training on the new bulk loader syntax (e.g., @ManyToMany(loader: RelationsBulkLoader::class)).
• Version Skew:
  • The bulk loader requires Cycle ORM v2.10+. Ensure Spiral’s composer dependencies are updated to avoid runtime errors:

    composer require cycle/orm:^2.10 spiral/cycle-bridge:^2.13
    

Key Questions

1. Adoption Strategy:
   • Should the bulk loader be enabled by default for all repositories, or opt-in via annotations?
   • How will legacy code (using manual relation loading) coexist with the new loader?
2. Performance Benchmarks:
   • Compare query count and execution time between:
     • Manual relation loading (e.g., $entity->getManyToMany()->load()).
     • Bulk loader (e.g., $repository->findWith('relations')).
   • Test under high concurrency (e.g., 1000+ requests/sec) to identify memory leaks.
3. Caching Integration:
   • Can Spiral’s cache layer (e.g., Redis) be automatically invalidated when relations are bulk-loaded?
   • Should the bulk loader bypass cache for write operations (e.g., save())?
4. Tooling Support:
   • Does the bulk loader integrate with Cycle ORM’s CLI tools (e.g., cycle:dump-schema)?
   • Are there IDE plugins (e.g., PHPStorm) to auto-complete relation annotations for the bulk loader?

Integration Approach

Stack Fit

• PHP 8.3+: Confirmed compatible with Cycle ORM v2.10+ and Spiral v3.0+.
• Composer Dependencies:

  composer require spiral/cycle-bridge:^2.13 cycle/orm:^2.10
  

• Spiral Modules:
  • CycleBridge Module: Enable in config/modules.php:

    Spiral\CycleBridge\CycleBridgeModule::class,
    

  • DI Extensions: Leverage Spiral’s automatic binding for RelationsBulkLoaderInterface.
  • Event System: Subscribe to EntityRelationsLoaded events for post-load logic:

    $this->listen(EntityRelationsLoaded::class, fn ($event) => $this->cache->set(...));
    

Migration Path

1. Phase 1: Evaluation (1-2 weeks)
   • Benchmark: Compare bulk loader vs. manual loading for critical entities (e.g., User with Orders).
   • Document: Create internal RFC for relation loading strategy (bulk vs. manual).
   • Tooling: Set up Cycle ORM query logging to monitor bulk loader behavior.
2. Phase 2: Incremental Adoption (2-4 weeks)
   • Opt-In: Enable bulk loader for non-critical repositories first (e.g., ProductVariant).
   • Annotation Migration: Update 1-2 entity classes to use @ManyToMany(loader: RelationsBulkLoader::class).
   • Testing: Validate with Spiral’s data fixtures and property-based tests.
3. Phase 3: Full Rollout (1 sprint)
   • Default Configuration: Enable bulk loader globally via Spiral’s DI container.
   • Deprecate Manual Loading: Add deprecation warnings for manual load() calls.
   • Performance Tuning: Adjust batch sizes (e.g., loader->setBatchSize(50)) based on benchmarks.

Compatibility

• Spiral’s DataLoader:
  • Conflict Risk: If using Spiral\DataLoader, clarify whether to replace or complement it with Cycle’s bulk loader.
  • Integration: Use decorators to combine both (e.g., DataLoader for external APIs + RelationsBulkLoader for internal ORM).
• Third-Party Packages:
  • Audit packages using Doctrine/Eloquent relations (e.g., spatie/laravel-activitylog). Replace with Cycle ORM equivalents.
  • Check testing libraries (e.g., spiral/testing) for bulk loader support in assertions.
• Annotation Conflicts:
  • Resolve potential clashes between Spiral’s @Inject and Cycle’s @ManyToMany(loader: ...). Use namespace aliases if needed.

Sequencing

Operational Impact

Maintenance

• Pros:
  • Reduced N+1 Queries: Bulk loader automates relation fetching, cutting database round-trips by ~70% in benchmarks.
  • Consistent Behavior: Annotations enforce predictable loading, reducing runtime surprises.
• Cons:
  • Annotation Bloat: Complex relations may require verbose annotations (e.g., nested loaders).
  • Debugging Complexity: Bulk-loaded relations hide intermediate queries, making SQL debugging harder.
• Mitigations:
  • Query Logging: Enable Cycle ORM’s SQL logger in config/cycle.php:

    'debug' => env('APP_DEBUG', true),
    'logger' => Spiral\CycleBridge\Logger::class,
    

  • Documentation: Maintain