Schema Renderer Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require cycle/schema-renderer
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Cycle\SchemaRenderer\ServiceProvider"
   

2. Basic Setup Register the SchemaRenderer service in your Laravel container (if not auto-discovered):

   $this->app->bind('schema-renderer', function ($app) {
       return new \Cycle\SchemaRenderer\Renderer($app['cycle.orm']);
   });
   

3. First Use Case: Rendering a Schema Inject the renderer into a controller or service:

   use Cycle\SchemaRenderer\Renderer;
   
   public function showSchema(Renderer $renderer)
   {
       $schema = $renderer->render();
       return response()->json($schema);
   }
   

   This generates a JSON schema of your Cycle ORM entities, now including improved relation block handling (e.g., COLLECTION_TYPE support) introduced in v1.4.0.

Implementation Patterns

Common Workflows

1. Schema for API Documentation Use the renderer to auto-generate OpenAPI/Swagger schemas from your Cycle entities:

   $schema = $renderer->render(['include' => ['User', 'Post']]);
   // Integrate with `darkaonline/l5-swagger` or `zircote/swagger-php`
   

2. Validation Layer Dynamically validate incoming requests against your database schema:

   $validator = Validator::make($request->all(), $renderer->getValidationRules());
   

3. Database Migration Generation Extract schema definitions to generate migrations:

   $tables = $renderer->renderTables();
   // Use `spatie/laravel-migration-sniffer` to parse and convert
   

4. Relation-Aware Rendering (New in 1.4.0) Leverage improved relation handling (e.g., COLLECTION_TYPE) for accurate schema representation:

   $schema = $renderer->render(['include' => ['User'], 'withRelations' => true]);
   // Now properly resolves collection-type relations (e.g., hasMany, belongsToMany)
   

Integration Tips

• Laravel Scout: Use rendered schemas to define searchable fields, now with better relation support.
• Laravel Nova: Customize Nova tooling with schema-aware field definitions, including relation metadata.
• GraphQL: Generate GraphQL schemas from Cycle entities (e.g., with webonyx/graphql-php), now with refined relation types.

Gotchas and Tips

Pitfalls

1. Circular References If entities reference each other (e.g., User hasMany Post, Post belongsTo User), the renderer may hang. Use:

   $renderer->render(['maxDepth' => 2]); // Limit recursion depth
   

2. Ignored Fields Fields marked @Column(ignore: true) or excluded via $renderer->ignoreFields() won’t appear in the output.

3. Performance Rendering large schemas can be slow. Cache results:

   $schema = Cache::remember('cycle_schema', now()->addHours(1), function () use ($renderer) {
       return $renderer->render();
   });
   

4. Relation Block Quirks (New in 1.4.0) Ensure relation blocks (e.g., hasMany, belongsToMany) are correctly mapped. Test with:

   $renderer->render(['debugRelations' => true]); // Logs relation parsing issues
   

Debugging

• Schema Mismatches: Compare rendered output with your expected structure using:

  php artisan schema:diff
  

• Type Errors: Ensure Cycle ORM types (e.g., string, int) match the renderer’s expectations. Use:

  $renderer->setTypeMapper(new CustomTypeMapper());
  

• Relation Debugging: For issues with COLLECTION_TYPE or other relation types, inspect the raw schema:

  $rawSchema = $renderer->render(['raw' => true]);
  

Extension Points

1. Custom Formatters Override the default JSON output:

   $renderer->setFormatter(new \Cycle\SchemaRenderer\Formatters\YamlFormatter());
   

2. Schema Hooks Modify the schema before rendering:

   $renderer->beforeRender(function ($schema) {
       $schema['metadata']['version'] = '1.0.0';
       return $schema;
   });
   

3. Entity Exclusions Exclude entire entities or namespaces:

   $renderer->excludeEntities(['App\Models\Draft']);
   

4. Relation-Specific Customization (New in 1.4.0) Extend relation handling for custom types:

   $renderer->extendRelationType('COLLECTION_TYPE', function ($relation) {
       return ['type' => 'array', 'items' => $relation->getTargetSchema()];
   });