Toolkit Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require splash/toolkit
   

   Add the service provider to config/app.php under providers:

   Splash\Toolkit\ToolkitServiceProvider::class,
   

2. First Use Case: Module Scaffolding Generate a basic module structure using Artisan:

   php artisan splash:module MyModule
   

   This creates:

   • app/Modules/MyModule/ (with Module.php, Providers/ModuleServiceProvider.php, etc.)
   • Database migrations (if configured in module.json)

3. Key Entry Points

   • Module Registration: Override register() in ModuleServiceProvider.
   • Bootstrapping: Use boot() for late binding (e.g., view composers, middleware).
   • Configuration: Publish assets with:

     php artisan vendor:publish --provider="Splash\Toolkit\ToolkitServiceProvider" --tag="config"
     

Implementation Patterns

Core Workflows

1. Module Development

• Structure:

  app/Modules/MyModule/
  ├── Config/          # Module-specific config
  ├── Database/        # Migrations, Seeders
  ├── Http/            # Controllers, Middleware, Routes
  ├── Resources/       # Views, Lang, Assets
  ├── Providers/       # Service Providers
  └── module.json      # Metadata (name, version, dependencies)
  

• Dynamic Routes: Use Route::module() in ModuleServiceProvider::boot():

  Route::module('MyModule')->group(function () {
      Route::get('/dashboard', 'DashboardController@index');
  });
  

2. Dependency Management

• Declare Dependencies in module.json:

  {
    "name": "MyModule",
    "dependencies": {
      "splash/auth": "^2.0",
      "splash/ui": "^1.0"
    }
  }
  

• Resolve Dependencies via Toolkit::module():

  $authModule = Toolkit::module('auth');
  

3. Service Binding

• Bind Module Services in ModuleServiceProvider:

  $this->app->bind('MyModule\Contracts\MyService', function ($app) {
      return new MyService($app->make('AnotherService'));
  });
  

• Access Services via Toolkit::make():

  $service = Toolkit::make('MyModule\Contracts\MyService');
  

4. Asset Management

• Publish Assets:

  php artisan splash:publish MyModule --assets
  

• Load Assets in Blade:

  {{ splash_asset('MyModule::css/style.css') }}
  {{ splash_script('MyModule::js/app.js') }}
  

5. Database Migrations

• Run Migrations:

  php artisan splash:migrate MyModule
  

• Rollback:

  php artisan splash:migrate:rollback MyModule
  

6. Event Handling

• Listen to Module Events:

  Toolkit::module('MyModule')->listen('event.name', function ($payload) {
      // Handle event
  });
  

• Dispatch Events:

  Toolkit::module('MyModule')->dispatch('event.name', ['key' => 'value']);
  

7. Testing

• Module Isolation:

  $module = Toolkit::module('MyModule');
  $module->setEnvironment('testing'); // Mock services, DB, etc.
  

Integration Tips

Laravel Ecosystem

• Laravel Mix/Vite: Integrate with splash_asset() by extending Mix:

  mix.setPublicPath('public/modules/MyModule');
  

• Laravel Echo/Pusher: Use Toolkit::module('broadcasting') for event broadcasting.

Third-Party Packages

• Splash Auth: Extend user models via Toolkit::module('auth')->extendUserModel().
• Splash UI: Customize components by overriding Resources/views/components.

CLI Automation

• Custom Commands: Extend ToolkitCommand for module-specific tasks:

  class MyModuleCommand extends ToolkitCommand
  {
      protected $signature = 'splash:my-module {action}';
      protected $description = 'MyModule CLI tool';
  
      public function handle()
      {
          $this->module = Toolkit::module('MyModule');
          // Logic here
      }
  }
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies

   • Issue: Modules A and B depend on each other.
   • Fix: Use lazy loading with Toolkit::module()->whenLoaded() or restructure dependencies.

2. Asset Versioning

   • Issue: Cached assets break after updates.
   • Fix: Enable versioning in module.json:

     "assets": {
       "versioning": true
     }
     

3. Service Provider Order

   • Issue: ModuleServiceProvider boots too early/late.
   • Fix: Use Toolkit::module()->deferBoot() to delay bootstrapping.

4. Database Conflicts

   • Issue: Migration conflicts between modules.
   • Fix: Prefix tables in module.json:

     "database": {
       "prefix": "my_module_"
     }
     

5. Route Caching

   • Issue: Routes not reloaded after changes.
   • Fix: Clear route cache:

     php artisan route:clear
     

   • Or disable caching in module.json:

     "routes": {
       "cache": false
     }
     

Debugging

1. Module Loading Issues

   • Check storage/logs/laravel.log for ModuleNotFoundException.
   • Verify module.json is valid JSON and exists in the module root.

2. Service Binding Failures

   • Use Toolkit::module()->getBindings() to inspect bindings.
   • Debug with:

     dd(Toolkit::module('MyModule')->getService('MyService'));
     

3. Asset Loading Failures

   • Verify paths in module.json:

     "assets": {
       "paths": {
         "css": "Resources/assets/css",
         "js": "Resources/assets/js"
       }
     }
     

   • Check published assets:

     php artisan splash:publish MyModule --assets --force
     

4. Event Dispatching

   • Listen for all events in development:

     Toolkit::module('MyModule')->listen('*', function ($event) {
         Log::debug("Event {$event->name} fired", $event->payload);
     });
     

Configuration Quirks

1. Environment-Specific Config

   • Override config per environment in config/splash/modules.php:

     'MyModule' => [
         'debug' => env('APP_DEBUG', false),
         'cache' => env('MY_MODULE_CACHE', 'file'),
     ],
     

2. Dynamic Module Paths

   • Change module base path in config/splash.php:

     'modules_path' => app_path('CustomModules'),
     

3. Lazy Loading

   • Enable for large modules in module.json:

     "lazy_load": true
     

   • Forces Toolkit::module() to load only when first accessed.

Extension Points

1. Custom Module Types

   • Extend Splash\Toolkit\Contracts\Module for non-standard modules (e.g., CLI tools).

2. Hooks System

   • Implement Splash\Toolkit\Contracts\Hookable for module lifecycle hooks:

     public function onInstall()
     {
         // Post-install logic
     }
     

3. Plugin Architecture

   • Use Toolkit::module()->extend() to add functionality:

     Toolkit::module('auth')->extend('user', function ($user) {
         return new ExtendedUser($user);
     });
     

4. Testing Utilities

   • Mock modules in tests:

     $module = Mockery::mock('overload:Splash\Toolkit\Module');
     Toolkit::shouldReceive('module')->andReturn($module);
     

5. API Integration

   • Expose module endpoints via Toolkit::module()->api():

     Toolkit::module('MyModule')->api()->get('/data', function () {
         return ['key' => 'value'];
     });