Download the PHP package shire-studio/laravel-starter-kit-api without Composer

A strict, fully tested Laravel 13 API starter kit with Sanctum token authentication and JSON resources. It shares its actions, form requests and models with the other Shire Studio starter kits, so the same application logic answers with JSON instead of pages.

Tech Stack

Backend: PHP 8.5+, Laravel 13, Laravel Sanctum, Nuno Maduro's Essentials

Code quality: PHPStan (level max via Larastan), Rector, Pint, Pest v5 (100% coverage)

Endpoints

Send the token as Authorization: Bearer <token>. Every response, including errors, is JSON. Password reset emails link to FRONTEND_URL, so point it at the client that collects the new password.

Local Development

Requires PHP 8.5+ and a code coverage driver such as Xdebug. composer dev also uses Node to run its processes side by side.

SQLite is used by default for the database, cache and queue.

The recommended way to start a project is the starter kit CLI. It works like the laravel installer, and it can also bring newer starter kit releases into your project later (see Keeping Your Project Up to Date).

Install it globally with Composer:

This installs the shire-kit command. Make sure Composer's global bin directory is on your PATH (run composer global config bin-dir --absolute to find it). Then create a project:

This creates example-app from the latest stable release of the API starter kit. There is no frontend to build, so you'll only be asked whether to initialise a git repository. Pass --git or --no-git to skip the question, or --force to overwrite an existing directory.

If you'd rather not install the CLI, composer create-project works too:

Either way, the project gets a .starter-kit.json file recording the kit and release it was created from. Commit it, because the CLI reads it to work out which starter kit changes your project hasn't received yet.

Then set it up:

Keeping Your Project Up to Date

Once you've built on the starter kit, you can't just pull in new releases, because your project has drifted from it. The CLI's update command handles this. Run it from the root of your project:

The project must be in a git repository with no uncommitted changes, so everything the update does can be reviewed with git diff and undone with git restore. It can live inside a larger repository, such as a monorepo.

The CLI compares the release in your .starter-kit.json with the latest one and writes the changes to .starter-kit-update/ (excluded from git). It then hands them to a coding agent of your choice, which merges them into your code, keeps your own changes and fixes anything the update breaks. Claude Code, Codex, Gemini CLI, OpenCode and Cursor are supported, and only the ones you have installed are offered. Pass --agent=<agent> to skip the question.

When the agent is done, the CLI shows the changed files and asks whether to mark the project as updated, which bumps the version in .starter-kit.json. Nothing is committed for you. Review the changes, run composer test, then commit.

A few things worth knowing:

• Removed features stay removed. If you deleted part of the starter kit, such as email verification, the update won't bring it back. The CLI can record these in .starter-kit.json so future updates remember them.
• You can skip the agent. --agent=none only prepares .starter-kit-update/. Follow .starter-kit-update/PROMPT.md yourself or give it to any agent you like.
• Older projects without a .starter-kit.json can still be updated. Pass --kit=api (or pick the kit when asked), and the agent works out which release the project started from and asks you to confirm it.

Update regularly. Small, frequent updates are much easier to review than one large jump across several releases. See the CLI README for every option.

Available Commands

• composer dev starts the app with Laravel's artisan dev process runner
• composer lint runs Rector and Pint and fixes what it can
• composer test:lint checks formatting without changing files
• composer test:types runs PHPStan
• composer test:type-coverage enforces 100% type coverage
• composer test:unit runs Pest with the 100% code coverage requirement
• composer test runs all of the above
• composer update:requirements bumps every PHP dependency to its latest version

Code Standards

• Actions oriented architecture: every operation lives in a single action class under app/Actions
• Cruddy by design: controllers stick to resourceful methods
• Immutable first: data structures favour immutability to prevent unexpected mutations
• Fail fast: strict static analysis catches errors before runtime
• Strict Laravel defaults: strict models, automatic eager loading and immutable dates via Essentials
• AI guidelines: the rules in .ai/rules keep generated code consistent with the rest of the codebase

Testing

The project uses Pest and enforces:

• 100% code coverage: the suite fails if coverage drops below 100%
• 100% type coverage: every method, property and parameter is explicitly typed
• Static analysis: PHPStan at level max

Run the full suite with:

Releasing

Releases are published by the release workflow, not from the Releases page. In the Actions tab, run it on main with the new version, for example v1.5.0.

The workflow writes the version to .starter-kit.json, commits it on top of main, tags that commit and publishes a GitHub release with generated notes. Every project created from the release then knows which version it started from, which the starter kit CLI uses to update it later. The release commit is only reachable from its tag, so main itself never has a .starter-kit.json.

Contributing

This repository is raised by Hobbiton, which grows every Shire Studio starter kit from shared smials. Please open issues and pull requests there, so a fix reaches every kit.

License

This project was created by Shire Studio under the MIT license.