Crudstarter Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require niraj/crudstarter --dev
   php artisan vendor:publish --tag=crudstarter-config
   

   • Publish the config file to customize default settings (e.g., namespace, view paths).

2. Generate a Dashboard (One-Time Setup)

   php artisan gen:dashboard
   

   • Creates a clean admin dashboard layout at /resources/views/dashboard.blade.php.

3. First CRUD Generation

   php artisan gen:crud User --fields="name:string,email:string,password:encrypted:string"
   

   • Generates:
     • Model (app/Models/User.php)
     • Migration (database/migrations/..._create_users_table.php)
     • Controller (app/Http/Controllers/Admin/UserController.php)
     • Views (resources/views/admin/users/...)
     • Routes (routes/web.php and routes/api.php)

4. Access the CRUD Interface

   • Navigate to /admin/users in your browser to interact with the generated CRUD.

Where to Look First

• Official Docs: Start here for detailed usage, customization, and API reference.
• Published Config File: /config/crudstarter.php – Adjust namespaces, view paths, or default behaviors.
• Stub Files: If published (php artisan vendor:publish --tag=crud-stub), customize templates for models, controllers, or views in /stubs/.

First Use Case: Quick CRUD for a Blog Post

php artisan gen:crud Post --fields="title:string,slug:unique:string,content:text,is_published:boolean"

• Outcome:
  • A fully functional CRUD interface for Post with validation, pagination, and search.
  • API endpoints (/api/posts) for headless integrations.
  • Pre-styled dashboard integration.

Implementation Patterns

Core Workflows

1. Model-Driven CRUD Generation

• Pattern: Define fields as fieldName:type (e.g., name:string, price:decimal:8,2).
• Example:

  php artisan gen:crud Product --fields="name:string,price:decimal:8,2,stock:integer,description:text"
  

• Integration Tip: Use --options to customize:

  php artisan gen:crud Product --fields="..." --options="--with-soft-deletes --with-timestamps"
  

2. API-First Development

• Generate API-only CRUD:

  php artisan gen:api Product --fields="name:string,price:decimal:8,2"
  

• Output:

  • API routes (routes/api.php).
  • Controller with store, update, destroy, etc.
  • No dashboard views (lightweight).

• Integration Tip: Extend the generated controller to add custom logic:

  // app/Http/Controllers/API/ProductController.php
  public function store(Request $request) {
      $validated = $request->validate([
          'name' => 'required|string|max:255',
          'price' => 'required|numeric',
          // Custom validation
          'price' => 'min:0',
      ]);
      return parent::store($request);
  }
  

3. Dashboard Customization

• Pattern: Override default views by copying generated files to /resources/views/admin/{model}/.

• Example:

  • Copy /vendor/niraj/crudstarter/src/Resources/views/admin/crud/index.blade.php to /resources/views/admin/products/index.blade.php.
  • Modify to add custom columns or buttons.

• Integration Tip: Use @include('crudstarter::partials._form') to reuse form partials while adding custom fields.

4. Relationship Handling

• Pattern: Define relationships in the --fields argument:

  php artisan gen:crud Order --fields="user:id,items:hasMany,total:decimal:10,2"
  

• Outcome:

  • Automatic foreign key columns (user_id).
  • Nested CRUD for items (if hasMany).
  • Relationship dropdowns in forms.

• Integration Tip: Customize relationship queries in the model:

  public function items() {
      return $this->hasMany(Item::class)->orderBy('created_at', 'desc');
  }
  

5. Validation and Authorization

• Pattern: Leverage Laravel’s built-in validation and gates/policies.
• Example:
  • Add a policy for Product:

    php artisan make:policy ProductPolicy --model=Product
    

  • Attach to the generated controller:

    public function __construct() {
        $this->authorizeResource(Product::class, 'product');
    }
    

  • Customize validation in the controller’s rules() method.

Integration Tips

1. Seeding and Testing

• Generate a seeder for initial data:

  php artisan gen:seeder Product --count=5
  

• Tip: Use --with-faker to populate fake data:

  php artisan gen:seeder Product --count=10 --with-faker
  

2. Multi-Auth Support

• If using spatie/laravel-permission, extend the generated controller:

  use Spatie\Permission\Traits\HasRoles;
  
  class ProductController extends Controller {
      use HasRoles;
      public function index() {
          $this->authorize('viewAny', Product::class);
          // ...
      }
  }
  

3. Localization

• Publish language files:

  php artisan vendor:publish --tag=crudstarter-lang
  

• Customize translations in /resources/lang/{locale}/crudstarter.php.

4. Custom Actions

• Add buttons/actions to the CRUD list:

  // In the controller
  public function getCustomButtons() {
      return [
          'publish' => [
              'label' => 'Publish',
              'class' => 'btn-success',
              'route' => 'admin.products.publish',
              'method' => 'POST',
          ],
      ];
  }
  

• Define the route in routes/web.php:

  Route::post('/admin/products/{product}/publish', [ProductController::class, 'publish'])->name('admin.products.publish');
  

5. Event Listeners

• Listen to model events (e.g., created, updated):

  // app/Listeners/ProductCreatedListener.php
  public function handle($event) {
      // Send notification, log, etc.
  }
  

• Register in EventServiceProvider:

  protected $listen = [
      'niraj\crudstarter\Events\CrudCreated' => [
          ProductCreatedListener::class,
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Field Type Mismatches

• Issue: Generating a field as string but using it as a relationship.
• Fix: Use relationship:model in --fields:

  php artisan gen:crud Order --fields="user:relationship:User"
  

2. Route Conflicts

• Issue: Generated routes clash with existing ones (e.g., /admin/users vs. /users).
• Fix: Customize the route prefix in config/crudstarter.php:

  'route_prefix' => 'backend',
  

• Or override routes in routes/web.php:

  Route::prefix('admin')->group(function () {
      Route::resource('products', ProductController::class);
  });
  

3. View Override Pitfalls

• Issue: Changes to stubs aren’t reflected in generated views.
• Fix: Republish stubs and regenerate CRUD:

  php artisan vendor:publish --tag=crud-stub --force
  php artisan gen:crud Product --force
  

4. Soft Deletes Not Working

• Issue: Soft deletes are enabled in the model but not in the CRUD.
• Fix: Regenerate with --with-soft-deletes:

  php artisan gen:crud Product --fields="..." --options="--with-soft-deletes"
  

• Or manually add the trait to the model:

  use SoftDeletes;
  

5. API Resource Conflicts

• Issue: Generated API resources conflict with existing ones.
• Fix: Use --api-namespace to customize the API namespace:

  php artisan gen:api Product --api-namespace=v1
  

Debugging Tips

1. Log Generation Steps

• Enable debug mode