Download the PHP package joelbutcher/laravel-skeleton without Composer

README

An opinionated, coding agent-ready, Laravel 13 application skeleton preconfigured with strict code quality tooling, Octane-ready conventions, and a comprehensive testing pipeline. Use this as a starting point for new Laravel services.

What's Included

Out of the box, the skeleton provides:

• Laravel Octane with FrankenPHP worker — high-performance, long-running process model
• Custom ULID primary keys — App\Support\Ulids\HasUlids trait and UlidCast, enforced over Laravel's built-in implementation
• Brick\DateTime integration — LocalDateCast and LocalDateTimeCast for Eloquent, replacing Carbon entirely
• Five-layer testing pipeline — PHPUnit, Behat BDD, PHPStan (level max), Infection mutation testing, Mago linting
• 100% coverage and mutation score — enforced automatically; builds fail if either drops
• Strict linting — final controllers, identity comparison, strict types, no eval/shell/globals
• Concurrent dev server — single command runs Octane, queue worker, log tailing, and Vite

Tech Stack

Getting Started

Prerequisites

• PHP 8.5+
• Composer
• Node.js and npm
• SQLite

Setup

This runs the full setup sequence: installs PHP and Node dependencies, generates an app key, runs migrations, and builds frontend assets.

Development Server

Starts four processes concurrently:

• server - php artisan serve
• queue - php artisan queue:listen
• logs - php artisan pail (log tailing)
• vite - npm run dev (hot-reload)

Project Structure

Conventions

No Carbon or DateTime

All date/time values use Brick\DateTime\LocalDate or Brick\DateTime\LocalDateTime. Carbon and PHP's DateTime are banned via PHPStan disallowed-namespace rules. Custom Eloquent casts (LocalDateCast, LocalDateTimeCast) handle serialisation.

Custom ULIDs

Use App\Support\Ulids\HasUlids instead of Laravel's built-in HasUlids trait. This is enforced by PHPStan. The custom implementation includes a UlidCast for Eloquent attribute casting.

Octane-Safe Code

The application runs on Laravel Octane, which boots the app once and reuses it across requests:

• Use scoped() instead of singleton() for request-scoped bindings.
• Never inject the container, request, or config repository into a singleton constructor.
• Never append to static properties (they persist across requests).

Mago Linter

PHP linting uses Mago with strict rules:

• Controllers must be final
• Prefer arrow functions and static closures
• Identity comparison required (=== / !==)
• declare(strict_types=1) enforced
• Shell execution, eval, FFI, and globals are prohibited

Testing

Running Tests

Test Strategy

Tests run against in-memory SQLite (phpunit.xml.dist). Behat scenarios bootstrap a full Laravel application with RefreshDatabase.

Coverage Requirements

• 100% code coverage enforced by robiningelbrecht/phpunit-coverage-tools (tests fail on low coverage).
• 100% mutation score enforced by Infection (all mutants must be killed).

Code Quality

composer before-stopping runs the full quality pipeline: unit tests, static analysis, feature tests, mutation testing, formatting, and linting.

Static Analysis

PHPStan runs at level max with:

• Larastan for Laravel-specific analysis
• Octane compatibility checks
• Custom disallowed-namespace rules (enforcing Brick\DateTime and custom ULIDs)
• PSL PHPStan extension for PHP Standard Library

Dependencies

Runtime

Development

Deployment

The application includes a FrankenPHP worker script (public/frankenphp-worker.php) and is configured for Laravel Octane, making it ready for high-performance deployment via Laravel Cloud or containerised environments.

License

This project is licensed under the MIT License.