Schema Generator Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package excels at automating JSON Schema generation from PHP objects (DTOs, entities, enums, value objects) with type hints, aligning well with Laravel’s API-first and contract-first development needs. It is particularly valuable for:
  • OpenAPI/Swagger documentation (partial schema generation for components/schemas).
  • Request/response validation (e.g., integrating with zircote/swagger-php or darkaonline/l5-swagger).
  • Code-first API design where schemas are derived from domain models.
• Laravel Synergy:
  • Complements Laravel’s Form Request validation (e.g., Illuminate\Validation\Validator) by providing structured schemas.
  • Useful for Lumen or API-heavy Laravel apps where manual schema documentation is cumbersome.
  • Can integrate with Laravel Fortify/Sanctum for auth-aware schema generation (via set* methods).
• Limitations:
  • Not a full OpenAPI generator: Only handles components/schemas; missing paths, security, or servers. Requires manual OpenAPI assembly (e.g., using cebe/php-openapi).
  • Apie-specific abstractions: Relies on Apie traits/interfaces (e.g., DtoInterface, StringValueObjectInterface). Custom Laravel models may need adapters.

Integration Feasibility

• PHP Compatibility: Works with PHP 8.0+ (Laravel 9+/10+). No major version conflicts with Laravel’s dependencies.
• Dependency Overlap:
  • Requires cebe/php-openapi (for schema output), which is already used in some Laravel OpenAPI tools (e.g., darkaonline/l5-swagger).
  • No conflicts with Laravel’s core (e.g., Illuminate containers, Facades).
• Testing:
  • Minimal test coverage in the package itself (monorepo structure may complicate CI/CD).
  • Recommendation: Write integration tests for schema generation against Laravel’s Validator or OpenApi\Generator.

Technical Risk

Key Questions

1. Schema Reuse:

   • How will generated schemas be reused across Laravel’s layers (e.g., validation, API responses, database migrations)?
   • Example: Can schemas auto-generate Laravel FormRequest rules or Illuminate\Database\Eloquent casts?

2. Customization:

   • How will Laravel’s native types (e.g., Carbon, Illuminate\Support\Collection) be mapped?
   • Solution: Extend ComponentsBuilderFactory or create a Laravel-specific adapter.

3. Tooling Integration:

   • Will this replace or complement existing tools like:
     • darkaonline/l5-swagger (OpenAPI generation)?
     • spatie/laravel-fractal (API resource schemas)?
   • Tradeoff: This package is lighter but less feature-complete.

4. CI/CD Impact:

   • How will schema generation be triggered (e.g., on php artisan commands, Git hooks, or deploy)?
   • Recommendation: Add a php artisan apie:generate-schemas command.

5. Long-Term Maintenance:

   • Who will maintain the Laravel-specific integration (e.g., handling Illuminate types)?
   • Option: Fork and extend the package or contribute upstream.

Integration Approach

Stack Fit

• Primary Use Cases:
  • API Documentation: Generate components/schemas for Swagger UI/Redoc.
  • Validation: Auto-generate Laravel FormRequest rules from schemas.
  • Contract Testing: Use schemas for Pact or Postman collections.
• Laravel-Specific Synergies:
  • Form Requests: Convert schemas to rules() arrays (e.g., using Illuminate/Validation).
  • Eloquent Models: Map database fields to schemas (e.g., for API resource responses).
  • API Resources: Integrate with spatie/laravel-fractal to auto-generate schemas for responses.
• Alternatives Considered:
  • zircote/swagger-php: More mature but heavier (full OpenAPI generation).
  • darkaonline/l5-swagger: Laravel-specific but less flexible for custom types.

Migration Path

1. Pilot Phase:
   • Start with DTOs (easiest to map) and generate schemas for a single API endpoint.
   • Example: Replace manual openapi: { ... } annotations in FormRequest with auto-generated schemas.
2. Incremental Adoption:
   • Phase 1: Generate schemas for request DTOs → validate against Laravel Validator.
   • Phase 2: Extend to response models (e.g., API resources) → integrate with spatie/laravel-fractal.
   • Phase 3: Replace manual OpenAPI components/schemas with auto-generated ones.
3. Tooling Layer:
   • Create a Laravel Service Provider to bootstrap ComponentsBuilderFactory and register schemas in the container.
   • Example:

     // app/Providers/ApieSchemaServiceProvider.php
     public function register()
     {
         $this->app->singleton(ComponentsBuilderFactory::class, function () {
             return ComponentsBuilderFactory::createComponentsBuilderFactory();
         });
     }
     

Compatibility

Sequencing

1. Setup:
   • Install dependencies:

     composer require apie/schema-generator cebe/php-openapi
     

   • Publish config (if needed) or extend ComponentsBuilderFactory.
2. Core Integration:
   • Generate schemas for critical DTOs (e.g., auth, core business models).
   • Validate schemas against Laravel’s Validator.
3. Tooling Integration:
   • Add a console command to regenerate schemas on demand:

     // app/Console/Commands/GenerateSchemas.php
     public function handle()
     {
         $factory = app(ComponentsBuilderFactory::class);
         $schemas = $factory->addCreationSchemaFor(MyDto::class)->getComponents();
         file_put_contents(storage_path('app/schemas.json'), json_encode($schemas));
     }
     

4. CI/CD:
   • Add a GitHub Action to validate schemas on PRs (e.g., using phpstan or custom tests).
5. Documentation:
   • Auto-generate Swagger/OpenAPI docs using darkaonline/l5-swagger with the generated schemas.

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: No manual JSON Schema maintenance for DTOs/entities.
  • Single Source of Truth: Schemas derived from PHP types (DRY principle).
• Cons:
  • Dependency on Apie: Future changes to Apie traits may break schema generation.
  • Customization Overhead: Extending for Laravel-specific types (e.g., Carbon) requires effort.
• Mitigation:
  • Abstraction Layer: Create a Laravel-specific adapter class to handle Illuminate types.
  • Version Pinning: Lock apie/schema-generator to a minor version in composer.json.

Support

• Debugging: