Laraman Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require christhompsontldr/laraman
   

   Publish the config file:

   php artisan vendor:publish --provider="ChrisThompsonTLDR\Laraman\LaramanServiceProvider" --tag="config"
   

2. First Use Case: Generate a CRUD controller for an existing model (e.g., User):

   php artisan laraman:make User
   

   This creates:

   • A controller (app/Http/Controllers/UserController.php)
   • Routes (auto-registered in routes/web.php)
   • Basic views (if using Blade)

3. Where to Look First:

   • Config: config/laraman.php (adjust controller naming, view paths, or route limits).
   • Commands: app/Console/Commands/LaramanMakeController.php (customize scaffolding).
   • Service Provider: ChrisThompsonTLDR\Laraman\LaramanServiceProvider (hook into route registration).

Implementation Patterns

Core Workflow

1. Scaffolding: Use the laraman:make command to generate controllers for models:

   php artisan laraman:make Post --resource --api
   

   • --resource: Generates RESTful routes (index, store, show, etc.).
   • --api: Skips Blade views, assumes API responses (JSON).

2. Customization:

   • Override Templates: Publish views with:

     php artisan vendor:publish --tag="laraman-views"
     

     Then modify resources/views/vendor/laraman/ templates.
   • Extend Controllers: Override methods in generated controllers (e.g., store()) or use traits.

3. Integration with Existing Code:

   • Routes: Manually add routes if needed (Laraman registers them via the service provider).

     Route::resource('custom-route', \App\Http\Controllers\CustomController::class);
     

   • Forms: Use Laravel Collective HTML ({!! Form::open() !!}) in views (required dependency).

4. API-Only Workflows: Disable views in config:

   'views' => [
       'enabled' => false,
   ],
   

   Then generate API controllers:

   php artisan laraman:make Product --api
   

5. Batch Operations: Use the laraman:make command in package.json scripts or CI/CD pipelines to scaffold multiple controllers:

   php artisan laraman:make User Post Category
   

Gotchas and Tips

Pitfalls

1. Performance Issues (v2.0.0):

   • Avoid using Laraman for high-traffic routes (e.g., /users). The package dynamically builds routes, which can slow down route caching.
   • Workaround: Use manual routes for critical paths or disable Laraman’s auto-registration in LaramanServiceProvider.

2. View Overrides:

   • If views aren’t updating after changes, clear the view cache:

     php artisan view:clear
     

   • Ensure resources/views/vendor/laraman/ exists and permissions are correct.

3. Route Conflicts:

   • Laraman auto-registers routes under /{model} (e.g., /users). Conflict with existing routes? Use --prefix in config:

     'route_prefix' => 'admin',
     

     Now routes appear under /admin/users.

4. Dependency on Laravel Collective:

   • If you remove laravelcollective/html, Laraman’s views will break. Either:
     • Keep the package installed, or
     • Manually replace {!! Form::... !!} with Blade syntax in templates.

5. Controller Naming:

   • By default, controllers are named {Model}Controller (e.g., UserController). To customize:

     'controller_name' => 'Admin{Model}Controller',
     

     Now generates AdminUserController.

Debugging Tips

1. Check Route Registration: Dump registered routes to debug conflicts:

   Route::get('/debug-routes', function() {
       dd(Route::getRoutes()->getByName());
   });
   

2. Log Controller Generation: Enable debug mode in config/laraman.php:

   'debug' => true,
   

   Logs will appear in storage/logs/laraman.log.

3. Override Route Middleware: Add middleware to all Laraman routes in LaramanServiceProvider:

   public function boot()
   {
       Route::group(['middleware' => ['auth']], function() {
           Route::resource('{model}', \App\Http\Controllers\{Model}Controller::class);
       });
   }
   

Extension Points

1. Custom Fields: Extend the laraman:make command to include additional fields (e.g., soft deletes):

   // app/Console/Commands/LaramanMakeController.php
   protected function getStub()
   {
       if ($this->option('soft-deletes')) {
           return __DIR__.'/stubs/controller.soft-deletes.stub';
       }
       return __DIR__.'/stubs/controller.stub';
   }
   

   Then use:

   php artisan laraman:make User --soft-deletes
   

2. Dynamic Views: Use Blade directives to inject dynamic content:

   // In a Laraman view (e.g., resources/views/vendor/laraman/index.blade.php)
   @laramanField('custom_field', 'This is dynamic!')
   

   Register the directive in a service provider:

   Blade::directive('laramanField', function($expression) {
       return "<?php echo \$laramanField = {$expression}; ?>";
   });
   

3. API Response Customization: Override the respondWith() method in generated controllers:

   // app/Http/Controllers/UserController.php
   protected function respondWith($resource)
   {
       return response()->json([
           'data' => $resource,
           'custom_meta' => 'value',
       ]);
   }
   

4. Hook into Model Events: Use Laraman’s controller stubs to add model observers or events:

   // In the generated controller's constructor
   public function __construct()
   {
       $this->model->observe(\App\Observers\UserObserver::class);
   }