Getting Started

Minimal Steps

Install the package:
```
composer require supervisorphp/configuration
```
Note: If using PHP 8.x, consider forking or patching for compatibility.

Basic configuration generation:

use Supervisor\Configuration\{Configuration, Section\Program};
use Supervisor\Configuration\Writer\IniFileWriter;

$config = new Configuration();
$config->addSection(new Program('laravel-queue-worker', [
    'command' => 'php artisan queue:work --sleep=3 --tries=3',
    'autostart' => true,
    'autorestart' => true,
    'user' => 'www-data',
    'numprocs' => 4,
    'stderr_logfile' => storage_path('logs/worker.err.log'),
    'stdout_logfile' => storage_path('logs/worker.out.log'),
]));

$writer = new IniFileWriter('/etc/supervisor/conf.d/laravel-worker.conf');
$writer->write($config);

Reload Supervisor (manually or via script):

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-queue-worker

First Use Case

Dynamic Laravel Queue Worker Configuration: Use this package to generate Supervisor configs for queue workers during deployment or runtime. For example, in a Laravel ServiceProvider or Artisan command:

// app/Providers/SupervisorServiceProvider.php
public function boot()
{
    $this->generateQueueWorkerConfig();
}

protected function generateQueueWorkerConfig()
{
    $config = new Configuration();
    $config->addSection(new Program('laravel-queue-worker', [
        'command' => 'php ' . base_path('artisan') . ' queue:work --sleep=3 --tries=3',
        'autostart' => true,
        'autorestart' => true,
        'user' => env('SUPERVISOR_USER', 'www-data'),
        'numprocs' => env('QUEUE_WORKER_COUNT', 4),
        'stderr_logfile' => storage_path('logs/worker.err.log'),
        'stdout_logfile' => storage_path('logs/worker.out.log'),
    ]));

    $writer = new IniFileWriter(config_path('supervisor/queue-worker.conf'));
    $writer->write($config);
}

Implementation Patterns

Usage Patterns

Configuration as Code:

Store Supervisor configs in PHP classes (e.g., config/supervisor.php) and generate .conf files during deployment.

Example:

// config/supervisor.php
return [
    'programs' => [
        'laravel-scheduler' => [
            'command' => 'php artisan schedule:run',
            'autostart' => true,
            'autorestart' => true,
        ],
        'laravel-queue-worker' => [
            'command' => 'php artisan queue:work --sleep=3 --tries=3',
            'numprocs' => 4,
        ],
    ],
];

// Generate configs from config
$configs = config('supervisor.programs');
foreach ($configs as $name => $options) {
    $config = new Configuration();
    $config->addSection(new Program($name, $options));
    $writer = new IniFileWriter("/etc/supervisor/conf.d/{$name}.conf");
    $writer->write($config);
}

Environment-Specific Configs:

Use Laravel’s config() helper to load environment-specific settings:

$numWorkers = config('supervisor.queue_workers.' . env('APP_ENV'));
$config->addSection(new Program('queue-worker', [
    'numprocs' => $numWorkers,
    // ...
]));

Dynamic Configs from Database:

Fetch process definitions from a database and generate configs on demand:

$processes = DB::table('supervisor_processes')->get();
foreach ($processes as $process) {
    $config = new Configuration();
    $config->addSection(new Program($process->name, [
        'command' => $process->command,
        'user' => $process->user,
        'numprocs' => $process->numprocs,
    ]));
    $writer->write($config);
}

Integration with Laravel Migrations:

Use migrations to manage Supervisor configs alongside database schema:

// database/migrations/xxxx_create_supervisor_configs.php
public function up()
{
    $config = new Configuration();
    $config->addSection(new Program('laravel-queue-worker', [
        'command' => 'php artisan queue:work',
        'numprocs' => 2,
    ]));
    $writer = new IniFileWriter('/etc/supervisor/conf.d/laravel-worker.conf');
    $writer->write($config);

    // Reload Supervisor (e.g., via SSH or Artisan command)
    Artisan::call('supervisor:reload');
}

Workflows

Deployment Workflow:
- Pre-deploy: Generate Supervisor configs in your CI/CD pipeline (e.g., GitHub Actions, GitLab CI).
- Post-deploy: Reload Supervisor to pick up new configs:
```
sudo supervisorctl reread
sudo supervisorctl update
```

Development Workflow:

Use IniStringLoader to parse existing configs for local development:

$loader = new IniStringLoader(file_get_contents('/etc/supervisor/supervisord.conf'));
$config = $loader->load();
// Modify config in PHP and regenerate

Runtime Configuration:

Dynamically update configs during runtime (e.g., scaling workers based on load):

// app/Http/Controllers/WorkerController.php
public function scaleWorkers(int $count)
{
    $config = (new IniFileLoader('/etc/supervisor/conf.d/laravel-worker.conf'))->load();
    $program = $config->getSection('laravel-queue-worker');
    $program->setProperty('numprocs', $count);

    $writer = new IniFileWriter('/etc/supervisor/conf.d/laravel-worker.conf');
    $writer->write($config);

    Artisan::call('supervisor:reload');
}

Integration Tips

Laravel Service Provider:

Bind the package’s interfaces to Laravel’s container for easier dependency injection:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->bind(
        \Supervisor\Configuration\Loader\LoaderInterface::class,
        \Supervisor\Configuration\Loader\IniFileLoader::class
    );
    $this->app->bind(
        \Supervisor\Configuration\Writer\WriterInterface::class,
        \Supervisor\Configuration\Writer\IniFileWriter::class
    );
}

Artisan Commands:

Create custom commands for common tasks (e.g., generating configs, reloading Supervisor):

// app/Console/Commands/GenerateSupervisorConfig.php
class GenerateSupervisorConfig extends Command
{
    protected $signature = 'supervisor:generate {--path=}';
    protected $description = 'Generate Supervisor configuration files';

    public function handle()
    {
        $path = $this->option('path') ?? config_path('supervisor');
        $configs = config('supervisor.programs');
        foreach ($configs as $name => $options) {
            $config = new Configuration();
            $config->addSection(new Program($name, $options));
            $writer = new IniFileWriter("{$path}/{$name}.conf");
            $writer->write($config);
        }
        $this->info('Supervisor configs generated!');
    }
}

Flysystem Integration:

Use FlysystemLoader/FlysystemWriter to store configs in cloud storage (e.g., S3):

use League\Flysystem\Filesystem;
use League\Flysystem\Adapter\Local;

$adapter = new Local(storage_path('supervisor'));
$filesystem = new Filesystem($adapter);

$loader = new \Supervisor\Configuration\Loader\FlysystemLoader($filesystem);
$writer = new \Supervisor\Configuration\Writer\FlysystemWriter($filesystem);

Validation:

Validate Supervisor configs against the official schema before writing:

use Indigo\Ini\Parser;
use Indigo\Ini\Exception\ParseException;

try {
    $parser = new Parser();
    $parser->parse($config->toArray());
    $writer->write($config);
} catch (ParseException $e) {
    throw new \RuntimeException('Invalid Supervisor config: ' . $e->getMessage());
}

Configuration Laravel Package