Laravel Schematics Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require mtolhuys/laravel-schematics
   php artisan schematics:install
   

   This publishes the config, migrations, and assets.

2. Run Migrations:

   php artisan migrate
   

3. Access the Dashboard: Visit /schematics in your browser to see the interactive model diagram.

First Use Case

• Model Visualization: Open /schematics to view all Eloquent models and their relationships in an interactive diagram.
• Quick Actions: Use the UI to:
  • Add new models via the "+" button.
  • Define relationships (e.g., hasMany, belongsTo) by dragging and dropping between models.
  • Generate migrations, controllers, and form requests with a single click.

Implementation Patterns

Core Workflows

1. Model Management:

   • Create/Edit Models: Use the UI to define models (fields, types, constraints) without manually editing Model classes or migrations.
   • Sync with Code: Click "Sync" to generate or update:
     • Eloquent models (app/Models/).
     • Database migrations (database/migrations/).
     • Resource controllers (app/Http/Controllers/).
     • Form requests (app/Http/Requests/).

2. Relationships:

   • Drag-and-Drop: Connect models visually to define relationships (e.g., User hasMany Post).
   • Auto-Generate Code: Schematics generates the belongsTo, hasMany, etc., methods in your models.

3. Migration Insights:

   • Migration Tracker: View a timeline of ran vs. pending migrations.
   • Auto-Migrate: Enable in config to auto-run migrations when models are saved.

4. Form Generation:

   • CRUD Forms: Generate Create/Update form requests and Blade views for each model.
   • Customization: Override generated files by placing stubs in resources/views/vendor/schematics/.

Integration Tips

• Existing Projects:
  • Use php artisan schematics:scan to import existing models/migrations into the UI.
  • Exclude models from the UI via the schematics.excluded_models config array.
• Custom Stubs:
  • Override default templates by publishing and modifying:

    php artisan vendor:publish --tag=schematics.stubs
    

• API Access:
  • Use the underlying Schematics facade or service container to programmatically:

    use Schematics\Facades\Schematics;
    $model = Schematics::findModel('User');
    

• Testing:
  • Mock the SchematicsService in tests to avoid hitting the database:

    $this->partialMock(Schematics::class, ['findModel']);
    

Gotchas and Tips

Pitfalls

1. Database State Mismatch:

   • Issue: Running php artisan schematics:sync may fail if the database schema doesn’t match the UI state.
   • Fix: Use php artisan schematics:fresh to reset the database and regenerate everything from scratch.

2. Circular Dependencies:

   • Issue: Defining circular relationships (e.g., User hasMany Role and Role belongsTo User) can cause UI freezes or errors.
   • Fix: Avoid circular relationships or use intermediate models (e.g., UserRole pivot table).

3. Migration Conflicts:

   • Issue: Manual migrations outside Schematics may conflict with auto-generated ones.
   • Fix: Exclude manual migrations from Schematics’ tracking via schematics.ignored_migrations.

4. Permission Issues:

   • Issue: The /schematics route may be blocked by middleware (e.g., auth).
   • Fix: Add the route to your app/Http/Kernel.php middleware exceptions or protect it explicitly:

     Route::middleware(['web', 'schematics'])->group(function () {
         // Schematics routes
     });
     

Debugging

• Log Output:

  • Enable debug mode in config/schematics.php to log actions:

    'debug' => env('SCHEMATICS_DEBUG', false),
    

  • Check storage/logs/schematics.log for errors.

• UI Errors:

  • Clear cached views and config:

    php artisan view:clear
    php artisan config:clear
    

  • Disable JavaScript errors in the browser console to isolate issues.

Configuration Quirks

1. Auto-Sync Behavior:

   • Config Key: schematics.auto_sync.
   • Default: false (safe mode). Set to true to auto-generate code on model save (risky for shared environments).

2. Field Type Mapping:

   • Custom Types: Extend the field types by publishing and modifying:

     php artisan vendor:publish --tag=schematics.field_types
     

   • Example: Add a json field type by defining a new class in app/Schematics/FieldTypes/JsonFieldType.php.

3. Excluding Models:

   • Config Key: schematics.excluded_models.
   • Example:

     'excluded_models' => [
         'App\Models\AdminPanel\\*', // Exclude all admin panel models
         'App\Models\UserSetting',   // Exclude specific model
     ],
     

Extension Points

1. Custom Actions:

   • Add buttons to the model toolbar by extending the Schematics\Actions\Action class and registering them in config/schematics.php:

     'actions' => [
         \App\Schematics\Actions\ExportToExcel::class,
     ],
     

2. Event Listeners:

   • Listen to model/relationship changes via events:

     Schematics::listen('model.saved', function ($model) {
         // Trigger custom logic after a model is saved
     });
     

3. API Extensions:

   • Extend the underlying SchematicsService by binding your own implementation:

     $this->app->bind(
         \Schematics\SchematicsService::class,
         \App\Services\CustomSchematicsService::class
     );