README

What's Different from the Official Laravel Starter

PHP >=8.4 baseline with declare(strict_types=1) enforced by Pint.
The default boilerplate is lean and backend/API-friendly rather than frontend-scaffold-heavy.
AppServiceProvider comes preconfigured with useful safeguards like immutable dates and stricter Eloquent.
Models are unguarded by default because policing request input is not their job.
Tooling is already wired: Pest (parallel tests), PHPStan + Larastan at max level, and Rector for refactors.
Tinker is intentionally kept in require-dev, not production dependencies, as a safer default.
Improved testing setup with clear conventions and a dedicated suite for external dependencies.
Laravel Boost configuration prompts are included during setup, and sensible .gitignore rules for Boost are preconfigured.
Uses Laravel Boost "best practices" as a baseline, not as an untouchable rulebook; project-owned .ai guidelines are configured to override Boost defaults when you or this starter kit make different choices.
SQLite is set as the default database, offering a clean, minimal starting point that you can easily customize for your preferred database setup.
Formatting is consistent out of the box: Pint for PHP and Prettier for everything else.

Installation

Create application (replace example-app with desired project name):

composer create-project adiachenko/starter-kit-laravel --prefer-dist example-app

Keep in mind that composer create-project already does most of the setup for you. It will install dependencies, create .env file, generate app key, and prompt you to configure Laravel Boost.

Navigate to your project and complete the setup:

cd example-app

# Initialize git repo
git init
sh install-git-hooks.sh

# Optionally, scaffold API routes with Sanctum or Passport (add --passport flag)
php artisan install:api

Installed Git hooks:

pre-commit runs composer format:check
pre-push runs composer analyse

If you use Fork and hooks misbehave, see this issue.

Development Commands

Mutation testing and coverage commands require Xdebug in coverage mode or enabled PCOV.

Command	Purpose
`composer test`	Run Feature and Unit test suites (`pest --compact --parallel`).
`composer test:external`	Run the External test suite (`--testsuite=External`).
`composer format`	Run Laravel Pint and Prettier formatting.
`composer format:check`	Check Laravel Pint and Prettier formatting.
`composer analyse`	Run static analysis (`phpstan`).
`composer refactor`	Apply Rector refactors.
`composer mutate`	Run mutation testing across the app.
`composer mutate:herd`	Run mutation testing via Laravel Herd tooling.
`composer coverage`	Run tests with local coverage (`pest --coverage`).
`composer coverage:herd`	Run coverage via Laravel Herd tooling.

Tests Structure and Conventions

The tests are organized into three test suites:

tests/Feature: default starting point for validating application behavior. Test from the outside in by calling endpoints directly. Organize feature tests in subfolders by interface type: Web, Api, or Mcp for HTTP endpoints, Console for Artisan commands, etc.
tests/Unit: tests for individual classes aligned with app/ namespaces; strict isolation is not required (using database or involving related classes is acceptable).
tests/External: tests real interactions with external services (no mocking), organized by provider or domain.

If unsure, always start with Feature tests and work inward toward Unit tests as complexity grows.

Do not place unmocked external integration checks in Feature or Unit; keep them in tests/External.

Test descriptions should follow the pattern: <verb> <observable outcome> [when <condition>] [for <actor>].

Additional Folders

Not strictly Laravel-official, but adopted as common practices in the community:

app/Actions: invokable classes for encapsulating business logic.
app/Data: data transfer objects (DTOs).
app/Enums: self-explanatory.
app/Services: for calling external services.

Editor Setup (Optional)

Zed

Zed automatically loads the shared settings from .zed/settings.json, whether the repository is opened directly or as part of a parent workspace.

Suggested extensions:

The shared settings don't choose a PHP language server, so configure whichever you like in Zed user settings. PHPantom is a good option.

VSCode/Cursor

When the repo is opened directly, VSCode and Cursor automatically load the shared configuration from .vscode/ and suggest the recommended extensions for installation. However, they do not discover this configuration when the project is opened as part of a larger monorepo. In that case, the parent workspace must provide its own editor configuration.

For PHP language support, install whichever extension you like. PHPantom is a good option.

PhpStorm

Recommended setup for consistent formatting:

Settings | Editor | Code Style: ensure "Enable EditorConfig support" is checked.
Settings | PHP | Quality Tools | Laravel Pint: set "Path to pint.json" to pint.json and select "defined in pint.json" as the ruleset
Settings | PHP | Quality Tools: set Laravel Pint as external formatter
Settings | Tools | Actions on Save: enable reformat on save
Settings | Languages & Frameworks | JavaScript | Prettier: use automatic config, enable "Run on save", and prefer Prettier config. Include md in Prettier file extensions.

When opened from a parent monorepo, configure Laravel Pint to use this repository's vendor/bin/pint and pint.json. PhpStorm applies these settings project-wide, so sibling PHP projects cannot use different Pint rules.

adiachenko / starter-kit-laravel

Maintainers

Package info

Statistics

Security