Larazoul Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tayeb-ali/larazoul
   php artisan vendor:publish --provider="TayebAli\Larazoul\LarazoulServiceProvider" --tag="config"
   php artisan migrate
   

   • Publishes default config (config/larazoul.php) and runs migrations for core tables (admin_users, roles, permissions).

2. First Use Case: Admin Panel

   • Register the admin route in routes/web.php:

     Route::group(['prefix' => 'admin', 'middleware' => ['web', 'auth:admin']], function () {
         \TayebAli\Larazoul\Facades\Larazoul::routes();
     });
     

   • Run php artisan larazoul:install to seed default admin credentials (email: admin@example.com, password: password).

3. Key Files to Review

   • Config: config/larazoul.php (adjust guard, middleware, or default settings).
   • Middleware: app/Http/Middleware/AuthenticateAdmin.php (customize if needed).
   • Service Provider: app/Providers/LarazoulServiceProvider.php (extend or override bindings).

Implementation Patterns

1. CRUD Generation

• Scaffold a Model/Controller

  php artisan larazoul:make:crud Post --fields="title:string,content:text,is_published:boolean"
  

  • Generates:
    • Model (app/Models/Post.php) with fillable fields.
    • Controller (app/Http/Controllers/Admin/PostController.php) with CRUD methods.
    • Migration (database/migrations/..._create_posts_table.php).
    • Admin views (resources/views/admin/posts/).

• Customize Fields Edit the generated fields array in the controller’s rules() method or use Laravel’s form helpers:

  public function fields()
  {
      return [
          'title' => ['type' => 'text', 'label' => 'Post Title'],
          'content' => ['type' => 'textarea', 'rows' => 5],
          'is_published' => ['type' => 'checkbox', 'label' => 'Published?'],
      ];
  }
  

2. Role-Based Permissions

• Assign Permissions to Roles Use the built-in admin panel (/admin/roles) to:

  1. Create a role (e.g., Editor).
  2. Attach permissions (e.g., create-post, edit-post).

• Gate Checks in Code

  if (auth()->user()->can('edit-post')) {
      // Allow edit functionality
  }
  

  Or use middleware:

  Route::group(['middleware' => 'can:edit-post'], function () {
      // Protected routes
  });
  

3. Extending the Admin Panel

• Add Custom Views Override default views by publishing them first:

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

  Then modify resources/views/vendor/larazoul/....

• Customize Layout Extend the base layout (resources/views/vendor/larazoul/layouts/app.blade.php) or override the admin template:

  // In LarazoulServiceProvider::boot()
  $this->loadViewsFrom(__DIR__.'/../resources/views/custom/admin', 'larazoul');
  

4. API Integration

• Expose CRUD via API Use Laravel’s API resources + Larazoul’s controllers:

  // routes/api.php
  Route::apiResource('posts', \App\Http\Controllers\Admin\PostController::class)
      ->middleware('auth:api');
  

  • Ensure the controller extends TayebAli\Larazoul\Http\Controllers\CrudController.

• Filtering/Sorting Leverage Laravel’s query builder or use packages like spatie/laravel-query-builder for dynamic API requests.

Gotchas and Tips

Pitfalls

1. Middleware Conflicts

   • If auth:admin fails, verify:
     • The admin guard is configured in config/auth.php.
     • The AuthenticateAdmin middleware is registered in app/Http/Kernel.php.
   • Fix: Re-run php artisan larazoul:install or manually create the admin user table.

2. Permission Caching

   • Permissions are cached by default. Clear cache after manual role/permission changes:

     php artisan cache:clear
     php artisan config:clear
     

3. View Overrides

   • Custom views must match the original structure (e.g., index.blade.php, create.blade.php). Partial overrides (e.g., only edit.blade.php) may break layouts.

4. Migration Conflicts

   • If you modify the admin_users table, reset migrations carefully:

     php artisan migrate:fresh --env=testing  # Test first
     

Debugging Tips

• Check Logs Enable debug mode (APP_DEBUG=true) and inspect storage/logs/laravel.log for permission or route errors.

• DD() in Controllers Debug CRUD logic by adding dd($request->all()) in controller methods (e.g., store()).

• Artisan Commands

  • List available commands:

    php artisan list | grep larazoul
    

  • Rebuild admin assets:

    php artisan larazoul:assets
    

Extension Points

1. Custom Auth Logic Override the AdminUser model (app/Models/AdminUser.php) or extend the AuthenticatesAdmins trait.

2. Add Notifications Extend the AdminUser model to include notify() methods or use Laravel Notifications:

   // app/Models/AdminUser.php
   use Illuminate\Notifications\Notifiable;
   class AdminUser extends Authenticatable {
       use Notifiable;
       // ...
   }
   

3. Multi-Tenant Support

   • Use spatie/laravel-multitenancy alongside Larazoul.
   • Override the LarazoulServiceProvider to scope queries:

     public function boot()
     {
         \TayebAli\Larazoul\Models\Post::addGlobalScope(new TenantScope());
     }
     

4. Localization

   • Publish translation files:

     php artisan vendor:publish --tag="larazoul-lang"
     

   • Extend resources/lang/vendor/larazoul/ for custom translations.

Performance Quirks

• Eager Load Relationships Manually eager-load in controllers to avoid N+1 queries:

  public function index()
  {
      $posts = Post::with('author')->get();
      // ...
  }
  

• Disable Debug Bar If using barryvdh/laravel-debugbar, exclude Larazoul routes to reduce overhead:

  // app/Providers/DebugbarServiceProvider.php
  $this->excludeRoutes([
      'admin/*',
  ]);