Shipping Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The sylius/shipping component aligns well with modular Laravel architectures (e.g., DDD, Hexagonal, or component-based designs). Its decoupled models (Shipment, ShippingMethod, ShipmentUnit, etc.) can be integrated as a standalone service layer without tight coupling to Sylius’s full-stack framework.
• Domain-Driven Design (DDD) Compliance: The component’s focus on shipment entities, rules engines, and calculators makes it a natural fit for e-commerce domains where shipping logic is complex (e.g., multi-carrier, dynamic pricing, or conditional rules).
• Laravel Ecosystem Synergy:
  • Leverages Eloquent ORM (via Sylius’s Doctrine integration) but can be adapted to Laravel’s native Eloquent with minimal effort.
  • Supports custom calculators (e.g., flat-rate, weight-based, or API-driven) via a strategy pattern, enabling Laravel’s service container to resolve dependencies dynamically.
  • Event-driven architecture (e.g., ShipmentCreated, ShippingMethodSelected) can integrate with Laravel’s event system or queues for async workflows.

Integration Feasibility

• Core Features:
  • Shipping Methods: Define carriers (e.g., FedEx, UPS) with configurable rules (e.g., "Free shipping over $50").
  • Shipment Units: Split shipments (e.g., separate orders for heavy/light items).
  • Rules Engine: Use PHP callbacks, Symfony expressions, or custom logic to filter available methods (e.g., "Only offer overnight shipping on weekdays").
  • Calculators: Plug in custom cost logic (e.g., distance-based, inventory-driven).
• Laravel-Specific Adaptations:
  • Replace Sylius’s Doctrine ORM with Eloquent models (e.g., Shipment → app/Models/Shipment).
  • Use Laravel’s service providers to bind interfaces (e.g., ShippingMethodRepository) to implementations.
  • API-First: The component’s DTOs and serializers can be mapped to Laravel’s API resources or Sanctum/Passport for headless setups.
• Database Schema:
  • Sylius uses Doctrine, but Laravel’s migrations can replicate the schema with adjustments (e.g., shipments, shipment_units, shipping_methods, shipping_rules).
  • Potential Conflict: Sylius’s sylius_resource bundle adds metadata tables; Laravel’s resourceful controllers can bypass this if using API-only.

Technical Risk

• Dependency Overhead:
  • Sylius components rely on Symfony components (e.g., ExpressionLanguage, Workflow). Laravel’s standalone Symfony packages (e.g., symfony/expression-language) can mitigate this, but version alignment may require careful composer.json management.
  • Risk: Mixing Symfony and Laravel versions could lead to BC breaks (e.g., Symfony 6.x vs. Laravel’s bundled Symfony 5.x).
• Testing Complexity:
  • Sylius’s PHPUnit tests use Doctrine fixtures; Laravel’s database testing (e.g., DatabaseMigrations, DatabaseTransactions) would need adaptation.
  • Mocking: The rules engine and calculators may require custom test doubles for isolation.
• Performance:
  • N+1 Queries: Sylius’s eager-loading strategies (e.g., Shipment::with('units.methods')) must be replicated in Laravel to avoid performance pitfalls.
  • Caching: Laravel’s cache tags or Redis can cache shipping method calculations, but the component’s default caching layer (Symfony Cache) would need integration.

Key Questions

1. Architecture Alignment:
   • How will this component fit into our existing Laravel modules (e.g., Orders, Inventory)? Will we use Laravel’s packages or monolithic controllers?
   • Do we need real-time shipping rates (e.g., API calls to carriers), or is pre-calculated logic sufficient?
2. Customization Depth:
   • Will we extend the rules engine with custom predicates (e.g., "Ship only if inventory > 0")?
   • Are there carrier-specific integrations (e.g., FedEx API) that require custom calculators?
3. Data Migration:
   • How will we seed initial shipping methods/rules? Will we use Laravel’s factories or migrations?
   • Are there legacy shipping tables in our DB that need backward compatibility?
4. Performance:
   • What’s the expected scale (e.g., 100 vs. 10,000 shipments/day)? Will we need database indexing or queue-based processing?
5. Maintenance:
   • Who will own the shipping logic? Will it be a dedicated team or cross-functional?
   • How will we handle Sylius updates (e.g., breaking changes in minor versions)?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Eloquent: Replace Sylius’s Doctrine entities with Laravel’s Eloquent models (e.g., Shipment, ShippingMethod).
  • Service Container: Bind interfaces (e.g., ShippingMethodRepository) to Laravel’s bindings in AppServiceProvider.
  • Events: Map Sylius events (e.g., ShipmentCreatedEvent) to Laravel’s event system or queues (e.g., ShipmentCreated::dispatch()).
  • API Layer: Use Laravel API Resources or Sanctum to expose shipping endpoints (e.g., /api/shipments/{id}/methods).
• Symfony Dependencies:
  • ExpressionLanguage: Install symfony/expression-language via Composer.
  • Workflow: If using Sylius’s workflows (e.g., shipment states), install symfony/workflow and configure in Laravel’s config/workflow.php.
  • Validator: Use Laravel’s validator instead of Sylius’s sylius/validator for form requests.
• Testing:
  • Replace Sylius’s PHPUnit Doctrine extensions with Laravel’s testing helpers (e.g., refreshDatabase()).
  • Use PestPHP or Laravel’s testing tools for behavior-driven tests.

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Goal: Validate core functionality (e.g., shipping method selection, cost calculation).
   • Steps:
     1. Add sylius/shipping to composer.json (with Symfony dependencies).
     2. Create Eloquent models mirroring Sylius’s entities (e.g., app/Models/Shipment).
     3. Implement a basic calculator (e.g., flat-rate) and rule (e.g., "Free shipping over $50").
     4. Test with Laravel’s HTTP tests (e.g., GET /api/shipments/1/methods).
   • Deliverable: A spike demonstrating shipping method selection and cost calculation.

2. Phase 2: Core Integration

   • Goal: Integrate with existing Laravel modules (e.g., Orders, Inventory).
   • Steps:
     1. Database: Run Sylius migrations (adapted for Eloquent) or create custom migrations.
     2. Services: Bind Sylius interfaces to Laravel implementations (e.g., ShippingMethodRepository).
     3. Events: Dispatch Laravel events for Sylius events (e.g., ShipmentCreated → ShipmentCreated::dispatch()).
     4. API: Build endpoints for:
        • Listing available shipping methods (GET /api/shipments/{id}/methods).
        • Calculating costs (POST /api/shipments/{id}/calculate).
        • Creating shipments (POST /api/shipments).
     5. Rules Engine: Extend with custom rules (e.g., inventory checks) via Laravel’s service container.
   • Deliverable: A functional shipping module integrated with orders.

3. Phase 3: Advanced Features

   • Goal: Add complex logic (e.g., multi-carrier, real-time rates).
   • Steps:
     1. Carrier APIs: Integrate with FedEx/UPS APIs via custom calculators.
     2. Workflow: Implement shipment state transitions (e.g., "Pending" → "Shipped") using Laravel’s stateful models or queues.
     3. Caching: Cache shipping method calculations using Laravel’s cache tags or Redis.
     4. Admin Panel: Build a Nova/Livewire interface for managing shipping methods/rules.
   • Deliverable: End-to-end shipping workflow with real-time and cached rates.

Compatibility

• Laravel Versions:
  • Tested with