Remoteserver Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acassan/remoteserver
   

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

   Acassan\RemoteServer\RemoteServerServiceProvider::class,
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="Acassan\RemoteServer\RemoteServerServiceProvider"
   

   Update config/remoteserver.php with your remote server details (host, port, credentials, etc.).

3. First Use Case: Connecting to a Remote Server Inject the RemoteServer facade or service into your controller/service:

   use Acassan\RemoteServer\Facades\RemoteServer;
   
   public function connectToRemote()
   {
       $connection = RemoteServer::connect();
       return $connection->isConnected() ? 'Connected!' : 'Failed.';
   }
   

4. Running a Simple Command

   $result = RemoteServer::execute('ls -la');
   dd($result); // Outputs the command result
   

Implementation Patterns

Common Workflows

1. Remote Command Execution

// Execute a command and get output
$output = RemoteServer::execute('php artisan migrate');

// Execute with error handling
try {
    $output = RemoteServer::execute('npm install');
} catch (\Acassan\RemoteServer\Exceptions\RemoteServerException $e) {
    Log::error("Remote execution failed: " . $e->getMessage());
}

2. File Operations

// Upload a file
RemoteServer::upload('local/path/file.txt', '/remote/path/file.txt');

// Download a file
$remoteFile = RemoteServer::download('/remote/path/file.txt', 'local/path/');

3. SSH-Based Authentication

Use the authenticate() method for SSH keys or passwords:

RemoteServer::authenticate([
    'username' => 'deploy',
    'password' => env('REMOTE_PASSWORD'),
    // OR for SSH keys:
    'private_key' => file_get_contents('/path/to/key'),
    'passphrase' => env('KEY_PASSPHRASE'),
]);

4. Batch Processing

$commands = [
    'cd /var/www/project',
    'git pull origin main',
    'composer install --no-dev',
];

foreach ($commands as $command) {
    RemoteServer::execute($command);
}

Integration Tips

Laravel Queues

Offload remote tasks to a queue job:

use Acassan\RemoteServer\Jobs\RemoteCommandJob;

RemoteCommandJob::dispatch('php artisan optimize:clear')
    ->onQueue('remote-tasks');

Event Listeners

Trigger actions post-remote execution:

RemoteServer::execute('deploy:update')->then(function ($output) {
    event(new DeploymentCompleted($output));
});

Configuration Management

Use Laravel's binding to dynamically configure remote servers:

$this->app->bind('remote.server.staging', function () {
    return RemoteServer::make()
        ->setHost('staging.example.com')
        ->setPort(22);
});

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • Default timeout may be too short for slow networks. Adjust in config:

     'timeout' => 30, // seconds
     

   • Debug with:

     RemoteServer::setDebug(true);
     

2. Permission Issues

   • Ensure the remote user has execute permissions for commands.
   • Use sudo cautiously (may require password input).

3. SSH Key Authentication

   • If using keys, ensure the ~/.ssh/ directory is properly configured on the remote server.
   • Passphrase-protected keys require the passphrase option.

4. Command Output Buffering

   • Large outputs may time out. Stream results with:

     $stream = RemoteServer::stream('tail -f /var/log/app.log');
     while ($line = $stream->read()) {
         Log::info($line);
     }
     

Debugging Tips

1. Enable Verbose Logging

   RemoteServer::setVerbose(true);
   

   Check Laravel logs for detailed SSH/connection output.

2. Test Locally First Use phpseclib's built-in tests to validate credentials:

   use phpseclib\Net\SSH2;
   
   $ssh = new SSH2(env('REMOTE_HOST'));
   if (!$ssh->login(env('REMOTE_USER'), env('REMOTE_PASSWORD'))) {
       die('Login failed');
   }
   

3. Handle Partial Failures Use try-catch blocks to gracefully handle transient failures:

   try {
       RemoteServer::execute('failing-command');
   } catch (\Acassan\RemoteServer\Exceptions\ConnectionException $e) {
       // Retry logic or notify admin
   }
   

Extension Points

1. Custom Command Classes Extend the base RemoteCommand class for reusable logic:

   namespace App\RemoteCommands;
   
   use Acassan\RemoteServer\RemoteCommand;
   
   class DeployCommand extends RemoteCommand {
       protected $commands = [
           'git pull',
           'composer install',
           'php artisan cache:clear',
       ];
   }
   

2. Middleware for Remote Calls Add middleware to log or transform remote requests:

   RemoteServer::getMiddleware()->push(function ($request) {
       Log::info("Remote call: {$request->command}");
       return $request;
   });
   

3. Dynamic Server Selection Use Laravel's container to switch servers dynamically:

   $server = app('remote.server.' . $environment);
   $server->execute('command');
   

4. Webhook Triggers Combine with Laravel's webhook package to trigger remote actions via HTTP:

   Route::post('/deploy', function () {
       RemoteServer::execute('deploy:latest');
       return response()->json(['status' => 'deployed']);
   });