Crudify Laravel Package

Getting Started

To begin using mr.incognito/crudify, install the package via Composer:

composer require mr.incognito/crudify

Start by generating a basic CRUD for a model, e.g., Department, with fields like name and created_by (a nullable foreign key):

php artisan make:crud Department --fields="name:string|max:255;created_by:foreign~|constrained:users"

This creates:

• Model (app/Models/Department.php)
• Migration (database/migrations/..._create_departments_table.php)
• Controller (app/Http/Controllers/Api/DepartmentController.php)
• Form Request (app/Http/Requests/DepartmentRequest.php)
• API Resource (app/Http/Resources/DepartmentResource.php)
• Route in routes/api.php

First Use Case: Quickly scaffold an API for an internal tool (e.g., admin dashboard) without writing boilerplate.

Implementation Patterns

1. API-Centric Workflow

• Generate API CRUD:

  php artisan make:crud User --fields="email:string|email;password:string" --type=api
  

• Extend the Controller: Override methods in UserController (e.g., store() for custom logic) while keeping generated code for standard operations.
• Custom Validation: Modify UserRequest to add rules (e.g., unique:users,email,{$user->id} for updates).

2. Web-Based CRUD with Blade

• Generate Web CRUD:

  php artisan make:crud Product --fields="name:string;price:decimal" --type=web
  

• Customize Views: Edit Blade templates in resources/views/products/ (e.g., add Alpine.js for interactivity).
• Form Requests: Extend ProductRequest for custom authorization (e.g., authorize('update-product')).

3. Partial Generation

• Skip Files: Exclude components like migrations or models:

  php artisan make:crud Setting --fields="key:string;value:text" --exclude=migration
  

  Useful for adding CRUD to existing tables or when migrations are managed elsewhere.

4. Foreign Key Patterns

• Required Foreign Key:

  php artisan make:crud Order --fields="user_id:foreign|constrained:users|onDelete:cascade;product_id:foreign|constrained:products"
  

• Nullable Foreign Key:

  php artisan make:crud Comment --fields="user_id:foreign~|constrained:users;post_id:foreign|constrained:posts"
  

5. Default Values and Constraints

• Add Defaults:

  php artisan make:crud Post --fields="title:string;is_published:boolean~|default:false"
  

• Composite Constraints: Combine modifiers like nullable, default, and onDelete in one field definition.

6. Integration with Existing Code

• Reuse Models/Migrations: Generate only controllers/requests/resources for existing tables:

  php artisan make:crud ExistingModel --exclude=model,migration --type=api
  

• Extend Routes: Manually add custom routes in routes/api.php or routes/web.php for non-standard endpoints.

7. Testing Generated CRUD

• Pest Tests: Use the built-in Pest tests to verify CRUD operations:

  composer test
  

• Custom Tests: Write feature tests targeting the generated controller (e.g., test('create department', fn() => $this->post('/api/departments', [...])).

Gotchas and Tips

Pitfalls

1. Foreign Key Mismatches:

   • If the constrained table doesn’t exist, the migration will fail. Ensure referenced tables (e.g., users) are created first.
   • Fix: Run php artisan migrate after generating the CRUD or create the parent table manually.

2. Route Conflicts:

   • Generating multiple CRUDs with the same plural name (e.g., User and Admin) will overwrite routes.
   • Fix: Use --type=web or --type=api explicitly or manually edit routes/api.php/routes/web.php.

3. Blade Template Overwrites:

   • Regenerating a web CRUD will overwrite Blade views. Backup customizations or use --exclude=views to preserve them.
   • Fix: Store custom views in a separate directory and symlink them post-generation.

4. Nullable Fields in Validation:

   • Fields marked as nullable (~) in the command may still require validation rules in FormRequest. Ensure rules like nullable|string are added.
   • Fix: Manually edit the generated FormRequest to match the nullable status.

5. Default Values in API Resources:

   • Default values in migrations won’t appear in API responses unless explicitly added to the toArray() method in the Resource.
   • Fix: Extend the generated Resource to include defaults:

     public function toArray($request) {
         return array_merge(parent::toArray($request), ['is_published' => true]);
     }
     

6. Delete Command Limitations:

   • The delete:crud command may skip files if they don’t match expected paths (e.g., custom-named migrations).
   • Fix: Use --force to bypass confirmation or manually delete files.

7. Type Safety in Fields:

   • Incorrect field types (e.g., date instead of timestamp) may cause migration errors.
   • Fix: Validate field syntax against Laravel’s migration column types.

Debugging Tips

1. Check Generated Files:

   • Verify the generated migration SQL matches expectations by running:

     php artisan migrate --pretend
     

2. Validation Errors:

   • If validation fails, inspect the FormRequest (e.g., app/Http/Requests/DepartmentRequest.php) for incorrect rules or missing fields.

3. Route Issues:

   • Ensure the generated route doesn’t conflict with existing ones. Check routes/api.php or routes/web.php for duplicates.

4. Foreign Key Errors:

   • If a foreign key constraint fails, run:

     php artisan schema:dump
     

     to reset the database schema or manually adjust the migration.

5. Blade Rendering:

   • Clear cached views if Blade templates don’t update:

     php artisan view:clear
     

Extension Points

1. Custom Templates:

   • Override default Blade templates by publishing them:

     php artisan vendor:publish --tag=crudify-views
     

   • Modify published templates in resources/views/vendor/crudify/.

2. Hooks in Controllers:

   • Extend generated controllers by adding methods (e.g., customLogic()) and calling them in overridden methods like store():

     public function store(Request $request) {
         $this->customLogic();
         return parent::store($request);
     }
     

3. Dynamic Field Generation:

   • Use the package’s field syntax to dynamically generate CRUDs from a database table (e.g., for a "dynamic forms" feature). Parse the table schema to construct the --fields argument.

4. API Resource Extensions:

   • Add custom relationships or computed attributes in the Resource:

     public function toArray($request) {
         return [
             'id' => $this->id,
             'name' => $this->name,
             'full_url' => route('api.products.show', $this),
         ];
     }
     

5. Form Request Logic:

   • Add custom authorization or logic in the handle() method of the FormRequest:

     public function handle() {
         if (!$this->user()->can('manage', $this->route('model'))) {
             abort(403);
         }
         return parent::handle();
     }
     

6. Migration Extensions:

   • Extend the generated migration by adding custom columns or indexes after generation:

     Schema::table('departments', function (Blueprint $table) {
         $table->index('name');
     });
     

Configuration Quirks

1. Default Type:

   • The package defaults to --type=api. Always specify --type=web for Blade-based CRUDs to avoid confusion.

2. Field Syntax:

   • Use pipes (|) to separate rules (e.g., name:string|max:255|min:3) and semicolons (;) to separate fields.
   • Example: --fields="name:string|max:255;email:string|email|unique:users".

3. Exclude Flag:

   • The --exclude flag accepts comma-separated values (e.g., --exclude=model,migration). Use .. to exclude all remaining components (e.g., --exclude=model,..).

4. Foreign Key Constraints:

   • Ensure the constrained table’s primary key is named id or specify the key explicitly (e.g., `