Instruções de Instalação

Existem alguns pré-requisitos básicos antes de poder instalar o Flight. Nomeadamente, você precisará de:

Instalar PHP no seu sistema
Instalar Composer para a melhor experiência de desenvolvimento.

Instalação Básica

Se você estiver usando o Composer, execute o seguinte comando:

composer require flightphp/core

Isso colocará apenas os arquivos principais do Flight no seu sistema. Você precisará definir a estrutura do projeto, layout, dependências, configurações, autoloading, etc. Este método garante que nenhuma outra dependência além do Flight seja instalada.

Você também pode baixar os arquivos diretamente e extraí-los para o seu diretório web.

A instalação básica é perfeita para aprendizado, micro APIs e experimentos de copiar e colar. Para um layout de aplicativo completo que humanos e ferramentas de codificação de IA possam seguir da mesma forma, use o esqueleto recomendado abaixo.

Instalação Recomendada

É altamente recomendável começar com o aplicativo flightphp/skeleton para qualquer novo projeto. A instalação é muito fácil.

composer create-project flightphp/skeleton my-project/
cd my-project/
composer start
# banco de dados de exemplo opcional + demonstração de posts
php runway migrate

Essa etapa configura a estrutura do projeto, o autoloading PSR-4 do Composer, a configuração e ferramentas como Tracy, Extensões do Tracy e Runway. Ela também inclui o AGENTS.md na raiz (e cópias com escopo em app/) para que os assistentes de IA compartilhem um layout com você — veja IA e experiência de desenvolvimento.

O que o esqueleto oferece

project-root/
├── AGENTS.md              # Fonte de verdade para IA / agente
├── SECURITY.md            # Expectativas de segurança
├── .env.example           # Segredos / overlays de deploy (copiado para .env)
├── public/index.php       # Apenas entrada web
├── app/
│   ├── config/            # bootstrap, rotas, serviços, config_sample.php
│   ├── Controller/        # App\Controller\*  (pasta PascalCase!)
│   ├── Middleware/        # App\Middleware\*
│   ├── Model/             # App\Model\* (ActiveRecord)
│   ├── Utils/             # Config, Env, DatabaseFactory
│   ├── commands/          # Comandos CLI do Runway
│   ├── views/             # Templates Twig (*.twig)
│   ├── cache/
│   └── log/
├── migrations/            # Migrações SQL (.sql / .mysql.sql)
└── tests/                 # PHPUnit

Namespaces seguem o caso das pastas. O Composer mapeia "App\\": "app/", então:

Caminho no disco	Namespace
`app/Controller/HomeController.php`	`App\Controller\HomeController`
`app/Middleware/…`	`App\Middleware\…`
`app/Model/…`	`App\Model\…`
`app/Utils/…`	`App\Utils\…`

No Linux, app/controller/ não é o mesmo que app/Controller/. O autoloading diferencia maiúsculas de minúsculas — corresponda às pastas PascalCase do esqueleto. Detalhes: Autoloading.

Padrões da stack (novos projetos): views Twig, SimplePdo + ActiveRecord, Dice com injeção de Engine (prefira não usar Flight:: dentro das classes do aplicativo), SQLite opcional após php runway migrate.

O create-project normalmente copia app/config/config_sample.php → config.php e .env.example → .env quando presentes. As rotas ficam em app/config/routes.php; serviços e DI (injeção de dependências) ficam em app/config/services.php.

Documentação ↔ esqueleto: Estes documentos ensinam as APIs do Flight (muitas vezes com exemplos curtos de Flight::). O esqueleto define a estrutura do aplicativo. Ao adicionar código em app/, siga a árvore do esqueleto; use a documentação para nomes de métodos, opções e plugins.

Configure seu Servidor Web

Servidor de Desenvolvimento Embutido do PHP

Esta é de longe a maneira mais simples de começar. Você pode usar o servidor embutido para executar seu aplicativo e até mesmo usar SQLite como banco de dados (desde que o sqlite3 esteja instalado no seu sistema) sem precisar de quase nada! Basta executar o seguinte comando assim que o PHP estiver instalado:

php -S localhost:8000
# ou com o aplicativo esqueleto
composer start

Em seguida, abra seu navegador e acesse http://localhost:8000.

Se você quiser definir o diretório raiz de documentos do seu projeto como um diretório diferente (Ex: seu projeto é ~/myproject, mas sua raiz de documentos é ~/myproject/public/), você pode executar o seguinte comando estando no diretório ~/myproject:

php -S localhost:8000 -t public/
# com o aplicativo esqueleto, isso já está configurado
composer start

Em seguida, abra seu navegador e acesse http://localhost:8000.

Apache

Certifique-se de que o Apache já esteja instalado no seu sistema. Se não estiver, pesquise no Google como instalar o Apache no seu sistema.

Para o Apache, edite seu arquivo .htaccess com o seguinte:

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

Nota: Se você precisar usar o Flight em um subdiretório, adicione a linha RewriteBase /subdir/ logo após RewriteEngine On.

