README

A minimal, opinionated Laravel 13 starter kit for building versioned JSON APIs. It ships with authentication, a strict code quality pipeline, and a Docker-based development environment so you can start writing endpoints immediately.

Requirements

• PHP 8.5+
• Composer
• Docker (for Laravel Sail)
• Node.js and npm (used by the setup script for asset compilation)

Installation

Using the Laravel installer (recommended)

Requires the Laravel installer (composer global require laravel/installer).

laravel new my-api --using=alibori/laravel-api-starter-kit
cd my-api

Using Composer create-project

composer create-project alibori/laravel-api-starter-kit my-api
cd my-api

Both methods above trigger post-create-project-cmd automatically: they generate the application key, create the SQLite database file, and run the initial migrations.

Cloning the repository

git clone https://github.com/alibori/laravel-api-starter-kit.git my-api
cd my-api
composer run setup

The setup script installs Composer and npm dependencies, generates the application key, runs migrations, and compiles front-end assets.

Running Locally

Start the Docker services:

vendor/bin/sail up -d

Then start the development process (HTTP server, queue worker, log viewer, and Vite):

composer run dev

Stop Docker services when done:

vendor/bin/sail stop

Ports

Override any port by setting APP_PORT, VITE_PORT, or FORWARD_REDIS_PORT in your .env file.

API Structure

All API routes live under routes/api/ and are version-prefixed. The router loads routes/api/api.php, which applies a v1 prefix and delegates to routes/api/v1/v1.php. New API versions follow the same pattern by adding a new prefix group and a corresponding directory.

routes/
  api/
    api.php       # registers version prefix groups
    v1/
      v1.php      # v1 route definitions

Current Endpoints

Responses follow the Laravel API Resources pattern.

Authentication

This kit uses Laravel Sanctum v4 for token-based authentication. Sanctum is configured out of the box including the personal_access_tokens table migration.

To obtain a token, issue one from Tinker or build an endpoint:

vendor/bin/sail artisan tinker --execute 'echo App\Models\User::first()->createToken("dev")->plainTextToken;'

Pass the token in the Authorization header:

Authorization: Bearer <token>

Protected routes use the auth:sanctum middleware.

Development Commands

All commands are registered as Composer scripts and run via composer run <name>.

Additional utility scripts:

Code Quality

Laravel Pint

Laravel Pint enforces PSR-12 as the base preset with additional rules defined in pint.json (strict types, final classes, strict comparisons, arrow functions, and more).

composer run format          # fix all violations
composer run test:format     # report violations without fixing

PHPStan / Larastan

Larastan runs PHPStan at level 7 against the app/ directory. Configuration lives in phpstan.neon.

composer run analyse         # static analysis
composer run analyse:debug   # verbose output for debugging suppressions

Rector

Rector is configured in rector.php to target PHP 8.5 syntax and Laravel 13 idioms. It runs against both app/ and tests/.

composer run refactor        # apply refactors
composer run test:refactor   # preview changes without applying

Testing

The project uses Pest v4 with the Laravel plugin. Test suites are defined in phpunit.xml:

• tests/Unit/ — isolated unit tests
• tests/Feature/ — feature tests (database, HTTP)

Feature tests automatically use RefreshDatabase and fake Storage, HTTP, Queue, and Bus.

composer run test            # run all tests
composer run test:parallel   # run with 5 parallel workers

Filter to a specific test:

vendor/bin/sail artisan test --filter=SomeTestName

Architecture Tests

tests/Feature/ArchTest.php enforces project-wide rules on every CI run:

• No dd, dump, or ray calls left in code
• No direct env() calls outside of config files
• All classes under App\ must declare strict types and use strict equality operators

AI Development

This project includes Laravel Boost v2, which exposes an MCP (Model Context Protocol) server for AI coding agents such as Claude Code.

The MCP server is configured in .mcp.json and runs via Sail:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "vendor/bin/sail",
            "args": ["artisan", "boost:mcp"]
        }
    }
}

Boost provides agents with tools for database inspection, documentation search, error log access, and URL resolution, all scoped to this application's installed package versions.

The boost.json file controls which agents, skills, and integrations are active. Current skills: laravel-best-practices, pest-testing, spatie-laravel-php, spatie-javascript, spatie-security, spatie-version-control.

License

This project is open-sourced software licensed under the MIT license.