Saloon API SDK (template)

Boilerplate for Laravel-ready PHP API client packages using Saloon v4: connector, optional rate limiting, Laravel service provider, Pest, PHPStan, and Pint.

This repository is intended to be used as a GitHub template. After you create a new repository from it, customize the package identity and class names with the one-time init script below (it deletes itself after a successful run).

Requirements

• PHP ^8.4
• Laravel ^11.0 || ^12.0 || ^13.0 (for the optional Laravel integration)

AI and editor rules

This template includes the same rule layout as the luma-sdk package: .claude/rules/ (saloon.md, php-package-phpstan.md, laravel-package.md) for Claude Code, and .cursor/rules/ (.mdc mirrors with globs front matter) for Cursor. The Laravel rules file notes that this repo uses laravel/pint in require-dev and composer lint / composer format, which differs from the optional “global Pint only” wording elsewhere in that document.

Laravel Boost-style helpers live under resources/boost/: guidelines/core.blade.php (stub) and two skills — a one-time safebase-sdk-initial-setup skill that generates API-specific content, and a safebase-sdk-development skill (stub until the initial-setup skill is run). The init script renames both skill folders to use your package slug ({package-slug}-initial-setup and {package-slug}-development).

CLAUDE.md at the repo root summarizes commands, checks, and architecture; run ./init-saloon-sdk.sh once after creating a new repo so names in that file match your package.

First-time setup (after “Use this template”)

1. Clone your new repository and install dependencies:

   composer install
   

2. Run the initializer at the repo root. It will prompt for:

   • Composer vendor — replaces laravel-gtm (e.g. laravel-gtm).
   • Package slug — replaces safebase-sdk everywhere, including the second segment of the Composer name and the config file basename (e.g. hubspot-sdk → laravel-gtm/hubspot-sdk).
   • Short class prefix — PascalCase, without Sdk on the end; the script adds Sdk, Connector, and ServiceProvider for you (e.g. Hubspot → HubspotSdk, HubspotConnector, HubspotServiceProvider).
   • Env prefix — replaces SAFEBASE_ in the published config (e.g. HUBSPOT_API).
   • Default API base URL.

   The PHP root namespace is derived as {VendorPascal}{Prefix}Sdk (e.g. laravel-gtm + Hubspot → LaravelGtm\HubspotSdk). composer.json keeps JSON’s doubled backslashes (\\) in autoload and extra.laravel.providers; you do not need to type those.

   chmod +x init-saloon-sdk.sh
   ./init-saloon-sdk.sh
   

   Non-interactive (e.g. CI), same values as environment variables:

   export COMPOSER_VENDOR='laravel-gtm'
   export PACKAGE_SLUG='hubspot-sdk'
   export SHORT_PREFIX='Hubspot'
   export ENV_PREFIX='HUBSPOT_API'
   export DEFAULT_BASE_URL='https://app.safebase.io'
   ./init-saloon-sdk.sh
   

   Preview changes without writing files (--dry-run does not delete the script):

   ./init-saloon-sdk.sh --dry-run
   

   After a successful full run (Composer install, tests, PHPStan, Pint), init-saloon-sdk.sh removes itself so it cannot be applied twice by mistake.

3. Update README badges and repository URLs (Packagist, GitHub Actions) for your package.

4. Replace the example ExampleGetRequest / ping() flow with real endpoints, DTOs, and resources for your API.

5. Once you have added initial request classes, response DTOs, and resource methods, run the safebase-sdk-initial-setup Boost skill (via an AI agent) to generate API-specific content for:

   • resources/boost/skills/safebase-sdk-development/SKILL.md — comprehensive development guide with real class names, code examples, and testing patterns
   • resources/boost/guidelines/core.blade.php — Boost guidelines with setup instructions and code snippets

   This replaces the placeholder stubs with real documentation matching your SDK's structure. After the init script, the skill name will be {your-package-slug}-initial-setup.

6. In GitHub: Settings → General → Template repository — enable only on the canonical template repo, not on forks meant for production.

Configuration (Laravel)

Publish the config (before init the tag is safebase-sdk-config; after init it becomes {your-package-slug}-config):

php artisan vendor:publish --tag=safebase-sdk-config

After running the init script, use your package slug in the tag (e.g. hubspot-sdk-config). Env keys use your chosen ENV_PREFIX (defaults before init use SAFEBASE_*):

• SAFEBASE_BASE_URL
• SAFEBASE_TOKEN
• SAFEBASE_AUTH_HEADER

Usage

Via the service container

use LaravelGtm\SafebaseSdk\SafebaseSdk;

$sdk = app(SafebaseSdk::class);

Standalone

use LaravelGtm\SafebaseSdk\SafebaseSdk;

$sdk = SafebaseSdk::make(
    baseUrl: 'https://app.safebase.io',
    token: 'your-token',
);

Example call

The template exposes a ping() method wired to GET /v1/ping — replace this with real API methods.

Development

composer test        # Pest
composer analyse     # PHPStan
composer lint        # Pint (check)
composer format      # Pint (fix)

License

MIT. See LICENSE.