Wire Sileo Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mrclln/wire-sileo
   

   Publish the config file (if available):

   php artisan vendor:publish --provider="Mrclln\WireSileo\WireSileoServiceProvider"
   

2. Basic Usage The package appears to be a wrapper for interacting with WireGuard via the sileo CLI tool (likely for iOS management). Start by inspecting the WireSileo facade or service container binding:

   use Mrclln\WireSileo\Facades\WireSileo;
   
   // Example: Check WireGuard status (hypothetical method)
   $status = WireSileo::status();
   

3. First Use Case

   • Device Management: If the package supports iOS WireGuard tunnel management, use it to:

     // Enable/disable a tunnel (example)
     WireSileo::enableTunnel('my-tunnel');
     WireSileo::disableTunnel('my-tunnel');
     

   • Configuration: Load/save WireGuard configs:

     $config = WireSileo::getConfig('tunnel-name');
     WireSileo::setConfig('tunnel-name', $newConfig);
     

4. Where to Look First

   • Facade/Service: Check app/WireSileo.php or Mrclln\WireSileo\Facades\WireSileo.
   • Service Provider: Review WireSileoServiceProvider for bindings and boot logic.
   • Documentation: If sparse, inspect the src/ directory for methods like execute(), runCommand(), or parseOutput().

Implementation Patterns

Core Workflows

1. Command Execution The package likely wraps sileo CLI commands. Follow this pattern:

   // Hypothetical: Run a raw sileo command
   $output = WireSileo::run('tunnel list');
   $tunnels = WireSileo::parseTunnels($output);
   

2. Configuration Management

   • Load/Save: Use methods like getConfig()/setConfig() to sync Laravel config with WireGuard.

     $config = WireSileo::getConfig('vpn-tunnel');
     config(['wireguard.tunnels.vpn-tunnel' => $config]);
     

   • Validation: Validate configs before saving (e.g., check for required keys like PrivateKey).

3. Event-Driven Integration

   • Listeners: Trigger Laravel events (e.g., WireGuardTunnelUpdated) when configs change.

     WireSileo::setConfig('tunnel', $data)->then(function () {
         event(new TunnelUpdated($data));
     });
     

   • Webhooks: If the package supports webhooks, use Laravel’s Http client to notify external services.

4. Artisan Commands Create custom Artisan commands to interact with WireGuard:

   php artisan wireguard:status
   php artisan wireguard:enable my-tunnel
   

Integration Tips

• Laravel Config: Store default tunnel configs in config/wireguard.php:

  'tunnels' => [
      'vpn-tunnel' => [
          'PrivateKey' => env('WIREGUARD_PRIVATE_KEY'),
          'Peers' => [...],
      ],
  ],
  

• Environment Variables: Use .env for sensitive data:

  WIREGUARD_SILEO_PATH=/usr/local/bin/sileo
  WIREGUARD_TUNNELS=vpn-tunnel,backup-tunnel
  

• Logging: Wrap commands in Laravel’s Log facade for debugging:

  Log::debug('WireGuard command output:', ['output' => $output]);
  

Gotchas and Tips

Pitfalls

1. CLI Dependency

   • Issue: The package relies on sileo being installed and in $PATH. Fix: Validate the binary exists in WireSileoServiceProvider:

     if (!file_exists('/usr/local/bin/sileo')) {
         throw new \RuntimeException('sileo CLI not found. Install it first.');
     }
     

   • Tip: Use Artisan::call() to check the binary path dynamically.

2. Output Parsing

   • Issue: sileo CLI output may be unstructured (e.g., JSON vs. plaintext). Fix: Implement a parser in WireSileo:

     protected function parseOutput(string $output): array
     {
         return json_decode($output, true) ?: $this->fallbackParse($output);
     }
     

3. Permissions

   • Issue: WireGuard tunnels may require sudo or specific user permissions. Fix: Use Laravel’s Process facade with sudo:

     use Symfony\Component\Process\Process;
     $process = new Process(['sudo', 'sileo', 'tunnel', 'enable', 'tunnel-name']);
     

4. Error Handling

   • Issue: Silent failures if sileo commands exit non-zero. Fix: Throw exceptions or log errors:

     $process = Process::fromShellCommandline('sileo tunnel enable my-tunnel');
     $process->run();
     if (!$process->isSuccessful()) {
         throw new \RuntimeException($process->getErrorOutput());
     }
     

Debugging Tips

1. Verbose Mode Add a --verbose flag to commands:

   public function run(string $command, bool $verbose = false): string
   {
       $args = $verbose ? ['--verbose'] : [];
       return Process::fromShellCommandline("sileo {$command} " . implode(' ', $args))
           ->getOutput();
   }
   

2. Logging Commands Log all executed commands to storage/logs/wireguard.log:

   Log::channel('wireguard')->info('Executing: sileo ' . $command);
   

3. Testing

   • Mock the Process: Use Laravel’s Process mock in tests:

     $mock = Mockery::mock(Process::class);
     $mock->shouldReceive('run')->andReturn(new ProcessResult(0, 'Success', ''));
     $this->app->instance(Process::class, $mock);
     

Extension Points

1. Custom Commands Extend the package by adding methods to WireSileo:

   public function generateKey(): string
   {
       return Process::fromShellCommandline('sileo key generate')->getOutput();
   }
   

2. Event System Dispatch events for tunnel lifecycle:

   // In WireSileo.php
   event(new TunnelEnabled($tunnelName));
   

3. API Wrapper If sileo has a REST API, create a WireSileoApi class to abstract HTTP calls:

   public function getTunnels(): array
   {
       return Http::post('http://localhost:8080/api/tunnels')->json();
   }
   

4. Queue Jobs Offload long-running commands (e.g., config sync) to queues:

   SyncWireGuardConfig::dispatch($tunnelName)->onQueue('wireguard');