Core Laravel Package

Technical Evaluation

Architecture Fit

• Hypermedia & GraphQL API Alignment: API Platform Core excels as a TPM for projects requiring API-first design, hypermedia-driven REST, or GraphQL integration. Its declarative metadata-driven approach (via annotations, attributes, or YAML) aligns well with modular PHP/Laravel/Symfony architectures, reducing boilerplate for CRUD, validation, and serialization.
• Laravel Compatibility: While primarily designed for Symfony, the package includes Laravel-specific fixes (e.g., Eloquent integration, ResourceAccessChecker, HydraSchemaFactory). This makes it viable for Laravel-based TPMs, though some Symfony-centric features (e.g., api_platform_iris route loader) may require workarounds.
• Domain-Driven Design (DDD) Support: Strong entity-relationship modeling (via Doctrine/ODM) and OpenAPI/Hydra documentation generation make it ideal for complex domain layers where API contracts must evolve independently of implementation.
• Extensibility: Hooks for custom filters, serializers, state providers, and validation allow TPMs to override defaults without forking, critical for long-term maintainability.

Integration Feasibility

• Laravel-Specific Challenges:
  • Service Container: Laravel’s IoC container differs from Symfony’s, requiring manual binding of API Platform services (e.g., ApiResource\ResourceInterface, State\ProcessorInterface).
  • Middleware: Laravel’s middleware stack may need adjustments for API Platform’s api_platform.json configuration or GraphQL middleware.
  • Doctrine ORM/ODM: While supported, Eloquent-specific quirks (e.g., casts(), relations()) may need custom metadata providers or filter decorators.
• Symfony Synergy: If the stack includes Symfony components (e.g., Security, Messenger), integration is near-seamless due to shared dependencies.
• GraphQL vs. REST: GraphQL requires additional setup (e.g., api-platform/graphql bundle), but the core package provides shared utilities (e.g., ObjectMapper, State processing).

Technical Risk

Key Questions for TPM

1. Stack Prioritization:
   • Is the project Laravel-first or Symfony-compatible? If Laravel, what’s the Symfony component overlap?
   • Will GraphQL be a phase 2 feature, or is REST-only sufficient initially?
2. Data Layer:
   • Is Doctrine ORM mandatory, or can Eloquent be used with custom metadata?
   • Are there complex nested relationships requiring custom filters/serializers?
3. Performance:
   • What’s the expected API scale (RPS, payload size)? Will serialization caching be needed?
   • Are real-time updates (e.g., Mercure) required?
4. DevOps:
   • How will OpenAPI/Hydra docs be versioned and deployed?
   • Is API security (e.g., OAuth2, JWT) handled by Symfony Security or a custom layer?
5. Team Skills:
   • Does the team have Symfony/Laravel + Doctrine expertise, or will training be required?

Integration Approach

Stack Fit

• Best Fit:
  • Laravel + Symfony Components: Use Symfony’s HttpKernel as a micro-framework or Laravel’s Bridge for shared services.
  • Doctrine ORM: Prefer over Eloquent for consistent metadata handling.
  • GraphQL: Only if API Platform’s GraphQL bundle is added post-MVP.
• Avoid:
  • Pure Laravel: Some Symfony-centric features (e.g., api_platform_iris) may require rewrites.
  • Monolithic APIs: API Platform shines in modular, contract-first designs.

Migration Path

1. Phase 1: REST API Skeleton

   • Install api-platform/core + api-platform/doctrine (for Doctrine).
   • Configure api_platform.json for basic resources (entities with @ApiResource).
   • Test with Symfony’s HttpKernel (if Laravel is the base).
   • Laravel Workaround: Use Laravel’s ServiceProvider to bind API Platform services manually.

2. Phase 2: Customization

   • Add custom filters (e.g., DateFilter, SearchFilter) via decorators.
   • Implement custom state processors for complex business logic.
   • Integrate Symfony Security (if using Laravel, use Laravel’s Auth + API Platform’s ResourceAccessChecker).

3. Phase 3: GraphQL (Optional)

   • Add api-platform/graphql bundle.
   • Configure GraphQL schema alongside REST.
   • Test shared resolvers between REST and GraphQL.

4. Phase 4: Optimization

   • Enable serialization caching (@ApiProperty(serializeAs="...")).
   • Profile Doctrine queries for N+1 issues.
   • Set up Mercure for real-time updates if needed.

Compatibility

Sequencing

1. Core API Contracts:
   • Define entities with @ApiResource.
   • Generate OpenAPI docs and validate with tools like Swagger UI.
2. Business Logic:
   • Implement custom state processors (e.g., Create, Update).
   • Add validation via @Assert or custom constraints.
3. Filters & Sorting:
   • Configure default filters (e.g., DateFilter, SearchFilter).
   • Test nested property filtering.
4. Security:
   • Integrate authentication (JWT/OAuth2) via Symfony’s Security or Laravel’s Sanctum.
   • Use @ApiProperty(security="is_granted('ROLE_ADMIN')") for granular access.
5. Performance:
   • Enable serialization caching.
   • Optimize Doctrine queries (e.g., DQL, QueryBuilder).
6. GraphQL (Optional):
   • Add api-platform/graphql bundle.
   • Map REST resources to GraphQL types.

Operational Impact

Maintenance

• Pros:
  • Declarative metadata reduces boilerplate and merge conflicts.
  • Shared utilities (e.g., State, ObjectMapper) simplify cross-cutting concerns.
  • OpenAPI/Hydra docs auto-update with schema changes.
• Cons:
  • Symfony dependencies may bloat a Laravel project.
  • Custom filters/processors can drift from upstream changes.
• Mitigation:
  • Use composer.lock to pin versions.
  • Isolate custom logic in separate packages (e.g., api-platform-filters).

Support

• Debugging:
  • Symfony Profiler (if using HttpKernel) provides deep request insights.
  • Doctrine Profiler helps optimize queries.
  • GraphQL Playground aids in debugging queries.
• Common Issues: