Hydra Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require api-platform/hydra
   

   Ensure api-platform/core is also installed (Hydra is a subcomponent).

2. First Use Case: Hydra Documentation Generation Hydra generates interactive API documentation (like Swagger/OpenAPI) dynamically. Start by configuring it in config/packages/api_platform.yaml:

   api_platform:
       formats:
           jsonld: ['application/ld+json']
       hydra:
           enabled: true
           output_dir: '%kernel.project_dir%/public/docs'
   

   Run the generator:

   php bin/console api:hydra:generate
   

   Access docs at /docs/index.html.

3. Where to Look First

   • Core Classes: ApiPlatform\Metadata\Resource\ResourceMetadataFactory (for resource metadata).
   • Hydra Generator: ApiPlatform\Hydra\Generator\HydraGenerator (for customization).
   • Configuration: config/packages/api_platform.yaml (hydra section).

Implementation Patterns

Workflows

1. Dynamic Documentation Hydra auto-generates OpenAPI/Swagger docs from your API resources. Extend it by:

   • Adding custom metadata to resources (e.g., @ApiProperty in entities).
   • Overriding the generator to include custom fields or examples:

     // src/Hydra/CustomGenerator.php
     use ApiPlatform\Hydra\Generator\HydraGenerator;
     
     class CustomHydraGenerator extends HydraGenerator {
         public function generate(): void {
             parent::generate();
             // Add custom logic (e.g., inject examples)
         }
     }
     

     Register it in services.yaml:

     services:
         App\Hydra\CustomGenerator:
             decorates: 'api_platform.hydra.generator'
             arguments: ['@.inner']
     

2. Integration with API Platform Hydra works seamlessly with API Platform’s Resource and Operation classes. Use it to:

   • Validate API responses against the generated schema.
   • Generate client SDKs (e.g., OpenAPI Generator integration).

3. Partial Generation Generate docs for specific resources only:

   php bin/console api:hydra:generate --resource=App\Entity\Post
   

Tips for Daily Use

• Cache Docs: Use Symfony’s cache system to avoid regenerating docs on every request:

  # config/packages/api_platform.yaml
  hydra:
      cache: true
  

• Versioning: Generate docs per API version by extending the generator and filtering resources by version.
• Custom Templates: Override Hydra’s Twig templates (located in vendor/api-platform/hydra/templates) for branding or additional UI elements.

Gotchas and Tips

Pitfalls

1. Metadata Conflicts

   • Hydra relies on API Platform’s metadata system. Ensure your entities use @ApiResource and related annotations correctly. Missing or conflicting metadata (e.g., duplicate @ApiProperty) can break doc generation.
   • Fix: Validate metadata with:

     php bin/console debug:api
     

2. Circular References

   • Complex entity relationships (e.g., bidirectional ManyToMany) may cause infinite loops in schema generation.
   • Fix: Use @ApiProperty(ignoreNull: true) or @MaxDepth to limit traversal depth.

3. Output Directory Permissions

   • Hydra writes files to public/docs by default. Ensure the directory is writable:

     chmod -R 755 public/docs
     

4. Deprecated Features

   • Hydra v2+ drops support for older API Platform versions (< 2.6). Check compatibility in the migration guide.

Debugging

• Verbose Output: Run the generator with -v for detailed logs:

  php bin/console api:hydra:generate -v
  

• Dry Run: Test changes locally before deploying by regenerating docs and reviewing the output in public/docs.

Extension Points

1. Custom Schemas Extend Hydra’s schema generation by implementing ApiPlatform\Hydra\Generator\SchemaGeneratorInterface:

   use ApiPlatform\Hydra\Generator\SchemaGeneratorInterface;
   use ApiPlatform\Metadata\Resource\ResourceMetadata;
   
   class CustomSchemaGenerator implements SchemaGeneratorInterface {
       public function generateSchema(ResourceMetadata $resource): array {
           $schema = parent::generateSchema($resource);
           // Modify $schema as needed
           return $schema;
       }
   }
   

   Register it in services.yaml:

   services:
       App\Hydra\CustomSchemaGenerator:
           tags: ['api_platform.hydra.schema_generator']
   

2. Post-Processing Hook into Hydra’s output by extending the generator’s postGenerate method or using Symfony’s event system:

   # config/services.yaml
   services:
       App\EventListener\HydraPostGenerateListener:
           tags:
               - { name: kernel.event_listener, event: api_platform.hydra.post_generate, method: onPostGenerate }
   

3. Non-Standard Formats Hydra supports JSON-LD by default. For custom formats (e.g., YAML), override the generate method in your custom generator and write to a different file extension.

Configuration Quirks

• Base URI: Hydra uses the request’s base URI for links. For local development, ensure your APP_URL env var is set correctly.
• Disabled Features: If Hydra docs appear empty, check hydra.enabled in api_platform.yaml and clear the cache:

  php bin/console cache:clear