Laravel Skeleton Laravel Package

Getting Started

overtrue/laravel-skeleton is not a library you install into an existing app — it is an opinionated Laravel application template. There is no composer require. Adopt it by starting a new project from it:

composer create-project overtrue/laravel-skeleton my-app
# or, if not on Packagist, clone and install:
git clone https://github.com/overtrue/laravel-skeleton my-app
cd my-app && composer install

Do these in the first 15 minutes, in order:

1. Read composer.json — the require/require-dev split and the php/laravel/framework constraints tell you what version baseline you're inheriting (last tag: Sept 2023, so likely Laravel 10-era; verify).
2. Read README.md — skim for boot instructions and any "removed/changed vs stock Laravel" notes.
3. Open .env.example, docker-compose.yml, and Makefile (if present). These encode the local-environment assumptions better than any docs.
4. Diff app/, config/, routes/ against a fresh laravel new app to see exactly what the skeleton customizes — this diff is your map for everything afterward.
5. Boot it: cp .env.example .env && php artisan key:generate && php artisan migrate && php artisan serve (or ./vendor/bin/sail up / docker compose up if the skeleton ships containers).

First real use case: scaffold a new internal API/service where the skeleton's pre-wired static analysis, code style, CI, and Docker config save you a day of setup. Strip out what you don't need after it boots, not before.

Implementation Patterns

• Fork-and-own, never "use as dependency." Immediately git init fresh history, remove the upstream remote, and make one baseline commit before any customization. That baseline is the reference you diff against when the upstream repo changes.
• Create an internal fork for org defaults. The highest-leverage pattern: fork to yourorg/laravel-skeleton, bake in your CI, Docker service names, Pint/PHPStan configs, base controller/response conventions, and org packages, then composer create-project yourorg/laravel-skeleton for every new service. Tag it (v1, v2) and record which tag each app was created from.
• Cherry-pick upstream. Add git remote add skeleton https://github.com/overtrue/laravel-skeleton and merge/cherry-pick selected improvements rather than trying to sync wholesale.
• Lean on the tooling it ships. Run whatever the skeleton wires up (make test, composer pint, composer analyse, or equivalent scripts) in CI exactly as-is first; customize only after you've confirmed green.
• Extend the skeleton's base classes, don't duplicate them. If it ships base controllers, response helpers, exception handlers, or app/Support utilities, subclass/call into them so your API envelope and error format stay consistent across services.
• Respect its directory conventions. If it imposes structure (e.g. app/Domain, app/Support), document it in your own CONTRIBUTING.md and enforce it with PHPStan/architecture rules rather than fighting it later.

Gotchas and Tips

• There is no upgrade path for a skeleton. composer update won't pull upstream structural changes. Every upstream improvement is a manual diff/merge — budget for it, and keep your baseline commit pristine so the diff stays small.
• Staleness is the main risk. Last release 2023-09-26. Expect to do a Laravel/PHP version bump on day one. Check composer.json constraints, run composer outdated, and plan the framework upgrade before you write business logic.
• create-project vs clone differ. create-project installs a dist and strips VCS metadata; cloning keeps the upstream .git and history. Either way, verify there's no leftover upstream origin before your first commit.
• Audit secrets and CI/Docker assumptions. Check .env.example, docker compose, and .github/workflows for hardcoded credentials, service names, ports, or PHP extensions your machine/CI doesn't have. Makefile targets often assume specific compose service names — confirm before relying on them.
• Dev deps may leak. Ensure nothing in require-dev (debugbar, telescope, ide-helper, faker-driven seeders) is referenced by production bootstrap code. Run composer install --no-dev -o once and boot the app to confirm.
• Debugging odd behavior: when routing, middleware, or error responses behave unexpectedly, diff against a fresh laravel new app of the same major version. Skeleton modifications are usually the cause, and that diff finds them fast.
• Extension points to customize: composer.json scripts, Makefile, pint.json/phpstan.neon, config/, app/Providers, and CI workflows. Never edit vendor/ or Laravel core files.
• Small community (139 stars). Expect limited issue support and sparse docs — you own this thing. Read the last few commits/issues before adopting, and keep the MIT license/attribution if you redistribute your fork.