README

Laravel integration for community-sdks/spaceship-php v2. Provides auto-discovery, a configured SDK singleton, and a facade. All SDK services, typed request/response DTOs, and exceptions remain available.

Requires PHP 8.2+ and Laravel 11, 12, or 13 (subject to Laravel's own PHP requirements).

Install locally

This workspace is a Composer package; it has not been published. In your Laravel application's composer.json, add a path repository pointing to this directory:

{
    "repositories": [
        {"type": "path", "url": "../SpaceshipLaravelSDK", "options": {"symlink": true}}
    ]
}

Then run in the application:

composer require community-sdks/spaceship-laravel:@dev
php artisan vendor:publish --tag=spaceship-config

Adjust the relative path to your checkout. After publishing this package to a Composer repository, applications can install it by its package name without the path repository.

Laravel discovers the provider and Spaceship facade alias automatically. If discovery is disabled, register CommunitySDKs\Spaceship\Laravel\SpaceshipServiceProvider in bootstrap/providers.php.

Configuration

Add credentials to your application's .env:

SPACESHIP_API_KEY=your-api-key
SPACESHIP_API_SECRET=your-api-secret
SPACESHIP_ENVIRONMENT=sandbox
SPACESHIP_TIMEOUT=30
# SPACESHIP_ENDPOINT=https://spaceship.dev/api

Use production for the production environment. The endpoint override is optional; otherwise the SDK selects its endpoint. Timeout is a positive integer in seconds. Credentials and options are validated only when the client is first resolved, so unrelated Artisan commands work without credentials. Errors do not include credential values.

Configuration supports php artisan config:cache. Rebuild the cache and restart long-running workers after changing credentials or options: the client is a singleton.

Usage

use CommunitySDKs\Spaceship\DTO\Domains\Request\GetDomainListRequest;
use CommunitySDKs\Spaceship\Laravel\Facades\Spaceship;

$page = Spaceship::domains()->getDomainList(
    new GetDomainListRequest(take: 20, skip: 0),
)->data;

foreach ($page->items as $domain) {
    echo $domain->name->value;
}

For dependency injection, type-hint the upstream client:

use CommunitySDKs\Spaceship\Client;
use CommunitySDKs\Spaceship\DTO\Domains\Request\GetDomainListRequest;

final class ListDomains
{
    public function __construct(private readonly Client $spaceship) {}

    public function __invoke(): array
    {
        return $this->spaceship->domains()->getDomainList(
            new GetDomainListRequest(take: 20, skip: 0),
        )->data->items;
    }
}

app(Client::class), app('spaceship'), and the facade resolve the same client. Services include domains(), dnsRecords(), contacts(), contactsAttributes(), asyncOperations(), sellerhub(), and hyperlift().

See the upstream documentation for DTOs and operations. Pagination and async polling are caller-controlled. SDK API exceptions and Guzzle transport exceptions propagate unchanged; this wrapper adds no retries.

Custom HTTP transport and application tests

Set http_client in config/spaceship.php to a container binding name (a string, not a closure or object). Register that binding in your application's service provider before resolving Spaceship. It must resolve to GuzzleHttp\ClientInterface.

For example, in an application test, before first use of the facade:

use GuzzleHttp\Client as HttpClient;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

$this->app->instance('spaceship.http', new HttpClient([
    'handler' => HandlerStack::create(new MockHandler([
        new Response(200, [], '{"items":[],"total":0}'),
    ])),
]));
config()->set('spaceship.http_client', 'spaceship.http');
config()->set('spaceship.api_key', 'test-key');
config()->set('spaceship.api_secret', 'test-secret');

The SDK uses Guzzle, so Laravel's Http::fake() does not intercept these requests. The SDK client is final; use the mocked transport to test actual DTO handling.

Development

composer install
composer validate --strict
composer test

Tests use Orchestra Testbench and mocked HTTP responses; no Spaceship account is needed. CI covers Laravel 11–13.

License

MIT. See LICENSE.

community-sdks / spaceship-laravel

Maintainers

Package info

Statistics

Security