Installation Instructions

There are some basic pre-requisites before you can install Flight. Namely you will need to:

Install PHP on your system
Install Composer for the best developer experience.

Basic Install

If you're using Composer, you can run the following command:

composer require flightphp/core

This will only put the Flight core files on your system. You will need to define the project structure, layout, dependencies, configs, autoloading, etc. This method ensures that no other dependencies besides Flight are installed.

You can also download the files directly and extract them to your web directory.

Basic install is perfect for learning, micro APIs, and copy-paste experiments. For a full app layout that humans and AI coding tools can follow the same way, use the recommended skeleton below.

Recommended Install

It is highly recommended to start with the flightphp/skeleton app for any new projects. Installation is a breeze.

composer create-project flightphp/skeleton my-project/
cd my-project/
composer start
# optional sample DB + posts demo
php runway migrate

That step sets up project structure, Composer PSR-4 autoloading, config, and tools like Tracy, Tracy Extensions, and Runway. It also ships root AGENTS.md (and scoped copies under app/) so AI assistants share one layout with you—see AI & developer experience.

What the skeleton gives you

project-root/
├── AGENTS.md              # AI / agent source of truth
├── SECURITY.md            # Security expectations
├── .env.example           # Secrets / deploy overlays (copied to .env)
├── public/index.php       # Web entry only
├── app/
│   ├── config/            # bootstrap, routes, services, config_sample.php
│   ├── Controller/        # App\Controller\*  (PascalCase folder!)
│   ├── Middleware/        # App\Middleware\*
│   ├── Model/             # App\Model\* (ActiveRecord)
│   ├── Utils/             # Config, Env, DatabaseFactory
│   ├── commands/          # Runway CLI commands
│   ├── views/             # Twig templates (*.twig)
│   ├── cache/
│   └── log/
├── migrations/            # SQL migrations (.sql / .mysql.sql)
└── tests/                 # PHPUnit

Namespaces follow folder case. Composer maps "App\\": "app/", so:

Path on disk	Namespace
`app/Controller/HomeController.php`	`App\Controller\HomeController`
`app/Middleware/…`	`App\Middleware\…`
`app/Model/…`	`App\Model\…`
`app/Utils/…`	`App\Utils\…`

On Linux, app/controller/ is not the same as app/Controller/. Autoloading is case-sensitive—match the skeleton’s PascalCase folders. Details: Autoloading.

Stack defaults (new projects): Twig views, SimplePdo + ActiveRecord, Dice with Engine injection (prefer no Flight:: inside app classes), optional SQLite after php runway migrate.

create-project typically copies app/config/config_sample.php → config.php and .env.example → .env when present. Routes live in app/config/routes.php; services and DI live in app/config/services.php.

Docs ↔ skeleton: These docs teach Flight APIs (often with short Flight:: samples). The skeleton fixes application shape. When adding code under app/, follow the skeleton tree; use the docs for method names, options, and plugins.

Configure your Web Server

Built-in PHP Development Server

This is by far the simplest way to get up and running. You can use the built-in server to run your application and even use SQLite for a database (as long as sqlite3 is installed on your system) and not require much of anything! Just run the following command once PHP is installed:

php -S localhost:8000
# or with the skeleton app
composer start

Then open your browser and go to http://localhost:8000.

If you want to make the document root of your project a different directory (Ex: your project is ~/myproject, but your document root is ~/myproject/public/), you can run the following command once your in the ~/myproject directory:

php -S localhost:8000 -t public/
# with the skeleton app, this is already configured
composer start

Then open your browser and go to http://localhost:8000.

Apache

Make sure Apache is already installed on your system. If not, google how to install Apache on your system.

For Apache, edit your .htaccess file with the following:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]

Note: If you need to use flight in a subdirectory add the line RewriteBase /subdir/ just after RewriteEngine On.

Note: If you want to protect all server files, like a db or env file. Put this in your .htaccess file:

