PHPackages                             flightphp/skeleton - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. flightphp/skeleton

ActiveLibrary[HTTP & Networking](/categories/http)

flightphp/skeleton
==================

A Flight PHP framework skeleton app to get your new projects up and running ASAP

v1.3.0(8mo ago)663.0k↓58.5%10MITPHPPHP ^7.4 || ^8.0

Since Jan 9Pushed 1w ago4 watchersCompare

[ Source](https://github.com/flightphp/skeleton)[ Packagist](https://packagist.org/packages/flightphp/skeleton)[ Docs](https://docs.flightphp.com)[ RSS](/packages/flightphp-skeleton/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (10)Dependencies (4)Versions (19)Used By (0)

Flight PHP Skeleton
===================

[](#flight-php-skeleton)

Official starter for [Flight PHP](https://docs.flightphp.com) — a fast, simple, extensible micro-framework.

This repository is what you get from:

```
composer create-project flightphp/skeleton cool-project-name
```

It is built so **you can write every line yourself**, following one clear application pattern, and so **AI coding tools succeed** when you choose to use them. Same codebase either way.

---

Who this is for
---------------

[](#who-this-is-for)

You…Start hereWant to code the app yourself[Quick start](#quick-start) → [How you work day to day](#how-you-work-day-to-day) → [Flight docs ↔ this skeleton](#flight-docs--this-skeleton)Use any AI coding agentSame as above, then [AI-assisted development](#ai-assisted-development), root **`AGENTS.md`**, and **`SECURITY.md`**Are comparing to older Flight demos[Flight docs ↔ this skeleton](#flight-docs--this-skeleton)Flight’s **framework APIs** live in the docs and in `vendor/flightphp/core`. This skeleton’s job is a **default application layout** (folders, DI, config, views, models) so you are not inventing structure on day one.

---

Requirements
------------

[](#requirements)

- PHP 8.1+ recommended (app code stays careful about syntax; some deps such as Runway 1.x need 8.2+)
- Composer
- `ext-json`, `ext-pdo` (`pdo_sqlite` for the default database)

---

Create a project
----------------

[](#create-a-project)

```
composer create-project flightphp/skeleton cool-project-name
cd cool-project-name
```

That step copies `config_sample.php` → `config.php`, `.env.example` → `.env` (when present), creates cache/log dirs, and writes `.runway-config.json` if needed.

---

Quick start
-----------

[](#quick-start)

```
# Optional: edit .env or app/config/config.php
composer start
# → http://localhost:8000

# Sample data (posts table + ActiveRecord example)
php runway migrate
# → http://localhost:8000/posts
# → http://localhost:8000/api/posts
```

### Docker

[](#docker)

```
docker compose up -d
# → http://localhost:8080
```

### Vagrant

[](#vagrant)

```
vagrant up
# → http://localhost:8000
```

---

Project structure
-----------------

[](#project-structure)

```
project-root/
├── README.md             # You are here (humans first)
├── AGENTS.md             # Root AI instructions (source of truth)
├── SECURITY.md           # Security policy (secrets, headers, reporting)
├── .env.example          # Documented env overlays (secrets / deploy)
├── public/index.php      # Web entry only
├── app/
│   ├── config/           # bootstrap, routes, services + AGENTS.md
│   ├── Utils/            # Config, Env, DatabaseFactory + AGENTS.md
│   ├── Controller/       # App\Controller\* + AGENTS.md
│   ├── Middleware/       # App\Middleware\* + AGENTS.md
│   ├── Model/            # App\Model\* + AGENTS.md
│   ├── commands/         # Runway CLI + AGENTS.md
│   ├── views/            # Twig + AGENTS.md
│   ├── cache/
│   └── log/
├── migrations/           # SQL + AGENTS.md
└── tests/                # PHPUnit + AGENTS.md

```

Namespaces are **`App\…`** (PascalCase folders: `Controller`, not `controllers`). Framework code stays **`flight\…`**.

---

How you work day to day
-----------------------

[](#how-you-work-day-to-day)

You do not need an AI tool. The loop is:

1. **Route** — add a line in `app/config/routes.php`
2. **Controller** — class under `app/Controller/` with constructor injection
3. **View or JSON** — Twig under `app/views/`, or `$this->app->json(...)`
4. **Database (optional)** — migration in `migrations/`, model under `app/Model/`, inject `SimplePdo`

### Minimal controller

[](#minimal-controller)

```
namespace App\Controller;

use flight\Engine;

class HelloController
{
    private $app;

    public function __construct(Engine $app)
    {
        $this->app = $app;
    }

    public function index(): void
    {
        $this->app->render('welcome', [
            'message' => 'Hello from a controller',
        ]);
    }
}
```

```
// app/config/routes.php
$router->get('/hello', [HelloController::class, 'index']);
```

Dice builds the controller and injects the **same** `Engine` instance used at boot (see `app/config/services.php`). That matches Flight’s dependency-injection and unit-testing guidance: prefer `$app` / injected services over the static `Flight::` facade in application classes.

### Configuration

[](#configuration)

Three layers:

1. **`.env`** — secrets and deploy overrides (`DB_PASSWORD`, `APP_ENV`, Docker)
2. **`app/config/config.php`** — structured **literal** defaults (safe for `runway config:set`)
3. **Bootstrap merge** — mapped env keys win when set (`App\Utils\Config::mergeEnv`)

TaskWhereLocal defaults / non-secret flags`config.php` or `php runway config:set …`Secrets / production`.env` (gitignored)Read file config`php runway config:get`Do **not** put `$_ENV[...]` expressions inside `config.php`. Runway rewrites that file as static PHP and would bake resolved values (including secrets) into the file.

Full env→config map: **`AGENTS.md`**.

### Useful commands

[](#useful-commands)

CommandPurpose`composer start`PHP built-in server on port 8000`composer test`PHPUnit`composer analyse`PHPStan level 8`composer check`PHPUnit + PHPStan`php runway migrate`Apply migrations for active driver (`.sql` / `.mysql.sql`)`php runway --help`List CLI commands`php runway config:get` / `config:set`File config helpersOnly rely on commands that actually appear in `php runway --help` for your install.

---

Stack (this skeleton’s defaults)
--------------------------------

[](#stack-this-skeletons-defaults)

ConcernChoiceWhy this defaultFramework[flightphp/core](https://docs.flightphp.com) (`Engine`, `SimplePdo`)Long-term Flight APIsDI[Dice](https://docs.flightphp.com/en/v3/learn/dependency-injection-container) + Engine substitutionsTestable controllers; official DI patternViews[Twig](https://twig.symfony.com/)Wide ecosystem; `$app->render()` is mapped to TwigModels[ActiveRecord](https://docs.flightphp.com/awesome-plugins/active-record)One model storyDB connection[`SimplePdo`](https://docs.flightphp.com/en/v3/learn/simple-pdo)Preferred over deprecated PdoWrapperSessions[flightphp/session](https://docs.flightphp.com/awesome-plugins/session)Injectable; avoid raw `$_SESSION`CLI[Runway](https://docs.flightphp.com/awesome-plugins/runway)Migrations + scaffolding hostDebuggerTracy (+ tracy-extensions in dev)Error UX in developmentThese are **deliberate product defaults for the official starter**, not the only way to use Flight. A micro app can still be a single file and `Flight::route()` — that path is documented in core docs / zip installs, not duplicated here.

---

Flight docs ↔ this skeleton
---------------------------

[](#flight-docs--this-skeleton)

Docs teach the **framework**. The skeleton fixes an **application shape** so copy-paste from tutorials does not fight the tree. When they differ, **prefer this repository’s layout for code you add under `app/`**, and use docs for method names, options, and plugins.

TopicDocs often showThis skeleton expectsEntry / demo style`Flight::route(...)`, sometimes one-file`public/index.php` → bootstrap → `routes.php` + controllersApp handle`Flight::…` static facadeInject `flight\Engine $app` in controllers/middleware; bootstrap may still call `Flight::app()`ControllersVarious namespaces / ad hoc classes`App\Controller\…` → `app/Controller/`Routing fileInline in index or mixedAll HTTP routes in `app/config/routes.php`ViewsBuilt-in PHP views, Latte examples, etc.**Twig only** under `app/views/`; `$app->render('name', $data)`Database helperOlder **PdoWrapper** examples still around**`SimplePdo`** (PdoWrapper is deprecated as of core 3.18)ModelsRaw SQL, or ActiveRecord in plugin docsActiveRecord under `App\Model\`; connection is SimplePdoConfigArrays, env snippets, register()Literal `config.php` + `.env` overlay; inject `App\Utils\Config`DIOptional / several containersDice wired in `services.php` with **Engine substitutions**TestingConstruct controller with `new Engine()` + mocksSame idea; see `tests/Unit/` and the [unit testing guide](https://docs.flightphp.com/en/v3/guides/unit-testing)**Reading docs without fighting the skeleton**

1. Learn the API from docs (`request()`, `json()`, `route` patterns, middleware `before`, ActiveRecord methods, SimplePdo helpers).
2. Place new code in this tree (`Controller`, `Middleware`, `Model`, `views`, `routes.php`, `services.php`).
3. Prefer constructor injection over new static `Flight::` calls inside app classes.
4. If a doc example uses `Flight::db()` or `Flight::render()`, the equivalent here is usually injected `SimplePdo` / `$this->app->render()` (render is already mapped to Twig).

**Where docs and skeleton already agree**

Flight’s own [unit testing guide](https://docs.flightphp.com/en/v3/guides/unit-testing) steers away from `Flight::` globals toward `Engine` injection and DI — the same stance this skeleton takes for `app/` code. Short facade examples in learn pages remain valid for quick experiments; they are not the house style for this starter.

**Docs site updates**

Install / structure pages on docs.flightphp.com should stay in sync with this README (especially `App\` namespaces and Twig/SimplePdo defaults) whenever the skeleton ships a breaking layout change. Until then, **this README is the source of truth for create-project layout**.

---

AI-assisted development (optional)
----------------------------------

[](#ai-assisted-development-optional)

Nothing in the runtime requires an AI tool. There is **no create-project question** about which assistant you use.

This repo standardizes on the open **`AGENTS.md`** convention only (no separate Copilot / Cursor / Gemini / Windsurf rule files):

FileRole**[AGENTS.md](AGENTS.md)**Root rules + **routing table** to scoped files**`app/**/AGENTS.md`**, **`migrations/AGENTS.md`**, **`tests/AGENTS.md`**Light, area-specific tips (controllers, Twig, Runway, …) loaded when working in that tree**[SECURITY.md](SECURITY.md)**Secrets, headers, XSS/SQL, reporting — keep security deliberate and separateIf you use an AI assistant:

1. Point it at root **`AGENTS.md`** (and let it follow links to scoped files when editing those folders).
2. Prefer [docs.flightphp.com](https://docs.flightphp.com) and MCP `https://mcp.flightphp.com/mcp`.
3. Verify APIs under `vendor/flightphp/core` — do not invent Flight methods.
4. **Project AGENTS / SECURITY win** over generic training data.
5. After application-code changes: add/update unit tests and run **`composer check`** (PHPUnit + PHPStan level 8).

Hand-written and AI-generated code should look the same: one controller style, one config path, one view layer.

---

First customization checklist
-----------------------------

[](#first-customization-checklist)

1. Add a route in `app/config/routes.php`
2. Add `app/Controller/YourController.php` (constructor injection)
3. Add a Twig template under `app/views/` **or** return JSON from the controller
4. For DB: SQL file in `migrations/` (`.sql` for SQLite, `.mysql.sql` for MySQL), `php runway migrate`, model in `app/Model/`, inject `SimplePdo`
5. After code changes: add/update tests, then run `composer check` (PHPUnit + PHPStan level 8)

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance82

Actively maintained with recent releases

Popularity36

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~41 days

Total

18

Last Release

240d ago

Major Versions

v0.4.3 → v1.0.02025-06-28

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2322095?v=4)[n0nag0n](/maintainers/n0nag0n)[@n0nag0n](https://github.com/n0nag0n)

---

Top Contributors

[![n0nag0n](https://avatars.githubusercontent.com/u/2322095?v=4)](https://github.com/n0nag0n "n0nag0n (59 commits)")[![eydun](https://avatars.githubusercontent.com/u/12867?v=4)](https://github.com/eydun "eydun (1 commits)")[![vlakoff](https://avatars.githubusercontent.com/u/544424?v=4)](https://github.com/vlakoff "vlakoff (1 commits)")

---

Tags

applicationboilerplateflightphpphpskeletonskeleton-applicationrestSimpleboilerplatemicroframeworkSkeletoneasyliterestapi

### Embed Badge

![Health badge](/badges/flightphp-skeleton/health.svg)

```
[![Health](https://phpackages.com/badges/flightphp-skeleton/health.svg)](https://phpackages.com/packages/flightphp-skeleton)
```

###  Alternatives

[peej/tonic

The RESTful Web App PHP Micro-Framework

624149.5k](/packages/peej-tonic)[contributte/api-router

RESTful Router for your Apis in Nette Framework - created either directly or via attributes

20814.8k4](/packages/contributte-api-router)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)