Capyrel Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require julio/capyrel
   

   No additional configuration is needed—Laravel’s auto-discovery handles registration.

2. First Use Case: Run the scaffold command to generate models, controllers, and views for an existing table (e.g., User):

   php artisan model:scaffold User
   

   • Follow the interactive prompts to confirm or customize generation.
   • Use --dry-run to preview changes without writing files:

     php artisan model:scaffold User --dry-run
     

3. Where to Look First:

   • Generated Files: Check app/Models/, app/Http/Controllers/, and resources/views/ for new files.
   • Relationships: Open a generated model (e.g., User.php) to see auto-detected Eloquent relationships like hasMany, belongsTo, etc.
   • Blade Views: Inspect resources/views/users/index.blade.php for embedded loops and relationship displays.

Implementation Patterns

Usage Patterns

1. Incremental Scaffolding:

   • Generate only models or controllers separately:

     php artisan model:scaffold User --models
     php artisan model:scaffold User --controllers
     

   • Use --force to skip confirmations for automation (e.g., CI/CD):

     php artisan model:scaffold --force
     

2. Database-Agnostic Workflow:

   • Specify a database connection for multi-database projects:

     php artisan model:scaffold --connection=pgsql
     

3. API Development:

   • Generate API Resources with eager-loaded relationships to avoid N+1 queries:

     php artisan model:resources User
     

   • Use whenLoaded() in resources to conditionally include relationships.

4. Testing:

   • Generate Pest tests for relationships:

     php artisan model:tests User
     

   • Run tests with:

     php artisan test --filter=relationships
     

5. Livewire Integration:

   • Scaffold Livewire components alongside models:

     php artisan model:scaffold User --livewire
     

   • Generated Livewire components include relationship data binding.

6. Migration Safety:

   • Scan migrations for risky patterns before running them:

     php artisan migrate:safe --check
     

   • Fix warnings (e.g., missing indexes, NOT NULL constraints) before migration.

Workflows

1. New Feature Development:

   • Add a migration → Run model:watch to auto-update models:

     php artisan model:watch
     

   • The watcher injects new relationships into model files in real-time.

2. Legacy Codebase Onboarding:

   • Run model:map to visualize the schema:

     php artisan model:map --format=mermaid
     

   • Paste Mermaid output into GitHub Markdown for documentation.

3. Validation Rules:

   • Generate Form Requests with column-aware validation:

     php artisan model:requests Post
     

   • Customize rules in the generated rules() method (e.g., add min:5 for string fields).

4. Health Checks:

   • Run a full schema audit before major releases:

     php artisan model:scaffold --health-check
     

   • Address warnings (e.g., orphaned FKs, missing indexes).

Integration Tips

1. Customize Generation:

   • Override generated files by placing stubs in config/capyrel.php or publishing the config:

     php artisan vendor:publish --provider="JulioOxalis\Capyrel\CapyrelServiceProvider"
     

   • Extend the ModelGenerator, ControllerGenerator, etc., classes in app/Generators/.

2. Seeders and Factories:

   • Manually add factories to database/factories/ and reference them in generated tests:

     // In UserTest.php
     $user = User::factory()->create();
     

   • Use --factories flag to generate factories alongside models:

     php artisan model:scaffold User --factories
     

3. Livewire Components:

   • Generate Livewire components with pre-bound relationships:

     php artisan model:scaffold User --livewire
     

   • Customize the Livewire class by editing app/Http/Livewire/User/Index.php.

4. Policies and Events:

   • Manually create policies (app/Policies/) and events (app/Events/) after scaffolding, as Capyrel does not auto-generate these.
   • Use the generated model as a starting point for authorization logic.

5. MongoDB Projects:

   • For MongoDB, ensure your migrations define schema conventions (e.g., user_id for references).
   • Use --connection=mongodb to target the correct database.

Gotchas and Tips

Pitfalls

1. Overwriting Existing Files:

   • Capyrel skips existing files by default. Use --force to overwrite:

     php artisan model:scaffold --force
     

   • Tip: Backup critical files (e.g., app/Http/Controllers/UserController.php) before running --force.

2. Circular Dependencies:

   • Capyrel detects circular relationships (e.g., User ↔ Post ↔ User) but may generate ambiguous method names.
   • Fix: Rename relationships manually or adjust the naming_strategy in config.

3. MongoDB Limitations:

   • Foreign key detection relies on naming conventions (e.g., user_id).
   • Tip: Use model:map --connection=mongodb to verify relationships before scaffolding.

4. Soft Deletes:

   • Tables with deleted_at columns require the SoftDeletes trait. Capyrel adds this automatically, but ensure your AppServiceProvider has:

     use Illuminate\Database\Eloquent\SoftDeletes;
     

5. Livewire Component Conflicts:

   • If User/Index.php already exists, Livewire generation may fail.
   • Tip: Use --livewire with --force or manually merge components.

6. Health Check False Positives:

   • Some warnings (e.g., "Dead relationship") may be intentional.
   • Tip: Review the health check output and suppress false positives in config/capyrel.php.

7. Dry-Run Mismatches:

   • --dry-run shows what would be generated, but actual output may differ due to:
     • Custom config overrides.
     • Manual edits to stub files.
   • Tip: Compare diffs with git diff after running --dry-run.

8. Multi-Tenant Projects:

   • Capyrel does not auto-detect tenant-specific tables.
   • Tip: Use --connection=tenant_{id} or filter tables manually.

Debugging

1. Relationships Not Detected:

   • Run model:map to verify foreign keys:

     php artisan model:map --format=both
     

   • Common Causes:
     • Missing indexes on FK columns.
     • Non-standard naming (e.g., author_id vs. user_id).
     • Fix: Add explicit relationships in the model or adjust the fk_strategy in config.

2. Validation Rules Incorrect:

   • Check column types in model:requests --dry-run output.
   • Common Issues:
     • varchar(255) → max:255 may conflict with existing rules.
     • Fix: Override the rules() method in the generated request class.

3. Watch Mode Not Updating:

   • Ensure database/migrations/ is being watched (check terminal output).
   • Fix: Restart the watcher or adjust the --interval (default: 2s).

4. Mermaid Diagram Errors:

   • Complex relationships (e.g., hasManyThrough) may not render cleanly.
   • Tip: Simplify the diagram or use ASCII format:

     php artisan model:map
     

5. Pest Tests Failing:

   • Tests may skip due to missing factories or DB setup.
   • Fix: Uncomment skip() in generated tests or run with --env=testing.

Tips

1. Custom Stubs:

   • Override default templates by copying files from vendor/julio/capyrel/src/Generators/Stubs/ to config/capyrel/stubs/.
   • Example: Customize model.stub to add default scopes.

2. Partial Generation:

   • Generate only specific files (e.g., views or controllers) to avoid clutter:

     php artisan model:scaffold User --views
     

3. Exclude Tables:

   • Skip scaffolding for specific tables by adding them to config/capyrel.php:

     'excluded_tables' => ['migrations', 'failed_jobs'],
     

4. Livewire Props:

   • Generated Livewire components include all relationships by default. Trim unused props in the public $props array