Artisan Ui Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require creative-syntax/artisan-ui
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="CreativeSyntax\ArtisanUI\ArtisanUIServiceProvider" --tag="artisan-ui-views"
   

2. First Use Case Create a simple Artisan command with a UI:

   php artisan make:command TestCommand
   

   Modify the generated command (app/Console/Commands/TestCommand.php) to include UI support:

   use CreativeSyntax\ArtisanUI\Traits\HasArtisanUI;
   
   class TestCommand extends Command
   {
       use HasArtisanUI;
   
       protected $signature = 'test:ui';
       protected $description = 'A test command with UI';
   
       public function handle()
       {
           $this->ui()->info('This is a UI-powered command!');
       }
   }
   

   Run the command:

   php artisan test:ui
   

   Access the UI at /artisan-ui (default route).

Key First Steps

• Register the UI route in routes/web.php (if not auto-loaded):

  Route::get('/artisan-ui', [\CreativeSyntax\ArtisanUI\ArtisanUIController::class, 'index']);
  

• Configure the UI (optional) via config/artisan-ui.php:

  'commands' => [
      'test:ui' => [
          'name' => 'Test Command',
          'description' => 'A test command with UI',
      ],
  ],
  

Implementation Patterns

Workflow: Command Development with UI

1. Extend Commands with UI Use the HasArtisanUI trait to enable UI integration:

   use CreativeSyntax\ArtisanUI\Traits\HasArtisanUI;
   
   class MyCommand extends Command
   {
       use HasArtisanUI;
   
       // Command logic...
   }
   

   The trait adds $ui property and ui() helper method.

2. UI Interaction Methods Leverage UI-specific methods in your command:

   public function handle()
   {
       $this->ui()->success('Operation completed!');
       $this->ui()->warning('This is a warning message.');
       $this->ui()->error('Something went wrong.');
       $this->ui()->input('Enter value:', $default = 'default');
   }
   

3. Dynamic UI Forms For interactive commands, use the ui()->form() method:

   public function handle()
   {
       $data = $this->ui()->form([
           'name' => 'text',
           'age' => 'number',
       ]);
   
       $this->info('Received: ' . json_encode($data));
   }
   

4. Integration with Laravel Blade Customize the UI view by publishing assets and extending:

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

   Override resources/views/vendor/artisan-ui/index.blade.php.

Common Patterns

• Command Registration Automatically discover commands via HasArtisanUI trait. Manually register in config/artisan-ui.php if needed:

  'commands' => [
      'my:custom-command' => [
          'name' => 'Custom Command',
          'description' => 'Does something amazing.',
      ],
  ],
  

• UI State Management Pass data to the UI via ui()->setData():

  $this->ui()->setData(['key' => 'value']);
  

  Access in Blade:

  @if(isset($data['key']))
      {{ $data['key'] }}
  @endif
  

• Conditional UI Logic Use ui()->shouldRender() to conditionally show/hide UI elements:

  if ($this->ui()->shouldRender()) {
      $this->ui()->info('UI is active!');
  }
  

Gotchas and Tips

Pitfalls

1. Route Conflict

   • The default /artisan-ui route may conflict with existing routes. Rename in config/artisan-ui.php:

     'route' => 'admin/artisan',
     

2. Trait Overhead

   • Avoid mixing HasArtisanUI with other traits that modify $signature or $description dynamically, as it may cause UI metadata conflicts.

3. CSRF Protection

   • The UI form submissions may trigger CSRF errors if not handled. Ensure middleware is configured in app/Http/Kernel.php:

     'web' => [
         \App\Http\Middleware\VerifyCsrfToken::class,
         // ...
     ],
     

4. Session Dependencies

   • The UI relies on sessions. If using API-only Laravel, enable sessions or handle stateless UI requirements manually.

Debugging Tips

1. Check UI Data Flow

   • Use dd($this->ui()->getData()) to inspect passed data in commands.

2. Clear Cached Views

   • After publishing views, clear cached Blade views:

     php artisan view:clear
     

3. Log UI Events

   • Enable debug mode in config/artisan-ui.php:

     'debug' => env('APP_DEBUG', false),
     

   • Check logs for UI-related errors in storage/logs/laravel.log.

Extension Points

1. Custom UI Components

   • Extend the UI by creating custom Blade components in resources/views/vendor/artisan-ui/components/.

2. Command-Specific Views

   • Override UI views per command by publishing assets and creating command-specific templates:

     php artisan vendor:publish --tag="artisan-ui-views" --force
     

   • Example: resources/views/vendor/artisan-ui/commands/test-ui.blade.php.

3. API Integration

   • Use the package’s ArtisanUI::execute() method to run commands programmatically and fetch UI data:

     $result = ArtisanUI::execute('test:ui');
     $uiData = $result->getUiData();
     

4. Localization

   • Localize UI messages by publishing language files:

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

   • Override in resources/lang/en/artisan-ui.php.