Ui Process Bundle Laravel Package

Getting Started

1. Prerequisites: Ensure your project meets the updated requirements:

   • PHP 8.1+ (previously likely lower; now explicitly enforced).
   • Symfony 7.3+ (aligns with Laravel 10.x+ compatibility).
   • Install via Composer:

     composer require cleverage/ui-process-bundle
     

2. First Use Case: Create a UI process with a user via CLI:

   php artisan cleverage:ui-process:user-create --username=testuser --password=securepass
   

   (Note: --username/--password args are now supported; see #57.)

3. Key Files:

   • config/cleverage_ui_process.php (check for Symfony 7.3+ config structure).
   • vendor/cleverage/ui-process-bundle/ (source for extension points).

Implementation Patterns

Core Workflows

1. Process Definition:

   • Define processes in config/cleverage_ui_process.php under processes.
   • Use Symfony 7.3’s YAML/PHP config syntax (e.g., steps: array with command: keys).

   'processes' => [
       'example' => [
           'steps' => [
               ['command' => 'php artisan queue:work'],
               ['command' => 'php artisan cache:clear'],
           ],
       ],
   ],
   

2. CLI Integration:

   • Use the cleverage:ui-process:run command to execute processes:

     php artisan cleverage:ui-process:run example
     

   • Pass dynamic args via --option=value (e.g., --env=production).

3. User Management:

   • Create users programmatically or via CLI (now with explicit --username/--password):

     $this->call('cleverage:ui-process:user-create', [
         '--username' => 'admin',
         '--password' => 'P@ssw0rd',
     ]);
     

Integration Tips

• Laravel Events: Trigger processes on events (e.g., ProcessStarted) via Event::dispatch().
• Queue Workers: Offload long-running processes to queues by wrapping commands in ProcessBundle's Process class.
• Symfony Components: Leverage Symfony’s Process and Console components for custom logic (e.g., logging, error handling).

Gotchas and Tips

Breaking Changes

1. PHP 8.1+ Requirement:

   • Impact: Code using array() or foreach with non-object iterables may fail.
   • Fix: Update to PHP 8.1+ and use typed properties/arrays (e.g., array_map() for strict types).
   • Debug: Check for TypeError in logs when running commands.

2. Symfony 7.3+:

   • Impact: Config files may need YAML/PHP syntax updates (e.g., !tagged services → tags: []).
   • Fix: Run composer dump-autoload and validate config structure.

Common Pitfalls

• CLI Argument Parsing:

  • Forgetting to pass --username/--password to user-create will throw MissingArgumentException.
  • Tip: Use --help for command-specific args:

    php artisan cleverage:ui-process:user-create --help
    

• Process Isolation:

  • Commands run in subprocesses; avoid shared memory (e.g., Laravel’s cache()) unless explicitly synchronized.
  • Tip: Use ProcessBundle's Process::mustRun() for blocking calls.

Extension Points

1. Custom Commands:

   • Extend the bundle by creating a new command:

     php artisan make:command CustomProcessCommand
     

   • Inject Cleverage\UiProcessBundle\Command\ProcessRunner to reuse logic.

2. Event Listeners:

   • Listen for ProcessStarted/ProcessFailed events to add pre/post hooks:

     public function handle(ProcessStarted $event) {
         Log::info('Process ID: '.$event->getProcess()->getId());
     }
     

3. Configuration Overrides:

   • Publish config with:

     php artisan vendor:publish --tag=cleverage-ui-process-config
     

   • Override processes array in config/cleverage_ui_process.php.

Debugging Tips

• Verbose Output: Add -vvv to CLI commands for Symfony debug logs.
• Process Logs: Check storage/logs/laravel.log for subprocess errors (e.g., command failures).
• PHP 8.4 Features: Use str_contains() or array_is_list() if upgrading to PHP 8.4.