Client Cli Laravel Package

Technical Evaluation

Architecture fit This is not a Laravel package — it is a standalone Symfony Console binary that wraps rokka/client-php to drive the rokka.io image CDN (stacks, transformations, asset uploads). It ships no service provider, no config publish, no facade. The correct architectural framing is developer/ops tooling, not a runtime dependency. Fit with a Laravel codebase is therefore indirect: it belongs alongside deploy scripts, CI runners, and provisioning jobs, while application code should depend on the underlying SDK, not on shelling out to a CLI.

Integration feasibility

• High for build/deploy-time operations: stack provisioning, bulk asset seeding, environment parity checks, one-off migrations. Installable as a global Composer binary or inside a build image with no impact on composer.json of the app.
• Medium for in-app invocation via Process/artisan wrappers — workable but introduces output-parsing and exit-code coupling.
• Low for request-path use. Never call this synchronously during a user request; latency, auth handling, and failure semantics are wrong for that.
• The CLI's thin-adapter design is a genuine strength: low coupling means low blast radius if we later replace it with direct SDK calls or Artisan commands.

Technical risk

• Adoption risk is the headline. 6 stars, 0 dependents, single-maintainer signal. Bus factor is effectively 1–2. MIT licensing means we can fork at low legal cost, but we own the fork thereafter.
• Version drift between the CLI and the SDK is the most likely runtime issue; pin both and upgrade deliberately.
• Vendor coupling to rokka.io is inherent to the package's purpose — evaluate it as a CDN procurement decision, not a library decision.
• Operational scripting risk: unparsed human-readable output, swallowed non-zero exit codes in CI, partial uploads leaving inconsistent state.
• Credential handling must go through environment/secret stores; avoid embedding API keys in committed stack definitions.

Key questions

1. Are we already committed to rokka.io as an image CDN? If not, this package is premature.
2. Does the CLI expose every stack/operation we need, or will we immediately need the SDK anyway (making the CLI a convenience only)?
3. Is machine-readable output (JSON) supported, or will we be screen-scraping?
4. Who owns the API keys and the stack-definition source of truth?
5. What is our fork-and-maintain cost if upstream goes quiet for 12 months?

Integration Approach

Stack fit Laravel 10/11/12 on PHP 8.1+ with Composer. The CLI itself does not need to live in the application's dependency graph — install it globally in CI images and developer machines, or as a require-dev entry scoped to a tooling package. Application code that needs rokka at runtime should use rokka/client-php directly behind a small internal service class, keeping the transport swappable.

Migration path

1. Pilot in one non-critical project to validate auth, stack definitions, and upload throughput.
2. Codify stack definitions as reviewed files in the repo (JSON/YAML), replacing hand-run console commands.
3. Automate invocation from CI/deploy scripts with explicit exit-code checks and idempotent operations.
4. Absorb the two or three most-used commands into Artisan commands (rokka:stacks:sync, rokka:assets:seed) that wrap the SDK, giving us logging, confirmation prompts, and environment guards.
5. Retire the direct CLI dependency in favour of the Artisan surface once parity is reached; retain the CLI for ad-hoc debugging.

Compatibility

• Verify the CLI's PHP constraint against our runtime matrix before adding it to shared images.
• Global installation sidesteps Composer constraint conflicts with laravel/framework and Symfony Console versions used by Artisan.
• Confirm the CLI's pinned SDK version matches any in-app SDK version to avoid divergent behaviour between deploy-time and runtime operations.

Sequencing Sequencing should follow risk, not convenience: credentials and account validation first, then read-only commands (list stacks, inspect assets), then mutating operations (create stack, upload), then CI automation, then Artisan wrapping. Do not automate deletes or stack overwrites until the read path is proven and an audit trail exists.

Operational Impact

Maintenance Low surface area — the tool is small and does one thing. The real maintenance burden is upstream continuity, not code complexity. Pin exact versions, subscribe to releases, and pre-agree a fork trigger (e.g. six months without a release plus a blocking bug). Budget roughly a few days per year for version bumps and one to two weeks if a fork becomes necessary.

Support Community-only via GitHub issues; no SLA. Commercial support exists for the rokka.io service, which is the part that actually carries production risk. Internal ownership should sit with the platform/DevOps team, documented in the runbook alongside other deploy tooling.

Scaling The CLI is stateless and per-invocation, so it does not scale in the application sense. Scaling concerns shift to the API: rate limits, concurrency on bulk uploads, and timeouts on large asset sets. Design seeding jobs to be resumable and batched, and treat rokka's transformation cache as a cost and latency variable during capacity planning.

Failure modes

• Auth/credential expiry failing late in a deploy, after other steps have mutated state.
• Network timeout mid-upload producing partial, non-obvious inconsistency.
• Non-zero exit codes not propagated through shell wrappers or Process calls.
• Stack name collisions across environments (staging writes into production stacks).
• Silent output-format changes after an unpinned upgrade breaking parsers.
• Credential leakage through CI logs or committed config.

Mitigations: idempotent operations keyed by name, environment-prefixed stack names, explicit exit-code assertions, dry-run flags, and secrets via CI secret stores.

Ramp-up Very low for engineers comfortable with CLIs and CI — hours, not days. The learning curve is domain knowledge (rokka stacks, operations, transformation syntax), not the tool. Document the stack model and the two or three supported workflows; avoid letting the team treat the CLI as a general-purpose API client. For a TPM, the staffing ask is one owner for credentials and stack definitions plus a documented runbook, not a dedicated maintainer.