Schema Generator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require api-platform/schema-generator --dev
   

   Or use the PHAR version:

   wget https://github.com/api-platform/schema-generator/releases/latest/download/schema.phar
   chmod +x schema.phar
   

2. First Generation: Generate a basic Person class from Schema.org:

   vendor/bin/schema generate https://schema.org/Person
   

   Or via PHAR:

   ./schema.phar generate https://schema.org/Person
   

3. Default Output:

   • Classes are generated in src/Entity/ (configurable).
   • Uses ApiResource attributes for API Platform integration.

First Use Case: Schema.org Model

Generate a Product entity with API Platform attributes:

vendor/bin/schema generate https://schema.org/Product --config=config/schema.yaml

Example schema.yaml:

namespace: App\Entity
outputDir: src/Entity
classes:
  Product:
    properties:
      name:
        type: string
        groups: ['default']
      description:
        type: string
        groups: ['default']
      image:
        type: string
        groups: ['default']

Implementation Patterns

Workflow: Schema-Driven Development

1. Define Schema: Use schema.yaml to customize generation (e.g., add ApiResource operations):

   classes:
     Product:
       operations:
         get:
           method: GET
           uriTemplate: /products/{id}
           normalizationContext:
             groups: ['default']
   

2. Generate and Iterate:

   vendor/bin/schema generate --config=config/schema.yaml
   

   Regenerate after schema updates:

   vendor/bin/schema generate --update
   

3. Integrate with API Platform: Use generated ApiResource classes directly in your API:

   // src/Entity/Product.php (auto-generated)
   #[ApiResource]
   class Product { ... }
   

Common Patterns

• Custom Attributes: Add PHP 8 attributes via config:

  classes:
    Product:
      attributes:
        - #[ORM\Table(name: 'products')]
  

• Doctrine Relations: Define ManyToOne/OneToMany via relations:

  classes:
    Product:
      relations:
        category:
          type: manyToOne
          target: Category
          inversedBy: products
  

• Serialization Groups: Use groups to control serialization:

  properties:
    sku:
      type: string
      groups: ['admin']
  

• OpenAPI Integration: Generate from OpenAPI specs:

  vendor/bin/schema generate --openapi=api/openapi.yaml
  

Integration Tips

1. Symfony Flex Projects: Place schema.yaml in config/packages/schema.yaml for autoloading.

2. CI/CD: Add to composer.json scripts:

   "scripts": {
     "generate:schema": "schema generate --config=config/schema.yaml --update"
   }
   

   Run in CI:

   composer generate:schema
   

3. Version Control: Exclude generated files from Git (add to .gitignore):

   src/Entity/Generated/
   

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Ensure namespace in schema.yaml matches your project (e.g., App\Entity).
   • Use prefix to avoid collisions:

     prefix: App\Entity\Generated\
     

2. Self-Referencing Relations:

   • Explicitly define mappedBy/inversedBy:

     relations:
       parent:
         type: manyToOne
         target: self
         mappedBy: children
     

3. Enum Generation:

   • Schema.org enums (e.g., OfferItemCondition) may require manual tweaks:

     properties:
       condition:
         type: string
         enum: [NEW, USED, REFURBISHED]
     

4. Update Mode:

   • --update may overwrite custom logic. Use sparingly:

     vendor/bin/schema generate --update --dry-run  # Test first
     

Debugging

1. Dry Run: Preview changes without writing files:

   vendor/bin/schema generate --dry-run
   

2. Verbose Output: Enable debug mode:

   vendor/bin/schema generate -v
   

3. Custom Templates: Override Twig templates in config/schema/templates/ to modify output.

Extension Points

1. Custom Logic: Extend generated classes via traits or post-generation scripts:

   // src/Entity/Generated/Product.php (add after generation)
   trait ProductExtensions {
       public function getFormattedPrice(): string { ... }
   }
   

2. Post-Generation Hooks: Use Symfony events to modify classes:

   # config/services.yaml
   App\EventSubscriber\SchemaGeneratedSubscriber:
     tags: [kernel.event_subscriber]
   

3. OpenAPI Extensions: Add custom OpenAPI annotations:

   classes:
     Product:
       openapi:
         - $ref: '#/components/schemas/ProductExtension'
   

Configuration Quirks

1. HTTPS URLs: Always use https://schema.org/ to avoid mixed-content warnings.

2. Reserved Keywords: Avoid PHP reserved words (e.g., class, new) as property names. Use columnPrefix:

   columnPrefix: schema_
   

3. Doctrine Inheritance: Use discriminatorMap for single-table inheritance:

   classes:
     CreativeWork:
       inheritance:
         type: single_table
         discriminatorColumn: type
         discriminatorMap:
           Book: book
           Movie: movie
   

4. Repeatable Attributes: Mark as repeatable in Schema.org:

   properties:
     offers:
       type: Offer
       repeatable: true