Client Cli Laravel Package

Getting Started

Treat rokka/client-cli as an operational CLI for Rokka, not as a Laravel HTTP SDK. It has no service provider, facade, config publishing, or Eloquent-style integration. Use it to provision stacks, upload/inspect source images, and run one-off Rokka administration tasks; use the Rokka PHP client or direct URL construction for runtime image delivery.

Minimal setup:

composer require --dev rokka/client-cli
vendor/bin/rokka list
vendor/bin/rokka help <command>

If production jobs or deploy scripts invoke the CLI, install it as a normal dependency instead of --dev; composer install --no-dev will otherwise remove the binary.

Configure credentials in Laravel and make sure the CLI receives them explicitly:

// config/services.php
'rokka' => [
    'api_key' => env('ROKKA_API_KEY'),
    'organization' => env('ROKKA_ORGANIZATION'),
],

ROKKA_API_KEY=
ROKKA_ORGANIZATION=

First practical use case: in staging, create/verify an image stack, upload a source image, confirm the returned identifier/URL, then store the stack name in config/services.php and use it when rendering image URLs in Blade. Start by reading the package README and running vendor/bin/rokka list/help; do not assume command names from the package name.

Implementation Patterns

Wrap the CLI in one small adapter so command syntax, binary path, credentials, exit-code handling, and logging live in one place:

namespace App\Support;

use Illuminate\Support\Facades\Process;
use Illuminate\Contracts\Process\ProcessResult;

class RokkaCli
{
    public function run(array $arguments, ?string $cwd = null): ProcessResult
    {
        return Process::path($cwd ?? base_path())
            ->timeout(300)
            ->env([
                'ROKKA_API_KEY' => config('services.rokka.api_key'),
                'ROKKA_ORGANIZATION' => config('services.rokka.organization'),
            ])
            ->run(array_merge([
                PHP_BINARY,
                base_path('vendor/bin/rokka'),
            ], $arguments));
    }
}

Use array arguments, not shell strings. This avoids quoting problems with filenames and prevents shell injection:

$result = app(RokkaCli::class)->run([
    'image', 'upload', Storage::path($path),
]);

Verify the actual command names with vendor/bin/rokka list; encode only verified commands in your adapter.

Common day-to-day patterns:

• Artisan command wrapper: create php artisan rokka:sync-stack or rokka:upload commands for repeatable operations. Validate inputs, support --dry-run, log sanitized command arguments, and return non-zero on failure.
• Queued uploads: dispatch a job that calls the adapter. Use Storage::path() for local files or download remote/S3 files to a temporary path first. Keep uploads out of HTTP requests.
• Deployment provisioning: run stack creation/update commands from a deploy script or release step. Make them idempotent and check exit codes.
• Bulk migration: loop over records in a chunked Artisan command, upload source images, store returned hashes/URLs in the database, and log per-item failures. Add rate limiting/sleeps if Rokka or the CLI rate-limits.
• Runtime URL generation: do not shell out on every page render. Store stack names and image hashes/URLs, or use the Rokka PHP client/URL builder at runtime.

Keep a boundary between “provisioning/ops” and “serving images”:

// Ops: provision stack once
app(RokkaCli::class)->run(['stack', 'create', $stackName]);

// Runtime: construct/store URL or use Rokka client, not CLI
$url = "https://{$organization}.rokka.io/{$stack}/{$hash}/{$filename}";

For tests, use Laravel’s process fake and assert the command shape:

Process::fake();
// call your Artisan command/job
Process::assertRan(fn ($process) => str_contains($process->command, 'rokka'));

Run real integration tests only against a dedicated Rokka test organization.

Gotchas and Tips

• This is a CLI, not an SDK. Avoid invoking it per image request, per Blade render, or in hot paths. Process startup, network calls, and output handling are too expensive.
• No Laravel integration to rely on. There is no facade, service provider, config file, or publishable migration. Your adapter and Artisan commands are the integration layer.
• Pin the version. With low stars/dependents, command names, flags, and output formats may change. Wrap it behind your own adapter so upgrades are contained. Check release notes before updating.
• API key handling: prefer environment variables over CLI flags. Flags may appear in process lists and logs. When calling through Process, pass credentials via ->env() and log a sanitized command only.
• Config cache mismatch: Laravel’s config:cache values are not automatically forwarded to a subprocess. Read config in PHP and pass the values through Process::env(), or ensure the CLI’s expected environment variables are present in the worker/container.
• Binary execution: use PHP_BINARY plus vendor/bin/rokka to avoid executable-bit/shebang issues. On Windows the binary path may be .bat; containerize or normalize paths if the team is mixed-OS.
• Timeouts and large files: Laravel’s process timeout may be too short for image uploads. Set a deliberate timeout or use Process::forever() for long jobs, and watch memory/output limits. Prefer file paths over piping large binary data through stdout.
• Exit codes are necessary but not sufficient. Check $result->failed() and inspect stderr. Some CLIs can exit 0 with warnings; log output for operational commands.
• Non-interactive mode: always run with --no-interaction-style flags if supported so queued jobs/deploys never block on prompts. Confirm the exact flag with vendor/bin/rokka help.
• Do not scrape human-readable tables. If the CLI does not document machine-readable output, derive URLs from stored identifiers or use the Rokka PHP client. Parsing console tables is brittle.
• Deployment dependency trap: if a queue job or deploy script runs the CLI, --dev will break production after composer install --no-dev. Decide explicitly whether the binary is dev-only or production-operational.
• File permissions in queue workers: uploads from storage/app must be readable by the worker and by the CLI subprocess. Avoid relying on interactive-shell environment variables that are absent under Supervisor/systemd.
• Debug sequence: run the exact command manually from the project root, inspect --help, check exit code and stderr, then reproduce through Process::run() with the same environment. Log the command without secrets and the full output on failure.
• Maturity risk: small package, few dependents, and CLI-only scope mean limited Laravel examples. Budget for reading the README/help output and owning a thin wrapper. Keep it isolated so replacing it with the Rokka PHP client later is straightforward.