Linode Laravel Package

Getting Started

1. Install the package:

   composer require samuelmwangi/linode
   

2. Publish the config file:

   php artisan vendor:publish --tag=linode-config
   

3. Add a Linode API token to .env:

   LINODE_TOKEN=your-personal-access-token
   

   Create the token in Linode Cloud Manager and grant only the scopes you need (e.g. linodes:read_write, volumes:read_write). The package reads the token from config/linode.php, which pulls from LINODE_TOKEN.

4. First use case — a read-only inventory check to confirm auth and transport are wired correctly:

   use SamuelMwangiW\Linode\Facades\Linode;
   
   $linodes = Linode::linodes()->all();
   

   If this returns a collection of Linode records, the connector is configured. From there, move to creating resources or wiring the package into a provisioning job. The package exposes resources such as linodes(), volumes(), domains(), images(), regions(), and account() through the Linode facade.

Implementation Patterns

Facade resource access. The common day-to-day pattern is a fluent resource call off the facade:

Linode::linodes()->all();
Linode::linodes()->find($id);
Linode::linodes()->create([
    'region' => 'eu-west',
    'type' => 'g6-nanode-1',
    'image' => 'linode/debian12',
    'label' => 'web-1',
    'root_pass' => $password,
]);

Keep these calls behind your own service or action class rather than scattering them through controllers. That gives you one place to swap in a fake and one place to change when the upstream API shifts.

Inject the connector for testability. If you need more control than the facade offers, resolve the underlying connector from the container and inject it into your service. This makes it straightforward to substitute a mock client in tests and avoids relying on facade state.

Custom Saloon requests. The package is built on Saloon, so endpoints not yet wrapped can be added with your own request classes rather than dropping to raw Http:: calls. Send them through the package connector so base URL, auth headers, and retry behaviour stay consistent:

$response = Linode::connector()->send(new MyCustomRequest($args));

This is also the right integration point for account-specific or beta Linode endpoints.

Testing. Fake at the HTTP layer (Http::fake()) or use Saloon's mock client against the connector. Assert on the outgoing request shape and return fixture payloads that match real Linode responses. Because the package returns DTOs/collections, test the transformation into your own domain objects, not just the raw response.

Provisioning workflows. Put create-and-wait flows in queued jobs. A Linode create call returns immediately with a provisioning status; poll Linode::linodes()->find($id) (with backoff) or listen for the relevant event before treating the instance as ready. Do not assume a successful create response means the host is booted.

Gotchas and Tips

Saloon v3 is a major upgrade. v2.4.0 bumps the package from Saloon v2 to Saloon v3. Facade-level calls (Linode::linodes()->all(), etc.) should be unaffected, but anything that touches Saloon directly is at risk:

• Custom request/connector classes you wrote against the package connector.
• Tests using Saloon's mock client and assertion helpers — the v3 API differs from v2, so fakes may need rewriting.
• Custom response handling, DTO hydration, or middleware/pipeline hooks.

If you have custom Saloon integrations, read the Saloon v3 upgrade guide and run your test suite before deploying. If you cannot upgrade immediately, pin to ^2.3 until your custom code is compatible.

PHP and framework requirements moved. Saloon v3 requires PHP 8.2+, so the package's effective floor is now PHP 8.2. Check composer.json constraints and your CI matrix before rolling this out; an upgrade that passes locally on 8.3 can fail in a production image still on 8.1.

Token scopes produce misleading errors. A token with insufficient scope often surfaces as a generic 401/403 rather than a clear "missing scope" message. When a call fails unexpectedly, verify the token's scopes in Cloud Manager before debugging the code.

Rate limits are real. Linode enforces per-endpoint rate limits. Enable Saloon retry/backoff on the connector, and handle 429 explicitly. Bulk operations (listing all volumes across many Linodes, for example) are the usual trigger.

Pagination is not count(). Linode paginates with page/pages/results. Do not treat a returned collection's size as the total resource count; iterate pages or use the package's pagination helper if present.

Config caching. After changing LINODE_TOKEN, run php artisan config:clear in environments using cached config. A stale cached token is a common cause of "it works locally but not in staging".

Async state transitions. Create, resize, rebuild, and delete are all asynchronous. Poll or subscribe to events; otherwise you will hit race conditions where a follow-up call runs against a resource that is still transitioning.

Error handling. Saloon throws request exceptions on non-2xx responses. Catch them at your service boundary, inspect the response body and status, and translate into your own exceptions so callers are not coupled to Saloon's exception types — important given the v3 upgrade.