RewriteEngine On
RewriteRule ^(.*)$ index.php

Nginx

Make sure Nginx is already installed on your system. If not, google how to install Nginx on your system.

For Nginx, add the following to your server declaration:

server {
  location / {
    try_files $uri $uri/ /index.php;
  }
}

Create your `index.php` file

If you are doing a basic install, you will need to have some code to get you started.

<?php

// If you're using Composer, require the autoloader.
require 'vendor/autoload.php';
// if you're not using Composer, load the framework directly
// require 'flight/Flight.php';

// Then define a route and assign a function to handle the request.
Flight::route('/', function () {
  echo 'hello world!';
});

// Finally, start the framework.
Flight::start();

With the skeleton app, the public entry only boots the app. Routes are registered in app/config/routes.php (typically [App\Controller\…::class, 'method'] so Dice can inject dependencies). Services, Twig, SimplePdo, and the container are wired in app/config/services.php. That structure is intentional so AI tools and humans edit the same places every time.

Installing PHP

If you already have php installed on your system, go ahead and skip these instructions and move to the download section

macOS

Installing PHP using Homebrew

Install Homebrew (if not already installed):

Open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install PHP:
- Install the latest version:
```
brew install php
```
- To install a specific version, for example, PHP 8.1:
```
brew tap shivammathur/php
brew install shivammathur/php/php@8.1
```
Switch between PHP versions:
- Unlink the current version and link the desired version:
```
brew unlink php
brew link --overwrite --force php@8.1
```
- Verify the installed version:
```
php -v
```

Windows 10/11

Installing PHP manually

Download PHP:
- Visit PHP for Windows and download the latest or a specific version (e.g., 7.4, 8.0) as a non-thread-safe zip file.
Extract PHP:
- Extract the downloaded zip file to C:\php.
Add PHP to the system PATH:
- Go to System Properties > Environment Variables.
- Under System variables, find Path and click Edit.
- Add the path C:\php (or wherever you extracted PHP).
- Click OK to close all windows.
Configure PHP:
- Copy php.ini-development to php.ini.
- Edit php.ini to configure PHP as needed (e.g., setting extension_dir, enabling extensions).
Verify PHP installation:
- Open Command Prompt and run:
```
php -v
```

Installing Multiple Versions of PHP

Repeat the above steps for each version, placing each in a separate directory (e.g., C:\php7, C:\php8).
Switch between versions by adjusting the system PATH variable to point to the desired version directory.

Ubuntu (20.04, 22.04, etc.)

Installing PHP using apt

Update package lists:
- Open Terminal and run:
```
sudo apt update
```
Install PHP:
- Install the latest PHP version:
```
sudo apt install php
```
- To install a specific version, for example, PHP 8.1:
```
sudo apt install php8.1
```
Install additional modules (optional):
- For example, to install MySQL support:
```
sudo apt install php8.1-mysql
```
Switch between PHP versions:
- Use update-alternatives:
```
sudo update-alternatives --set php /usr/bin/php8.1
```
Verify the installed version:
- Run:
```
php -v
```

Rocky Linux

Installing PHP using yum/dnf

Enable the EPEL repository:
- Open Terminal and run:
```
sudo dnf install epel-release
```

Install Remi's repository:

Run:

sudo dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm
sudo dnf module reset php

Install PHP:
- To install the default version:
```
sudo dnf install php
```
- To install a specific version, for example, PHP 7.4:
```
sudo dnf module install php:remi-7.4
```

Switch between PHP versions:

Use the dnf module command:

sudo dnf module reset php
sudo dnf module enable php:remi-8.0
sudo dnf install php

Verify the installed version:
- Run:
```
php -v
```

General Notes

For development environments, it's important to configure PHP settings as per your project requirements.
When switching PHP versions, ensure all relevant PHP extensions are installed for the specific version you intend to use.
Restart your web server (Apache, Nginx, etc.) after switching PHP versions or updating configurations to apply changes.