Symfony Config Schema Gen Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require adamwojs/symfony-config-schema-gen --dev
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       AdamWojs\SymfonyConfigSchemaGenBundle\SymfonyConfigSchemaGenBundle::class => ['dev' => true],
   ];
   

2. First Use Case: Generate a JSON schema for your Symfony configuration:

   php bin/console config:dump-schema > config.schema.json
   

   This creates a config.schema.json file in your project root, representing your entire Symfony configuration structure.

3. Where to Look First:

   • Command Reference: Run php bin/console config:dump-schema --help to explore options like --schema-id, --format, and --pretty-print.
   • Generated Schema: Open config.schema.json to inspect the schema structure, which mirrors your config/packages/*.yaml files.

Implementation Patterns

Workflows

1. Schema-Driven Configuration Validation:

   • Use the generated schema to validate external configuration files (e.g., Docker, CI/CD, or user-provided configs) with tools like ajv or jsonschema.
   • Example: Validate a config/custom.yaml against config.schema.json:

     ajv validate -s config.schema.json -d config/custom.yaml
     

2. Documentation Generation:

   • Convert the schema to Markdown or Swagger/OpenAPI for API documentation. Tools like json-schema-to-markdown can help:

     npx json-schema-to-markdown config.schema.json > CONFIGURATION.md
     

3. IDE Autocompletion:

   • Integrate the schema with your IDE (e.g., PHPStorm, VSCode) for YAML autocompletion. Use plugins like Red Hat's YAML and reference the schema file.

4. CI/CD Validation:

   • Add schema validation to your CI pipeline to catch misconfigurations early:

     # .github/workflows/validate-config.yml
     - name: Validate config schema
       run: ajv validate -s config.schema.json -d config/prod.yaml
     

Integration Tips

• Partial Schema Generation: Generate schemas for specific bundles or extensions:

  php bin/console config:dump-schema --extensions=FrameworkBundle,MonologBundle > partial.schema.json
  

• Custom Schema ID: Override the default schema ID for clarity in distributed systems:

  php bin/console config:dump-schema --schema-id="https://yourdomain.com/schema/config.json"
  

• Pretty-Print for Readability: Use --pretty-print for human-readable output:

  php bin/console config:dump-schema --pretty-print > config.schema.json
  

• Format Flexibility: Generate schemas in other formats (e.g., JSON5, YAML) for specific use cases:

  php bin/console config:dump-schema --format=json5 > config.schema.json5
  

Gotchas and Tips

Pitfalls

1. Dev-Only Bundle: The bundle is marked as dev => true in bundles.php. Ensure it’s not accidentally included in production builds.

2. Schema Drift: The generated schema reflects only the loaded configuration at runtime. If you modify config/packages/*.yaml after generating the schema, regenerate it:

   php bin/console cache:clear && php bin/console config:dump-schema
   

3. Complex Nested Structures: Deeply nested configurations (e.g., multi-level arrays) may produce unwieldy schemas. Use --pretty-print to debug:

   php bin/console config:dump-schema --pretty-print | less
   

4. Extension Whitelisting: The extensions argument filters bundles, but it requires exact bundle class names. Use php bin/console debug:container | grep Bundle to find the correct names.

Debugging

• Schema Validation Errors: If validation fails, compare the generated schema with your config file line-by-line. Use jq to inspect the schema:

  jq '.properties' config.schema.json
  

• Missing Properties: Ensure all custom configuration keys are defined in your YAML files. The schema only includes loaded configurations.

Tips

1. Version Control: Commit config.schema.json to version control to track configuration changes over time.

2. Schema Diffing: Use tools like jsondiff to compare schemas across branches or deployments:

   npx jsondiff config.schema.json config.schema.old.json
   

3. Dynamic Schema Generation: For dynamic configurations (e.g., environment-specific), generate schemas per environment:

   APP_ENV=prod php bin/console config:dump-schema > config.prod.schema.json
   

4. Extending the Schema: The package doesn’t support custom annotations or extensions out-of-the-box, but you can post-process the schema with tools like json-schema-extractor to add metadata.

5. Performance: Schema generation is lightweight, but avoid running it in production. Cache the schema in CI/CD or local development:

   php bin/console config:dump-schema > /tmp/config.schema.json