Nota: Se você quiser proteger todos os arquivos do servidor, como um arquivo de banco de dados ou env. Coloque isto no seu arquivo .htaccess:

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

Nginx

Certifique-se de que o Nginx já esteja instalado no seu sistema. Se não estiver, pesquise no Google como instalar o Nginx no seu sistema.

Para o Nginx, adicione o seguinte à sua declaração de servidor:

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

Crie seu arquivo `index.php`

Se você estiver fazendo uma instalação básica, precisará de algum código para começar.

<?php

// Se você estiver usando o Composer, requisite o autoloader.
require 'vendor/autoload.php';
// se você não estiver usando o Composer, carregue o framework diretamente
// require 'flight/Flight.php';

// Em seguida, defina uma rota e atribua uma função para lidar com a solicitação.
Flight::route('/', function () {
  echo 'hello world!';
});

// Finalmente, inicie o framework.
Flight::start();

Com o aplicativo esqueleto, a entrada pública apenas inicializa o aplicativo. As rotas são registradas em app/config/routes.php (normalmente [App\Controller\…::class, 'method'] para que o Dice possa injetar dependências). Serviços, Twig, SimplePdo e o contêiner estão conectados em app/config/services.php. Essa estrutura é intencional para que ferramentas de IA e humanos editem os mesmos lugares todas as vezes.

Instalando PHP

Se você já tem php instalado no seu sistema, pode pular estas instruções e ir para a seção de download.

macOS

Instalando o PHP usando Homebrew

Instale o Homebrew (se ainda não estiver instalado):

Abra o Terminal e execute:

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

Instale o PHP:
- Instale a versão mais recente:
```
brew install php
```
- Para instalar uma versão específica, por exemplo, PHP 8.1:
```
brew tap shivammathur/php
brew install shivammathur/php/php@8.1
```
Alterne entre versões do PHP:
- Desvincule a versão atual e vincule a versão desejada:
```
brew unlink php
brew link --overwrite --force php@8.1
```
- Verifique a versão instalada:
```
php -v
```

Windows 10/11

Instalando o PHP manualmente

Baixe o PHP:
- Visite PHP para Windows e baixe a versão mais recente ou uma versão específica (ex.: 7.4, 8.0) como um arquivo zip não thread-safe.
Extraia o PHP:
- Extraia o arquivo zip baixado para C:\php.
Adicione o PHP ao PATH do sistema:
- Vá em Propriedades do Sistema > Variáveis de Ambiente.
- Em Variáveis do sistema, encontre Path e clique em Editar.
- Adicione o caminho C:\php (ou onde você extraiu o PHP).
- Clique em OK para fechar todas as janelas.
Configure o PHP:
- Copie php.ini-development para php.ini.
- Edite o php.ini para configurar o PHP conforme necessário (ex.: definindo extension_dir, habilitando extensões).
Verifique a instalação do PHP:
- Abra o Prompt de Comando e execute:
```
php -v
```

Instalando Múltiplas Versões do PHP

Repita os passos acima para cada versão, colocando cada uma em um diretório separado (ex.: C:\php7, C:\php8).
Alterne entre as versões ajustando a variável PATH do sistema para apontar para o diretório da versão desejada.

Ubuntu (20.04, 22.04, etc.)

Instalando o PHP usando apt

Atualize as listas de pacotes:
- Abra o Terminal e execute:
```
sudo apt update
```
Instale o PHP:
- Instale a versão mais recente do PHP:
```
sudo apt install php
```
- Para instalar uma versão específica, por exemplo, PHP 8.1:
```
sudo apt install php8.1
```
Instale módulos adicionais (opcional):
- Por exemplo, para instalar suporte ao MySQL:
```
sudo apt install php8.1-mysql
```
Alterne entre versões do PHP:
- Use update-alternatives:
```
sudo update-alternatives --set php /usr/bin/php8.1
```
Verifique a versão instalada:
- Execute:
```
php -v
```

Rocky Linux

Instalando o PHP usando yum/dnf

Habilite o repositório EPEL:
- Abra o Terminal e execute:
```
sudo dnf install epel-release
```

Instale o repositório Remi:

Execute:

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

Instale o PHP:
- Para instalar a versão padrão:
```
sudo dnf install php
```
- Para instalar uma versão específica, por exemplo, PHP 7.4:
```
sudo dnf module install php:remi-7.4
```

Alterne entre versões do PHP:

Use o comando de módulo dnf:

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

Verifique a versão instalada:
- Execute:
```
php -v
```

Notas Gerais

Para ambientes de desenvolvimento, é importante configurar as configurações do PHP de acordo com os requisitos do seu projeto.
Ao alternar versões do PHP, certifique-se de que todas as extensões PHP relevantes estejam instaladas para a versão específica que você pretende usar.
Reinicie seu servidor web (Apache, Nginx, etc.) após alternar versões do PHP ou atualizar configurações para aplicar as alterações.