Kit: An Opinionated API Starter Kit for Laravel

Getting Started with Kit

To begin using Kit, developers need to clone the repository, install the necessary dependencies, and run the setup script. The following commands will set up your environment:

composer install
composer run setup
php artisan serve

The composer run setup command performs several critical tasks:

• Copies .env.example to .env.
• Generates a unique application key.
• Runs migrations against a local SQLite database.

API Architecture Overview

Kit adopts specific architectural choices to streamline API development:

• No global /api prefix: Routes are versioned directly, such as /v1/auth/login.
• Invokable controllers: Each controller is designed as a single __invoke method.
• Form Requests for validation: Payloads are validated using dedicated FormRequest classes, ensuring clean and maintainable code.
• JSON:API resource format: Responses are structured consistently to enhance the client experience.

Authentication Mechanism

Kit simplifies the authentication process with nine dedicated routes that handle the complete authentication lifecycle:

• Registration and Login: Both processes return tokens through Laravel Sanctum.
• User Information: The route /v1/auth/me retrieves user data and requires a Bearer token.
• Email Verification: Utilizes signed URLs for secure email verification.
• Password Reset: Implements anti-enumeration responses to enhance security.

Security Features

Security is a top priority in Kit, which includes several built-in features:

• ULID Primary Keys: User records are assigned ULID primary keys to enhance uniqueness and security.
• Predefined Rate Limits: Configurable rate limits on authentication endpoints help prevent abuse.
• Mandatory Content-Type Enforcement: Ensures that all write requests have the application/json content type.
• Hardened Response Headers: Includes security headers like X-Content-Type-Options: nosniff and X-Frame-Options: DENY.
• Request ID Tracking: Facilitates tracking of requests for better debugging and logging.
• Audit Logging: Sensitive operations are logged for security auditing.

Sunset Middleware

To manage the deprecation of API endpoints over time, Kit includes a Sunset middleware. This middleware can be applied directly to routes with the following parameters:

Route::middleware('sunset:2027-01-01,https://api.acme.com/v2/auth/login,true')
    ->post('/v1/auth/login', LoginController::class);

While the endpoint is active, the middleware appends Deprecation, Sunset, and Link headers to every response, allowing API clients to prepare for changes. Once the sunset date is reached, and enforcement is enabled, the endpoint will return a 410 Gone status.

Documentation Generation

Kit simplifies API documentation with Scribe, generating documentation that adheres to the OpenAPI specification. The documentation setup utilizes attribute-based annotations instead of traditional docblock annotations, streamlining the documentation process.

Localization Support

To cater to a diverse user base, Kit respects the Accept-Language request header and responds with a Content-Language header. The default supported locales are English and Spanish, with translation files located at lang/en/api.php and lang/es/api.php.

Development Tooling

Kit incorporates several tools to enhance the development experience:

• Pest: A testing framework that simplifies the process of writing tests.
• PHPStan: A static analysis tool that helps identify potential issues in the codebase.
• Pint: A code formatting tool that ensures consistent code style.
• Rector: An automated refactoring tool that helps maintain code quality.
• GitHub Actions: CI workflows run tests on every push, apply daily dependency updates, and conduct security scans using composer audit and Gitleaks.

Requirements

To effectively use Kit, developers should ensure their environment meets the following requirements:

• PHP Version: 8.5 or higher.
• Laravel Version: 12 or higher.
• Database: SQLite for local development, with the option to configure other databases.

Conclusion

Kit serves as a powerful starter kit for developers looking to build APIs using Laravel. By providing a structured approach that emphasizes security, versioning, and comprehensive documentation, Kit allows developers to focus on delivering high-quality applications. The integration of modern development tools and practices further enhances the development experience, making it an invaluable resource for both new and seasoned Laravel developers.

Frequently Asked Questions

Note: Provide a strategic conclusion reinforcing long-term business impact and keyword relevance.