Akeeba Laravel Package

Getting Started

• Mental model first: this is a Symfony 3+ bundle, not a Laravel package. There is no service provider, no auto-discovery, no config/akeeba.php. Laravel will not "just load" it. Expect to spend your first hour reading vendor/philetaylor/akeeba/ — specifically the DependencyInjection/ folder (to learn config keys) and the Service/ or Api/ class (the actual client you want).
• Install: composer require philetaylor/akeeba.
• Prerequisite on the Joomla side: Akeeba Backup must be installed, and its JSON API must be enabled in the component options. You get a base URL and a secret API key. Without this, nothing works.
• Minimal wiring in Laravel: skip the Symfony DI machinery. Bind the underlying client class manually in a service provider:

$this->app->singleton(AkeebaClient::class, fn () => new AkeebaClient(
    config('services.akeeba.url'),
    config('services.akeeba.key'),
));

• Store credentials in config/services.php + .env (AKEBBA_URL, AKEBBA_KEY). The key is a query-string secret, not a header — treat it like a password.
• First use case: pull the backup history and show it on a dashboard. Call the "list/get backups" method, map the array into a small value object (Backup with createdAt, size, status). This validates connectivity and response shape before you attempt anything destructive.

Implementation Patterns

• Wrap, don't inject. Create a Laravel service — App\Services\AkeebaService — that owns the client. Controllers, jobs, and commands never touch the vendor class. This is your seam for mocking, retries, and eventually replacing the bundle with five raw Guzzle calls.
• Trigger backups asynchronously. A full site archive takes minutes. Put the trigger in a queued job (php artisan make:job TriggerAkeebaBackup), never in a synchronous web request.
• Poll, don't block. Fire the backup, then a CheckAkeebaBackupStatus job re-dispatches itself with delay until the API reports complete. This pairs naturally with Laravel's scheduler for weekly triggers.
• Stream archives. Use the API's download endpoint and stream straight to disk/S3 (Storage::put($path, $stream)). Do not buffer a multi-hundred-MB archive into memory.
• Staleness watchdog (highest day-to-day value): a scheduled command that fetches the latest backup date per site and alerts (Slack/mail) if older than X hours. This is often the only thing you actually need from the API.
• Multi-site loop: keep a config array of [url, key] pairs, resolve a fresh client per entry, and iterate. The client is cheap to construct.
• Adapter interface: define interface BackupProvider { public function history(): array; public function trigger(): string; } and implement it with this bundle. When the bundle rots (see below), you swap the implementation and nothing else changes.

Gotchas and Tips

• Package health is the headline issue. Zero stars, zero dependents, likely a personal project. It is not a maintained dependency. Read the source before trusting it, pin the exact version in composer.json, and be ready to fork. Seriously evaluate whether ~5 Guzzle calls against the Akeeba JSON API is a better investment than integrating a Symfony bundle into Laravel.
• No auto-discovery. If you try to register the bundle via Laravel's package discovery, it won't work — Symfony bundles rely on Extension/CompilerPass semantics Laravel doesn't have. Manual instantiation of the client class is the pragmatic path.
• The API key leaks easily. It lives in the query string, so naive Log::info($url) or exception traces will expose it. Sanitize URLs before logging and set 'debug' => false on the HTTP client in production.
• HTTP 200 with an error body. Akeeba's JSON API frequently returns success status codes with { "error": ... } payloads. Parse the body; never trust the status code alone.
• Timeouts will bite you. Default Guzzle timeouts are too short for backup/list operations on large sites. Set explicit timeout and a separate connect_timeout.
• Response shape drift. Akeeba's API has changed across versions (backup status codes, error envelopes, field names). Log raw responses to a debug channel during rollout.
• TLS pitfalls. Self-signed certs on staging Joomla sites cause cURL errors that look like connection failures. Decide deliberately on verify => false for non-prod only.
• Error semantics. A "backup already running" condition may surface as an error string rather than an HTTP error — check the message and treat it idempotently (return the existing job id) rather than crashing.
• Testing. Never hit a live site in CI. Mock at the AkeebaService boundary and keep recorded JSON responses as fixtures so you notice when the API shape shifts.