Tawa Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require zhyu/tawa
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Zhyu\Tawa\TawaServiceProvider" --tag="tawa-assets"
   php artisan vendor:publish --provider="Zhyu\Tawa\TawaServiceProvider" --tag="tawa-config"
   

2. Basic Usage

   • Register the TawaServiceProvider in config/app.php under providers (if not auto-discovered).
   • Run migrations:

     php artisan migrate
     

   • Access the admin panel at /admin (default route).

3. First Use Case

   • Create a model (e.g., Post) and define its CRUD operations via the admin panel.
   • Use the built-in Livewire components to manage permissions, menus, and user roles.

Implementation Patterns

Core Workflows

1. Model Management

   • Define models in app/Models/ and ensure they extend Illuminate\Database\Eloquent\Model.
   • Use the admin panel to configure CRUD operations for each model via the UI (no manual controller generation needed).

2. Livewire Integration

   • Extend existing Livewire components (e.g., Tawa\Components\AdminLayout) for custom admin logic:

     namespace App\Http\Livewire\Admin;
     
     use Tawa\Components\AdminLayout;
     
     class CustomComponent extends AdminLayout
     {
         public function mount()
         {
             $this->title = "Custom Admin Page";
         }
     }
     

   • Register custom Livewire components in resources/views/admin/layouts/app.blade.php.

3. Alpine.js Enhancements

   • Use Alpine.js for dynamic UI interactions (e.g., toggling filters, real-time updates) in admin views.
   • Example:

     <div x-data="{ open: false }">
         <button @click="open = !open">Toggle</button>
         <div x-show="open">Content</div>
     </div>
     

4. Permission System

   • Assign roles/permissions via the admin panel (/admin/roles and /admin/permissions).
   • Protect routes using middleware:

     Route::middleware(['auth', 'can:access-admin'])->group(function () {
         Route::get('/admin', [AdminController::class, 'index']);
     });
     

5. Menu Configuration

   • Define admin menus in the config (config/tawa.php):

     'menus' => [
         [
             'name' => 'Posts',
             'route' => 'admin.posts.index',
             'icon' => 'fas fa-file-alt',
         ],
     ],
     

Integration Tips

• Custom Views: Override default views by publishing them first (php artisan vendor:publish --tag="tawa-views") and modifying resources/views/vendor/tawa/.
• API Endpoints: Use Laravel’s API resources to extend functionality (e.g., /api/admin/posts).
• Event Listeners: Listen to model events (e.g., created, deleted) for custom logic:

  public function boot()
  {
      \App\Models\Post::created(function ($post) {
          // Custom logic on post creation
      });
  }
  

Gotchas and Tips

Pitfalls

1. Livewire Component Conflicts

   • Avoid naming custom Livewire components the same as those in zhyu/tawa (e.g., AdminLayout). Prefix with your namespace (e.g., App\Livewire\Admin\CustomLayout).

2. Alpine.js Scope Issues

   • Ensure Alpine.js directives are scoped correctly to avoid conflicts with other Alpine instances on the page. Use x-data with unique IDs or namespaces:

     <div x-data="{ open: false }" x-init="$wire.init()">
     

3. Permission Caching

   • Clear cached permissions after role/permission updates:

     php artisan cache:clear
     php artisan view:clear
     

4. Route Caching

   • If using route caching (php artisan route:cache), ensure admin routes are not cached or update them manually after changes:

     php artisan route:clear
     

5. Model Observers

   • If using model observers, ensure they are registered in AppServiceProvider after the package’s observers to avoid conflicts:

     public function boot()
     {
         \App\Models\Post::observe(\App\Observers\PostObserver::class);
     }
     

Debugging Tips

• Livewire Debugging: Use php artisan livewire:discover to regenerate Livewire components if issues arise.
• Alpine.js Debugging: Check browser console for Alpine.js errors. Use x-init to log data:

  <div x-data x-init="console.log('Data:', $data)">
  

• Middleware Debugging: Verify middleware is registered in app/Http/Kernel.php:

  protected $routeMiddleware = [
      'can' => \Zhyu\Tawa\Http\Middleware\CheckPermission::class,
  ];
  

Extension Points

1. Custom Admin Panels

   • Create a new admin panel by extending Tawa\Components\AdminPanel and registering it in config/tawa.php:

     'panels' => [
         'custom' => \App\Components\CustomAdminPanel::class,
     ],
     

2. Dynamic Menus

   • Fetch menus dynamically via a service provider:

     public function boot()
     {
         \Zhyu\Tawa\Facades\Tawa::extendMenus(function ($menus) {
             $menus[] = ['name' => 'Dynamic Menu', 'route' => route('dynamic.route')];
             return $menus;
         });
     }
     

3. Custom Fields

   • Extend the field types in app/Providers/TawaServiceProvider.php:

     public function boot()
     {
         \Zhyu\Tawa\Fields\Field::macro('customField', function () {
             return new \App\Fields\CustomField();
         });
     }
     

4. Localization

   • Override translations by publishing them first (php artisan vendor:publish --tag="tawa-translations") and modifying resources/lang/vendor/tawa/.

5. Asset Overrides

   • Override CSS/JS by publishing assets and modifying:
     • public/vendor/tawa/css/admin.css
     • public/vendor/tawa/js/admin.js