laravel-services
Third-party integrations are services in app/Services/{Name}, built from a manager, drivers behind a contract, Saloon for HTTP, a facade and a deferred provider. Use when integrating an external API, adding a driver, connector or request, or writing a facade-backed service.
How do I install this agent skill?
npx skills add https://github.com/leeovery/agentic-skills --skill laravel-servicesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural templates and best practices for implementing a service layer in Laravel using the Manager pattern and the Saloon HTTP library. No security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Laravel Services
A service wraps something outside the domain, usually a third-party API, behind a facade the rest of the app calls: Shipping::getShipment($reference). An integration is a Laravel Manager that picks one of several drivers implementing the same contract. The real driver talks to the API through Saloon; a NullDriver stands in where the API shouldn't be called. Everything the service needs lives in its own folder, so it reads, swaps and extracts as one unit. A service holds no business rules: the action that calls it decides what happens.
app/Services/Shipping/
├── ShippingManager.php
├── Connector/ShippingConnector.php
├── Contracts/ShippingDriver.php
├── Data/ShipmentData.php # DTOs only this service uses
├── Drivers/
│ ├── ShippingV1Driver.php # the API, through Saloon
│ └── NullDriver.php
├── Enums/ShipmentStatus.php # enums only this service uses
├── Exceptions/ShippingException.php
├── Facades/Shipping.php
├── Requests/V1/GetShipmentRequest.php
└── Transformers/ShipmentDataTransformer.php # payload → DTO
app/Providers/ShippingServiceProvider.php
config/shipping.php
tests/Fixtures/Saloon/shipping/
Rules
- An integration is a manager with drivers. It always has at least two, the real one and the
NullDriver, so it always gets a manager. An internal service with one implementation, such as a generator, is a single class inapp/Services/{Name}/behind a facade, with no manager. - Drivers implement the service's contract.
Contracts/{Name}Driver. Methods take and return typed values and DTOs, never a SaloonResponseor a raw payload array, so callers can't tell one driver from another. - One driver per API version.
ShippingV1Driver, config keyshipping_v1, requests inRequests/V1/. A new API version is a new driver beside the old one, switched by config. - Config in
config/{name}.php. Adefaultread from{NAME}_DRIVERand onedriversentry per driver. The manager passes the values into the driver's constructor as named arguments; a driver never callsconfig(), so a test can build it directly. - Every integration has a
NullDriver. It returns empty but valid results and does nothing else. Local work that shouldn't reach the API setsSHIPPING_DRIVER=null.env()reads that value as PHPnull, sogetDefaultDriver()falls back to'null'. It isn't the test driver: see Testing. - One deferred provider per service, and it only registers.
scoped()the manager, alias it to'{name}-manager', and list both inprovides(). Scoped gives one manager per request or job, shared by the facade and anything that injects it, so a driver keeps its connector for that request or job; the queue worker forgets it before the next. Itsboot()stays empty: during a request a deferred provider boots only once the manager is resolved, so the service's rate limiter goes inAppServiceProvider::bootRateLimiters()with the rest, and anything that configures the scoped manager goes throughcallAfterResolving()(laravel-providers). - The facade resolves the alias and mixes in the contract.
getFacadeAccessor()returns'shipping-manager', and@mixin ShippingDrivergives every driver method to the IDE with no@methodlist to keep in step. Actions call it,Shipping::cancelShipment(...), or inject the service where that reads better (laravel-actions). - Saloon for HTTP. One connector per API in
Connector/, one request class per endpoint inRequests/. NeverHttp::or a hand-built Guzzle client in a driver. - The connector throws on failure.
use AlwaysThrowOnErrors, so every 4xx and 5xx raises Saloon'sRequestException. Never check$response->failed()by hand. - Auth through an authenticator.
defaultAuth()returns Saloon'sTokenAuthenticatororHeaderAuthenticator. NoAuthorizationheader indefaultHeaders(), and noContent-Typeon the connector:HasJsonBodysets it on the requests that send JSON. - The request maps its response.
createDtoFromResponse()hands the payload to the service's transformer, and the driver returns$response->dtoOrFail(). How the transformer is written is laravel-dtos' call.
Example
<?php
declare(strict_types=1);
namespace App\Services\Shipping;
use App\Services\Shipping\Drivers\NullDriver;
use App\Services\Shipping\Drivers\ShippingV1Driver;
use Illuminate\Support\Manager;
class ShippingManager extends Manager
{
public function getDefaultDriver(): string
{
return $this->config->get('shipping.default') ?? 'null';
}
public function createShippingV1Driver(): ShippingV1Driver
{
return new ShippingV1Driver(
baseUrl: $this->config->get('shipping.drivers.shipping_v1.base_url'),
token: $this->config->get('shipping.drivers.shipping_v1.token'),
);
}
public function createNullDriver(): NullDriver
{
return new NullDriver;
}
}
<?php
declare(strict_types=1);
namespace App\Providers;
use App\Services\Shipping\ShippingManager;
use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;
class ShippingServiceProvider extends ServiceProvider implements DeferrableProvider
{
public function register(): void
{
$this->app->scoped(ShippingManager::class);
$this->app->alias(ShippingManager::class, 'shipping-manager');
}
public function provides(): array
{
return [
ShippingManager::class,
'shipping-manager',
];
}
}
<?php
declare(strict_types=1);
namespace App\Services\Shipping\Facades;
use App\Services\Shipping\Contracts\ShippingDriver;
use Illuminate\Support\Facades\Facade;
/**
* @mixin ShippingDriver
*/
class Shipping extends Facade
{
public static function getFacadeAccessor(): string
{
return 'shipping-manager';
}
}
The provider is listed in bootstrap/providers.php. Read references/saloon-driver.md when writing a driver, its config, connector and requests, or its tests.
An internal single-class service gets the same facade with its class as the accessor, written fully qualified because the facade shares its short name: \App\Services\PasswordGenerator\PasswordGenerator::class. The container builds it, so it needs no provider. When its constructor needs config, bind it in its own deferred provider and alias it like a manager.
Testing
| What's under test | How |
|---|---|
| A driver | Build it with the testing config, then Saloon::fake([GetShipmentRequest::class => MockResponse::fixture('shipping/get_shipment')]) |
| A failure | MockResponse::make(body: '', status: 404) and ->throws(NotFoundException::class) |
| Code that calls the facade | Shipping::shouldReceive('cancelShipment')->once() |
| Code that injects the manager | mock(ShippingManager::class)->shouldReceive('cancelShipment')->once(): a facade mock replaces only the 'shipping-manager' alias, so an injected manager would still be the real one |
- Fixtures are real responses.
MockResponse::fixture()records the response when its file is missing; record each one once against the API and commit it undertests/Fixtures/Saloon/{name}/. CallMockConfig::throwOnMissingFixtures()in the driver test so a missing fixture fails instead of reaching the API. - No stray requests. Call
Saloon\Config::preventStrayRequests()once, at the top oftests/Pest.php, so a Saloon request with no fake throws. It registers a global check each time it's called, so calling it per test insetUp()piles them up.Http::preventStrayRequests()doesn't catch it, even through Saloon's Laravel HTTP sender, which builds its request outside the factory's stray-request check. .env-testingkeeps the real driver, with placeholder credentials, because the driver tests build it from that config. Nothing else reaches it: callers mock the facade.
More in laravel-testing.
Reach for these when the situation calls for it
Callers that handle the failure. When an action catches a failed call to fall back, mark a record failed or retry later, the driver catches RequestException|FatalRequestException and throws the service's own exception with the original as previous. Callers then catch one type and the cause still reaches the log. FatalRequestException, a request that got no response at all, is not a RequestException.
An API that issues short-lived tokens. Fetch the token in the connector's boot() and keep it and its expiry on the connector. Return early for the token request itself, which boots too. The scoped driver holds one connector for the request or job, so every call in it reuses the token; a token that must outlive that goes in the cache, keyed by its expiry.
A slow endpoint. use HasTimeout on the connector, set $connectTimeout and $requestTimeout (seconds), and add a comment saying why those numbers.
Transient failures. Set $tries and $retryInterval (milliseconds) on the connector or the request. sendAndRetry() is deprecated in Saloon v3. Leave retries off when the caller is a queued job that already retries, or each job attempt multiplies them.
A response that rarely changes. Cache it in the Fetch…Action that calls the service, never in the driver, so the cache key and lifetime sit with the code that decides them.
Anti-patterns
- ❌
if ($response->failed()) { throw … }in a driver. - ❌
'Authorization' => "Bearer {$this->token}"or'Content-Type' => 'application/json'in a connector'sdefaultHeaders(). - ❌ A driver method returning a Saloon
Response,$response->json()or a payload array. - ❌
config('shipping.drivers.shipping_v1.token')inside a driver or connector. - ❌ A rate limiter, gate, listener or macro in a per-service provider's
boot(). - ❌
SHIPPING_DRIVER=nullin.env-testing, or a driver test with no fake that calls the real API. - ❌ Hand-kept
@method staticlines on an app facade. - ❌
$connector->sendAndRetry(...).
Related
- laravel-actions: the actions that call services
- laravel-dtos: the service's
Data/andTransformers/ - laravel-providers: deferred providers,
bootstrap/providers.phpand rate limiters - laravel-exceptions: the service's exception factories
- laravel-architecture: where
Services/sits in the app - laravel-testing: testing style
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/leeovery/agentic-skills/laravel-services">View laravel-services on skillZs</a>