Icons background left side Icons background left side in dark variant
Um micro-framework extensível para PHP Um micro-framework extensível para PHP
Icons background right side Icons background right side in dark variant

Learn/flight_vs_laravel

Flight vs Laravel

O que é Laravel?

Laravel é um framework completo com todos os recursos e um ecossistema focado em desenvolvedores impressionante, mas a um custo em desempenho e complexidade. O objetivo do Laravel é que o desenvolvedor tenha o mais alto nível de produtividade e torne tarefas comuns fáceis. Laravel é uma ótima escolha para desenvolvedores que desejam construir uma aplicação web completa e empresarial. Isso vem com algumas compensações, especificamente em termos de desempenho e complexidade. Aprender os conceitos iniciais do Laravel pode ser fácil, mas ganhar proficiência no framework pode levar algum tempo.

Há também tantos módulos do Laravel que os desenvolvedores frequentemente sentem que a única maneira de resolver problemas é por meio desses módulos, quando na verdade você poderia simplesmente usar outra biblioteca ou escrever seu próprio código.

Prós em comparação com Flight

Contras em comparação com Flight

Learn/migrating_to_v3

Migração para a v3

A compatibilidade retroativa foi mantida na maior parte, mas há algumas alterações das quais você deve estar ciente ao migrar da v2 para a v3. Há algumas mudanças que conflitaram demais com padrões de design, então alguns ajustes tiveram que ser feitos.

Comportamento de Buffer de Saída

v3.5.0

Output buffering é o processo onde a saída gerada por um script PHP é armazenada em um buffer (interno ao PHP) antes de ser enviada ao cliente. Isso permite que você modifique a saída antes de ela ser enviada ao cliente.

Em uma aplicação MVC, o Controller é o "gerenciador" e ele gerencia o que a view faz. Ter saída gerada fora do controller (ou no caso do Flight, às vezes uma função anônima) quebra o padrão MVC. Essa mudança é para estar mais alinhada com o padrão MVC e tornar o framework mais previsível e fácil de usar.

Na v2, o output buffering era tratado de uma forma onde não fechava consistentemente seu próprio buffer de saída, o que tornava testes unitários e streaming mais difíceis. Para a maioria dos usuários, essa mudança pode não afetá-lo de fato. No entanto, se você estiver ecoando conteúdo fora de callables e controllers (por exemplo, em um hook), você provavelmente vai encontrar problemas. Ecoar conteúdo em hooks, e antes do framework realmente executar, pode ter funcionado no passado, mas não funcionará daqui para frente.

Onde você pode ter problemas

// index.php
require 'vendor/autoload.php';

// apenas um exemplo
define('START_TIME', microtime(true));

function hello() {
    echo 'Hello World';
}

Flight::map('hello', 'hello');
Flight::after('hello', function(){
    // isso na verdade estará bem
    echo '<p>This Hello World phrase was brought to you by the letter "H"</p>';
});

Flight::before('start', function(){
    // coisas como essa causarão um erro
    echo '<html><head><title>My Page</title></head><body>';
});

Flight::route('/', function(){
    // isso na verdade está apenas bem
    echo 'Hello World';

    // Isso também deve estar bem
    Flight::hello();
});

Flight::after('start', function(){
    // isso causará um erro
    echo '<div>Your page loaded in '.(microtime(true) - START_TIME).' seconds</div></body></html>';
});

Ativando o Comportamento de Renderização da v2

Você ainda pode manter seu código antigo como está sem fazer uma reescrita para torná-lo compatível com a v3? Sim, você pode! Você pode ativar o comportamento de renderização da v2 definindo a opção de configuração flight.v2.output_buffering como true. Isso permitirá que você continue a usar o antigo comportamento de renderização, mas é recomendado corrigi-lo daqui para frente. Na v4 do framework, isso será removido.

// index.php
require 'vendor/autoload.php';

Flight::set('flight.v2.output_buffering', true);

Flight::before('start', function(){
    // Agora isso estará bem
    echo '<html><head><title>My Page</title></head><body>';
});

// mais código

Mudanças no Dispatcher

v3.7.0

Se você tiver chamado diretamente métodos estáticos para Dispatcher, como Dispatcher::invokeMethod(), Dispatcher::execute(), etc. você precisará atualizar seu código para não chamar diretamente esses métodos. O Dispatcher foi convertido para ser mais orientado a objetos, de modo que Contêineres de Injeção de Dependência possam ser usados de forma mais fácil. Se você precisar invocar um método de forma similar ao que o Dispatcher fazia, você pode usar manualmente algo como $result = $class->$method(...$params); ou call_user_func_array() em vez disso.

Mudanças em halt() stop() redirect() e error()

v3.10.0

O comportamento padrão antes da 3.10.0 era limpar tanto os headers quanto o corpo da resposta. Isso foi alterado para limpar apenas o corpo da resposta. Se você precisar limpar os headers também, você pode usar Flight::response()->clear().

Learn/configuration

Configuração

Visão Geral

Flight fornece uma maneira simples de configurar vários aspectos do framework para atender às necessidades da sua aplicação. Alguns são definidos por padrão, mas você pode sobrescrevê-los conforme necessário. Você também pode definir suas próprias variáveis para serem usadas em toda a sua aplicação.

Compreendendo

Você pode personalizar certos comportamentos do Flight definindo valores de configuração por meio do método set.

Flight::set('flight.log_errors', true);

No arquivo app/config/config.php, você pode ver todas as variáveis de configuração padrão disponíveis para você.

Uso Básico

Opções de Configuração do Flight

A seguir, uma lista de todas as configurações disponíveis:

Configuração do Loader

Há adicionalmente outra configuração para o loader. Isso permitirá que você carregue classes automaticamente com _ no nome da classe.

// Ativa o carregamento de classes com underscores
// Padrão: true
Loader::$v2ClassLoading = false;

Variáveis

Flight permite que você salve variáveis para que elas possam ser usadas em qualquer lugar da sua aplicação.

// Salva sua variável
Flight::set('id', 123);

// Em outro lugar da sua aplicação
$id = Flight::get('id');

Para ver se uma variável foi definida, você pode fazer:

if (Flight::has('id')) {
  // Faça algo
}

Você pode limpar uma variável fazendo:

// Limpa a variável id
Flight::clear('id');

// Limpa todas as variáveis
Flight::clear();

Nota: Apenas porque você pode definir uma variável não significa que você deva. Use este recurso com moderação. O motivo é que qualquer coisa armazenada aqui se torna uma variável global. Variáveis globais são ruins porque podem ser alteradas de qualquer lugar na sua aplicação, tornando difícil rastrear bugs. Além disso, isso pode complicar coisas como testes unitários.

Erros e Exceções

Todos os erros e exceções são capturados pelo Flight e passados para o método error. se flight.handle_errors estiver definido como true.

O comportamento padrão é enviar uma resposta genérica HTTP 500 Internal Server Error com algumas informações de erro.

Você pode sobrescrever este comportamento para suas próprias necessidades:

Flight::map('error', function (Throwable $error) {
  // Lida com o erro
  echo $error->getTraceAsString();
});

Por padrão, os erros não são registrados no servidor web. Você pode ativar isso alterando a configuração:

Flight::set('flight.log_errors', true);

404 Não Encontrado

Quando uma URL não pode ser encontrada, o Flight chama o método notFound. O comportamento padrão é enviar uma resposta HTTP 404 Not Found com uma mensagem simples.

Você pode sobrescrever este comportamento para suas próprias necessidades:

Flight::map('notFound', function () {
  // Lida com não encontrado
});

Veja Também

Solução de Problemas

Registro de Alterações

Learn/ai

IA & Experiência do Desenvolvedor com Flight

Visão Geral

Flight facilita o superpoder de seus projetos PHP com ferramentas alimentadas por IA e fluxos de trabalho modernos para desenvolvedores. Com comandos integrados para conectar a provedores de LLM (Large Language Model) e gerar instruções de codificação específicas do projeto alimentadas por IA, Flight ajuda você e sua equipe a tirar o máximo de assistentes de IA como GitHub Copilot, Cursor e Windsurf.

Entendendo

Assistentes de codificação de IA são mais úteis quando entendem o contexto, convenções e objetivos do seu projeto. Os ajudantes de IA do Flight permitem que você:

Esses recursos estão integrados ao CLI principal do Flight e ao projeto inicial oficial flightphp/skeleton.

Uso Básico

Configurando Credenciais de LLM

O comando ai:init o guia na conexão do seu projeto a um provedor de LLM.

php runway ai:init

Você será solicitado a:

Isso cria um arquivo .runway-creds.json na raiz do seu projeto (e garante que ele esteja no seu .gitignore).

Exemplo:

Bem-vindo ao AI Init!
Qual API de LLM você deseja usar? [1] openai, [2] grok, [3] claude: 1
Insira a URL base para a API de LLM [https://api.openai.com]:
Insira sua chave de API para openai: sk-...
Insira o nome do modelo que você deseja usar (ex. gpt-4, claude-3-opus, etc) [gpt-4o]:
Credenciais salvas em .runway-creds.json

Gerando Instruções Específicas do Projeto para IA

O comando ai:generate-instructions ajuda você a criar ou atualizar instruções para assistentes de codificação de IA, adaptadas ao seu projeto.

php runway ai:generate-instructions

Você responderá a algumas perguntas sobre seu projeto (descrição, banco de dados, templating, segurança, tamanho da equipe, etc.). Flight usa seu provedor de LLM para gerar instruções, depois as escreve em:

Exemplo:

Por favor, descreva para que serve seu projeto? Minha API incrível
Qual banco de dados você planeja usar? MySQL
Qual engine de templating HTML você planeja usar (se houver)? latte
A segurança é um elemento importante deste projeto? (y/n) y
...
Instruções de IA atualizadas com sucesso.

Agora, suas ferramentas de IA darão sugestões mais inteligentes e relevantes com base nas necessidades reais do seu projeto.

Uso Avançado

Veja Também

Solução de Problemas

Changelog

Learn/unit_testing_and_solid_principles

Este artigo foi originalmente publicado no Airpair em 2015. Todo o crédito é dado ao Airpair e a Brian Fenton, que originalmente escreveu este artigo, embora o site não esteja mais disponível e o artigo só exista dentro da Wayback Machine. Este artigo foi adicionado ao site para fins de aprendizado e educacionais para a comunidade PHP em geral.

1 Configuração e instalação

1.1 Mantenha atualizado

Vamos destacar isso desde o início - um número deprimentemente pequeno de instalações de PHP no mundo real está atualizado ou mantido atualizado. Seja devido a restrições de hospedagem compartilhada, padrões que ninguém pensa em alterar, ou falta de tempo/orçamento para testes de atualização, os humildes binários do PHP tendem a ficar para trás. Então, uma prática recomendada clara que precisa de mais ênfase é sempre usar uma versão atual do PHP (5.6.x conforme este artigo). Além disso, é importante agendar atualizações regulares tanto do PHP quanto de quaisquer extensões ou bibliotecas de fornecedores que você possa estar usando. As atualizações trazem novos recursos de linguagem, velocidade aprimorada, menor uso de memória e atualizações de segurança. Quanto mais frequentemente você atualizar, menos doloroso o processo se torna.

1.2 Defina padrões sensíveis

O PHP faz um trabalho decente ao definir bons padrões fora da caixa com seus arquivos php.ini.development e php.ini.production, mas podemos fazer melhor. Por exemplo, eles não definem uma data/horário para nós. Isso faz sentido do ponto de vista de distribuição, mas sem um, o PHP lançará um erro E_WARNING toda vez que chamarmos uma função relacionada a data/hora. Aqui estão algumas configurações recomendadas:

1.3 Extensões

Também é uma boa ideia desabilitar (ou pelo menos não habilitar) extensões que você não vai usar, como drivers de banco de dados. Para ver o que está habilitado, execute o comando phpinfo() ou vá para uma linha de comando e execute isso.

$ php -i

As informações são as mesmas, mas phpinfo() adiciona formatação HTML. A versão CLI é mais fácil de redirecionar para grep para encontrar informações específicas. Ex.

$ php -i | grep error_log

Uma ressalva desse método: é possível ter configurações diferentes do PHP aplicadas à versão voltada para a web e à versão CLI.

2 Use Composer

Isso pode surpreender, mas uma das melhores práticas para escrever PHP moderno é escrever menos dele. Embora seja verdade que uma das melhores maneiras de se tornar bom em programação é fazer isso, há um grande número de problemas que já foram resolvidos no espaço PHP, como roteamento, bibliotecas básicas de validação de entrada, conversão de unidades, camadas de abstração de banco de dados, etc... Basta ir para Packagist e navegar. Você provavelmente descobrirá que partes significativas do problema que você está tentando resolver já foram escritas e testadas.

Embora seja tentador escrever todo o código você mesmo (e não há nada de errado em escrever seu próprio framework ou biblioteca como uma experiência de aprendizado), você deve lutar contra esses sentimentos de "Não Inventado Aqui" e se poupar de muito tempo e dor de cabeça. Siga a doutrina do PIE em vez disso - Orgulhosamente Inventado Em Outro Lugar. Além disso, se você escolher escrever seu próprio algo, não o libere a menos que ele faça algo significativamente diferente ou melhor do que as ofertas existentes.

Composer é um gerenciador de pacotes para PHP, semelhante ao pip no Python, gem no Ruby e npm no Node. Ele permite que você defina um arquivo JSON que lista as dependências do seu código e tentará resolver esses requisitos para você, baixando e instalando os pacotes de código necessários.

2.1 Instalando Composer

Estamos assumindo que isso é um projeto local, então vamos instalar uma instância do Composer apenas para o projeto atual. Navegue para o diretório do seu projeto e execute isso:

$ curl -sS https://getcomposer.org/installer | php

Lembre-se de que direcionar qualquer download diretamente para um interpretador de script (sh, ruby, php, etc...) é um risco de segurança, então leia o código de instalação e garanta que você esteja confortável com ele antes de executar qualquer comando como esse.

Por conveniência (se você preferir digitar composer install em vez de php composer.phar install), você pode usar este comando para instalar uma cópia única do composer globalmente:

$ mv composer.phar /usr/local/bin/composer
$ chmod +x composer

Você pode precisar executar esses com sudo, dependendo das suas permissões de arquivo.

2.2 Usando Composer

O Composer tem duas categorias principais de dependências que ele pode gerenciar: "require" e "require-dev". Dependências listadas como "require" são instaladas em todos os lugares, mas dependências "require-dev" são instaladas apenas quando solicitadas especificamente. Geralmente, essas são ferramentas para quando o código está em desenvolvimento ativo, como PHP_CodeSniffer. A linha abaixo mostra um exemplo de como instalar Guzzle, uma biblioteca HTTP popular.

$ php composer.phar require guzzle/guzzle

Para instalar uma ferramenta apenas para fins de desenvolvimento, adicione a flag --dev:

$ php composer.phar require --dev 'sebastian/phpcpd'

Isso instala PHP Copy-Paste Detector, outra ferramenta de qualidade de código como uma dependência apenas para desenvolvimento.

2.3 Install vs update

Quando executamos composer install pela primeira vez, ele instalará quaisquer bibliotecas e suas dependências de que precisamos, com base no arquivo composer.json. Quando isso é feito, o composer cria um arquivo de bloqueio, previsivelmente chamado composer.lock. Esse arquivo contém uma lista das dependências que o composer encontrou para nós e suas versões exatas, com hashes. Então, qualquer vez futura que executarmos composer install, ele olhará no arquivo de bloqueio e instalará aquelas versões exatas.

composer update é um pouco diferente. Ele ignorará o arquivo composer.lock (se presente) e tentará encontrar as versões mais atualizadas de cada uma das dependências que ainda satisfazem as restrições em composer.json. Ele então escreve um novo composer.lock quando terminar.

2.4 Autoload

Tanto o composer install quanto o composer update gerarão um autoloader para nós que diz ao PHP onde encontrar todos os arquivos necessários para usar as bibliotecas que acabamos de instalar. Para usá-lo, basta adicionar esta linha (geralmente a um arquivo de bootstrap que é executado em cada solicitação):

require 'vendor/autoload.php';

3 Siga bons princípios de design

3.1 SOLID

SOLID é um mnemônico para nos lembrar de cinco princípios-chave no bom design de software orientado a objetos.

3.1.1 S - Princípio da Responsabilidade Única

Isso afirma que as classes devem ter apenas uma responsabilidade, ou dito de outra forma, elas devem ter apenas um motivo para mudar. Isso se encaixa bem com a filosofia Unix de muitas ferramentas pequenas, fazendo uma coisa bem. Classes que fazem apenas uma coisa são muito mais fáceis de testar e depurar, e menos propensas a surpreendê-lo. Você não quer que uma chamada de método para uma classe Validator atualize registros no banco de dados. Aqui está um exemplo de violação de SRP, do tipo que você veria comumente em um aplicativo baseado no padrão ActiveRecord.

class Person extends Model
{
    public $name;
    public $birthDate;
    protected $preferences;
    public function getPreferences() {}
    public function save() {}
}

Então isso é um modelo de entidade bastante básico. No entanto, uma dessas coisas não pertence aqui. A única responsabilidade de um modelo de entidade deve ser o comportamento relacionado à entidade que ele representa; ele não deve ser responsável por persistir a si mesmo.

class Person extends Model
{
    public $name;
    public $birthDate;
    protected $preferences;
    public function getPreferences() {}
}
class DataStore
{
    public function save(Model $model) {}
}

Isso é melhor. O modelo Person está de volta a fazer apenas uma coisa, e o comportamento de salvamento foi movido para um objeto de persistência. Observe também que eu só adicionei um type hint em Model, não em Person. Voltaremos a isso quando chegarmos às partes L e D do SOLID.

3.1.2 O - Princípio Aberto/Fechado

Há um teste incrível para isso que resume bem o que esse princípio é: pense em um recurso para implementar, provavelmente o mais recente que você trabalhou ou está trabalhando. Você pode implementar esse recurso no seu código existente APENAS adicionando novas classes e não alterando nenhuma classe existente no seu sistema? Sua configuração e código de fiação recebem um pouco de perdão, mas na maioria dos sistemas isso é surpreendentemente difícil. Você tem que depender muito de despacho polimórfico e a maioria dos códigos não está configurada para isso. Se você estiver interessado nisso, há uma boa palestra do Google no YouTube sobre polimorfismo e escrever código sem Ifs que aprofunda isso. Como bônus, a palestra é dada por Miško Hevery, que muitos podem conhecer como o criador do AngularJs.

3.1.3 L - Princípio da Substituição de Liskov

Esse princípio é nomeado para Barbara Liskov e é impresso abaixo:

"Objetos em um programa devem ser substituíveis por instâncias de seus subtipos sem alterar a correção desse programa."

Isso parece bom, mas é mais claramente ilustrado com um exemplo.

abstract class Shape
{
    public function getHeight();
    public function setHeight($height);
    public function getLength();
    public function setLength($length);
}

Isso vai representar nossa forma básica de quatro lados. Nada chique aqui.

class Square extends Shape
{
    protected $size;
    public function getHeight() {
        return $this->size;
    }
    public function setHeight($height) {
        $this->size = $height;
    }
    public function getLength() {
        return $this->size;
    }
    public function setLength($length) {
        $this->size = $length;
    }
}

Aqui está nossa primeira forma, o Quadrado. Uma forma bem direta, certo? Você pode assumir que há um construtor onde definimos as dimensões, mas você vê aqui desta implementação que o comprimento e a altura sempre serão os mesmos. Quadrados são assim.

class Rectangle extends Shape
{
    protected $height;
    protected $length;
    public function getHeight() {
        return $this->height;
    }
    public function setHeight($height) {
        $this->height = $height;
    }
    public function getLength() {
        return $this->length;
    }
    public function setLength($length) {
        $this->length = $length;
    }
}

Então aqui temos uma forma diferente. Ainda tem as mesmas assinaturas de método, ainda é uma forma de quatro lados, mas e se começarmos a tentar usá-las no lugar uma da outra? Agora, de repente, se mudarmos a altura da nossa Shape, não podemos mais assumir que o comprimento da nossa forma corresponderá. Violamos o contrato que tínhamos com o usuário quando demos a eles nossa forma Quadrado.

Isso é um exemplo clássico de violação do LSP e precisamos desse tipo de princípio para fazer o melhor uso de um sistema de tipos. Até mesmo o duck typing não nos dirá se o comportamento subjacente é diferente, e como não podemos saber isso sem vê-lo quebrar, é melhor garantir que não seja diferente em primeiro lugar.

3.1.3 I - Princípio da Segregação de Interface

Esse princípio diz para favorecer muitas interfaces pequenas e refinadas em vez de uma grande. Interfaces devem ser baseadas em comportamento em vez de "é uma dessas classes". Pense nas interfaces que vêm com o PHP. Traversable, Countable, Serializable, coisas assim. Elas anunciam capacidades que o objeto possui, não o que ele herda. Então, mantenha suas interfaces pequenas. Você não quer uma interface com 30 métodos, 3 é uma meta muito melhor.

3.1.4 D - Princípio da Inversão de Dependência

Você provavelmente ouviu falar disso em outros lugares que falaram sobre Injeção de Dependência, mas Inversão de Dependência e Injeção de Dependência não são exatamente a mesma coisa. Inversão de dependência é realmente apenas uma forma de dizer que você deve depender de abstrações no seu sistema e não dos seus detalhes. O que isso significa para você no dia a dia?

Não use diretamente mysqli_query() em todo o seu código, use algo como DataStore->query() em vez disso.

O cerne desse princípio é sobre abstrações. É mais sobre dizer "use um adaptador de banco de dados" em vez de depender de chamadas diretas a coisas como mysqli_query. Se você está usando mysqli_query diretamente em metade das suas classes, você está amarrando tudo diretamente ao seu banco de dados. Nada contra o MySQL aqui, mas se você está usando mysqli_query, esse tipo de detalhe de baixo nível deve ser escondido em apenas um lugar e então essa funcionalidade deve ser exposta via um wrapper genérico.

Agora eu sei que isso é um exemplo um pouco batido se você pensar sobre isso, porque o número de vezes que você vai realmente mudar completamente o motor do seu banco de dados após o produto estar em produção é muito, muito baixo. Eu escolhi isso porque imaginei que as pessoas estariam familiarizadas com a ideia do seu próprio código. Além disso, mesmo se você tiver um banco de dados que sabe que vai manter, esse objeto wrapper abstrato permite que você corrija bugs, mude o comportamento ou implemente recursos que você deseja que o seu banco de dados escolhido tivesse. Ele também torna o teste unitário possível onde chamadas de baixo nível não o fariam.

4 Calistenia de objetos

Isso não é um mergulho completo nesses princípios, mas os dois primeiros são fáceis de lembrar, fornecem bom valor e podem ser aplicados imediatamente a praticamente qualquer base de código.

4.1 Não mais que um nível de indentação por método

Isso é uma forma útil de pensar sobre decompor métodos em pedaços menores, deixando você com código que é mais claro e autodocumentado. Quanto mais níveis de indentação você tiver, mais o método está fazendo e mais estado você tem que rastrear na sua cabeça enquanto trabalha com ele.

Logo de cara eu sei que as pessoas vão objetar a isso, mas isso é apenas uma diretriz/heurística, não uma regra rígida e rápida. Eu não espero que ninguém imponha regras do PHP_CodeSniffer para isso (embora pessoas tenham).

Vamos passar por uma amostra rápida do que isso pode parecer:

public function transformToCsv($data)
{
    $csvLines = array();
    $csvLines[] = implode(',', array_keys($data[0]));
    foreach ($data as $row) {
        if (!$row) {
            continue;
        }
        $csvLines[] = implode(',', $row);
    }
    return $csvLines;
}

Embora isso não seja um código terrível (é tecnicamente correto, testável, etc...), podemos fazer muito mais para torná-lo claro. Como reduzir os níveis de aninhamento aqui?

Sabemos que precisamos simplificar muito o conteúdo do loop foreach (ou removê-lo completamente), então vamos começar aí.

if (!$row) {
    continue;
}

Essa primeira parte é fácil. Tudo o que isso está fazendo é ignorar linhas vazias. Podemos encurtar esse processo inteiro usando uma função integrada do PHP antes de chegarmos ao loop.

$data = array_filter($data);
foreach ($data as $row) {
    $csvLines[] = implode(',', $row);
}

Agora temos nosso único nível de aninhamento. Mas olhando para isso, tudo o que estamos fazendo é aplicar uma função a cada item em um array. Nós nem precisamos do loop foreach para fazer isso.

$data = array_filter($data);
$csvLines = array_map(function($row) {
    return implode(',', $row);
}, $data);

Agora não temos aninhamento algum, e o código provavelmente será mais rápido, pois estamos fazendo todo o looping com funções nativas em C em vez de PHP. Temos que nos envolver um pouco para passar a vírgula para implode, então você poderia argumentar que parar no passo anterior é muito mais compreensível.

4.2 Tente não usar else

Isso realmente lida com duas ideias principais. A primeira é múltiplos statements de return de um método. Se você tiver informações suficientes para tomar uma decisão sobre o resultado do método, vá em frente e tome essa decisão e retorne. A segunda é uma ideia conhecida como Guard Clauses. Essas são basicamente verificações de validação combinadas com retornos iniciais, geralmente perto do topo de um método. Deixe-me mostrar o que quero dizer.

public function addThreeInts($first, $second, $third) {
    if (is_int($first)) {
        if (is_int($second)) {
            if (is_int($third)) {
                $sum = $first + $second + $third;
            } else {
                return null;
            }
        } else {
            return null;
        }
    } else {
        return null;
    }
    return $sum;
}

Então isso é bem direto novamente, ele adiciona 3 ints juntos e retorna o resultado, ou null se qualquer dos parâmetros não for um inteiro. Ignorando o fato de que podemos combinar todas essas verificações em uma única linha com operadores AND, acho que você pode ver como a estrutura if/else aninhada torna o código mais difícil de seguir. Agora olhe para este exemplo em vez disso.

public function addThreeInts($first, $second, $third) {
    if (!is_int($first)) {
        return null;
    }
    if (!is_int($second)) {
        return null;
    }
    if (!is_int($third)) {
        return null;
    }
    return $first + $second + $third;
}

Para mim, esse exemplo é muito mais fácil de seguir. Aqui estamos usando cláusulas de guarda para verificar nossas asserções iniciais sobre os parâmetros que estamos passando e saindo imediatamente do método se eles não passarem. Também não temos mais a variável intermediária para rastrear a soma o caminho todo pelo método. Nesse caso, verificamos que já estamos no caminho feliz e podemos apenas fazer o que viemos aqui para fazer. Novamente, podemos fazer todas essas verificações em um único if, mas o princípio deve estar claro.

5 Testes unitários

Testes unitários é a prática de escrever testes pequenos que verificam o comportamento no seu código. Eles são quase sempre escritos na mesma linguagem que o código (nesse caso PHP) e são destinados a ser rápidos o suficiente para rodar a qualquer momento. Eles são extremamente valiosos como uma ferramenta para melhorar o seu código. Além dos benefícios óbvios de garantir que o seu código esteja fazendo o que você acha que está, testes unitários podem fornecer feedback de design muito útil também. Se um pedaço de código é difícil de testar, isso frequentemente destaca problemas de design. Eles também dão a você uma rede de segurança contra regressões e isso permite que você refatore muito mais frequentemente e evolua o seu código para um design mais limpo.

5.1 Ferramentas

Há várias ferramentas de testes unitários por aí no PHP, mas de longe a mais comum é PHPUnit. Você pode instalá-lo baixando um PHAR diretamente, ou instalá-lo com composer. Como estamos usando composer para tudo mais, vamos mostrar esse método. Além disso, como o PHPUnit provavelmente não vai ser implantado para produção, podemos instalá-lo como uma dependência de desenvolvimento com o seguinte comando:

composer require --dev phpunit/phpunit

5.2 Testes são uma especificação

O papel mais importante dos testes unitários no seu código é fornecer uma especificação executável do que o código é suposto fazer. Mesmo se o código de teste estiver errado ou o código tiver bugs, o conhecimento do que o sistema é suposto fazer é inestimável.

5.3 Escreva seus testes primeiro

Se você teve a chance de ver um conjunto de testes escrito antes do código e um escrito após o código ter sido finalizado, eles são notavelmente diferentes. Os testes "após" são muito mais preocupados com os detalhes de implementação da classe e garantindo que tenham boa cobertura de linhas, enquanto os testes "antes" são mais sobre verificar o comportamento externo desejado. Isso é realmente o que nos importa com testes unitários de qualquer maneira, é garantir que a classe exiba o comportamento certo. Testes focados na implementação na verdade tornam o refatoramento mais difícil porque eles quebram se os internos das classes mudarem e você acabou de se custar os benefícios de ocultação de informação da POO.

5.4 O que faz um bom teste unitário

Bons testes unitários compartilham muitas das seguintes características:

Há razões para ir contra algumas dessas, mas como diretrizes gerais elas vão servir bem a você.

5.5 Quando testar é doloroso

Testes unitários forçam você a sentir a dor do mau design no início - Michael Feathers

Quando você está escrevendo testes unitários, você está forçando a si mesmo a realmente usar a classe para realizar coisas. Se você escrever testes no final, ou pior, apenas jogar o código por cima do muro para QA ou quem quer que escreva testes, você não obtém nenhum feedback sobre como a classe realmente se comporta. Se estamos escrevendo testes e a classe é um saco de usar, vamos descobrir enquanto estamos escrevendo, o que é quase o momento mais barato para consertar.

Se uma classe é difícil de testar, é um defeito de design. Diferentes defeitos se manifestam de maneiras diferentes, no entanto. Se você tiver que fazer um monte de mocking, sua classe provavelmente tem muitas dependências ou seus métodos estão fazendo muito. Quanto mais configuração você tiver que fazer para cada teste, mais provável é que seus métodos estejam fazendo muito. Se você tiver que escrever cenários de teste realmente complicados para exercer o comportamento, os métodos da classe provavelmente estão fazendo muito. Se você tiver que cavar dentro de um monte de métodos privados e estado para testar coisas, talvez haja outra classe tentando sair. Testes unitários são muito bons em expor "classes iceberg" onde 80% do que a classe faz está escondido em código protegido ou privado. Eu costumava ser um grande fã de tornar o máximo possível protegido, mas agora percebi que eu estava apenas tornando minhas classes individuais responsáveis por muito, e a solução real era quebrar a classe em pedaços menores.

Escrito por Brian Fenton - Brian Fenton tem sido um desenvolvedor PHP por 8 anos no Meio-Oeste e na Baía, atualmente na Thismoment. Ele se concentra em artesanato de código e princípios de design. Blog em www.brianfenton.us, Twitter em @brianfenton. Quando ele não está ocupado sendo pai, ele gosta de comida, cerveja, jogos e aprendizado.

Learn/security

Segurança

Visão Geral

A segurança é uma grande preocupação quando se trata de aplicações web. Você quer garantir que sua aplicação esteja segura e que os dados dos seus usuários estejam seguros. Flight fornece uma série de recursos para ajudá-lo a proteger suas aplicações web.

Entendendo

Existem várias ameaças de segurança comuns das quais você deve estar ciente ao construir aplicações web. Algumas das ameaças mais comuns incluem:

Templates ajudam com XSS escapando a saída por padrão, para que você não precise se lembrar de fazer isso. Sessions podem ajudar com CSRF armazenando um token CSRF na sessão do usuário, conforme descrito abaixo. Usar declarações preparadas com PDO pode ajudar a prevenir ataques de injeção SQL (ou usando métodos úteis na classe PdoWrapper). CORS pode ser tratado com um gancho simples antes de Flight::start() ser chamado.

Todos esses métodos trabalham juntos para ajudar a manter suas aplicações web seguras. Deve sempre estar na vanguarda da sua mente aprender e entender as melhores práticas de segurança.

Uso Básico

Cabeçalhos

Os cabeçalhos HTTP são uma das maneiras mais fáceis de proteger suas aplicações web. Você pode usar cabeçalhos para prevenir clickjacking, XSS e outros ataques. Existem várias maneiras de adicionar esses cabeçalhos à sua aplicação.

Dois ótimos sites para verificar a segurança dos seus cabeçalhos são securityheaders.com e observatory.mozilla.org. Após configurar o código abaixo, você pode facilmente verificar se seus cabeçalhos estão funcionando com esses dois sites.

Adicionar Manualmente

Você pode adicionar esses cabeçalhos manualmente usando o método header no objeto Flight\Response.

// Define o cabeçalho X-Frame-Options para prevenir clickjacking
Flight::response()->header('X-Frame-Options', 'SAMEORIGIN');

// Define o cabeçalho Content-Security-Policy para prevenir XSS
// Nota: este cabeçalho pode ficar muito complexo, então você vai querer
//  consultar exemplos na internet para sua aplicação
Flight::response()->header("Content-Security-Policy", "default-src 'self'");

// Define o cabeçalho X-XSS-Protection para prevenir XSS
Flight::response()->header('X-XSS-Protection', '1; mode=block');

// Define o cabeçalho X-Content-Type-Options para prevenir sniffing de MIME
Flight::response()->header('X-Content-Type-Options', 'nosniff');

// Define o cabeçalho Referrer-Policy para controlar quanto informação de referenciador é enviada
Flight::response()->header('Referrer-Policy', 'no-referrer-when-downgrade');

// Define o cabeçalho Strict-Transport-Security para forçar HTTPS
Flight::response()->header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');

// Define o cabeçalho Permissions-Policy para controlar quais recursos e APIs podem ser usados
Flight::response()->header('Permissions-Policy', 'geolocation=()');

Esses podem ser adicionados no topo dos seus arquivos routes.php ou index.php.

Adicionar como um Filtro

Você também pode adicioná-los em um filtro/gancho como o seguinte: 

// Adiciona os cabeçalhos em um filtro
Flight::before('start', function() {
    Flight::response()->header('X-Frame-Options', 'SAMEORIGIN');
    Flight::response()->header("Content-Security-Policy", "default-src 'self'");
    Flight::response()->header('X-XSS-Protection', '1; mode=block');
    Flight::response()->header('X-Content-Type-Options', 'nosniff');
    Flight::response()->header('Referrer-Policy', 'no-referrer-when-downgrade');
    Flight::response()->header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
    Flight::response()->header('Permissions-Policy', 'geolocation=()');
});

Adicionar como um Middleware

Você também pode adicioná-los como uma classe de middleware, o que fornece a maior flexibilidade para quais rotas aplicar isso. Em geral, esses cabeçalhos devem ser aplicados a todas as respostas HTML e API.

// app/middlewares/SecurityHeadersMiddleware.php

namespace app\middlewares;

use flight\Engine;

class SecurityHeadersMiddleware
{
    protected Engine $app;

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

    public function before(array $params): void
    {
        $response = $this->app->response();
        $response->header('X-Frame-Options', 'SAMEORIGIN');
        $response->header("Content-Security-Policy", "default-src 'self'");
        $response->header('X-XSS-Protection', '1; mode=block');
        $response->header('X-Content-Type-Options', 'nosniff');
        $response->header('Referrer-Policy', 'no-referrer-when-downgrade');
        $response->header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
        $response->header('Permissions-Policy', 'geolocation=()');
    }
}

// index.php ou onde você tem suas rotas
// FYI, este grupo de string vazia atua como um middleware global para
// todas as rotas. Claro que você poderia fazer a mesma coisa e adicionar
// isso apenas a rotas específicas.
Flight::group('', function(Router $router) {
    $router->get('/users', [ 'UserController', 'getUsers' ]);
    // mais rotas
}, [ SecurityHeadersMiddleware::class ]);

Cross Site Request Forgery (CSRF)

Cross Site Request Forgery (CSRF) é um tipo de ataque onde um site malicioso pode fazer o navegador de um usuário enviar uma solicitação para o seu site. Isso pode ser usado para realizar ações no seu site sem o conhecimento do usuário. Flight não fornece um mecanismo de proteção CSRF integrado, mas você pode facilmente implementar o seu próprio usando middleware.

Configuração

Primeiro, você precisa gerar um token CSRF e armazená-lo na sessão do usuário. Você pode então usar esse token em seus formulários e verificá-lo quando o formulário for enviado. Vamos usar o plugin flightphp/session para gerenciar sessões.

// Gera um token CSRF e armazena na sessão do usuário
// (assumindo que você criou um objeto de sessão e o anexou ao Flight)
// veja a documentação de sessão para mais informações
Flight::register('session', flight\Session::class);

// Você só precisa gerar um único token por sessão (para que funcione 
// em várias abas e solicitações para o mesmo usuário)
if(Flight::session()->get('csrf_token') === null) {
    Flight::session()->set('csrf_token', bin2hex(random_bytes(32)) );
}
Usando o Template Padrão PHP Flight
<!-- Use o token CSRF no seu formulário -->
<form method="post">
    <input type="hidden" name="csrf_token" value="<?= Flight::session()->get('csrf_token') ?>">
    <!-- outros campos do formulário -->
</form>
Usando Latte

Você também pode definir uma função personalizada para exibir o token CSRF em seus templates Latte.


Flight::map('render', function(string $template, array $data, ?string $block): void {
    $latte = new Latte\Engine;

    // outras configurações...

    // Define uma função personalizada para exibir o token CSRF
    $latte->addFunction('csrf', function() {
        $csrfToken = Flight::session()->get('csrf_token');
        return new \Latte\Runtime\Html('<input type="hidden" name="csrf_token" value="' . $csrfToken . '">');
    });

    $latte->render($finalPath, $data, $block);
});

E agora em seus templates Latte, você pode usar a função csrf() para exibir o token CSRF.

<form method="post">
    {csrf()}
    <!-- outros campos do formulário -->
</form>

Verificar o Token CSRF

Você pode verificar o token CSRF usando vários métodos.

Middleware
// app/middlewares/CsrfMiddleware.php

namespace app\middleware;

use flight\Engine;

class CsrfMiddleware
{
    protected Engine $app;

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

    public function before(array $params): void
    {
        if($this->app->request()->method == 'POST') {
            $token = $this->app->request()->data->csrf_token;
            if($token !== $this->app->session()->get('csrf_token')) {
                $this->app->halt(403, 'Invalid CSRF token');
            }
        }
    }
}

// index.php ou onde você tem suas rotas
use app\middlewares\CsrfMiddleware;

Flight::group('', function(Router $router) {
    $router->get('/users', [ 'UserController', 'getUsers' ]);
    // mais rotas
}, [ CsrfMiddleware::class ]);
Filtros de Evento
// Este middleware verifica se a solicitação é uma solicitação POST e, se for, verifica se o token CSRF é válido
Flight::before('start', function() {
    if(Flight::request()->method == 'POST') {

        // captura o token csrf dos valores do formulário
        $token = Flight::request()->data->csrf_token;
        if($token !== Flight::session()->get('csrf_token')) {
            Flight::halt(403, 'Invalid CSRF token');
            // ou para uma resposta JSON
            Flight::jsonHalt(['error' => 'Invalid CSRF token'], 403);
        }
    }
});

Cross Site Scripting (XSS)

Cross Site Scripting (XSS) é um tipo de ataque onde uma entrada de formulário maliciosa pode injetar código no seu site. A maioria dessas oportunidades vem de valores de formulário que seus usuários finais preencherão. Você nunca deve confiar na saída dos seus usuários! Sempre assuma que todos eles são os melhores hackers do mundo. Eles podem injetar JavaScript ou HTML malicioso na sua página. Esse código pode ser usado para roubar informações dos seus usuários ou realizar ações no seu site. Usando a classe de visualização do Flight ou outro motor de templating como Latte, você pode facilmente escapar a saída para prevenir ataques XSS.

// Vamos assumir que o usuário é esperto e tenta usar isso como seu nome
$name = '<script>alert("XSS")</script>';

// Isso escapará a saída
Flight::view()->set('name', $name);
// Isso exibirá: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;

// Se você usar algo como Latte registrado como sua classe de visualização, ele também escapará isso automaticamente.
Flight::view()->render('template', ['name' => $name]);

SQL Injection

SQL Injection é um tipo de ataque onde um usuário malicioso pode injetar código SQL no seu banco de dados. Isso pode ser usado para roubar informações do seu banco de dados ou realizar ações no seu banco de dados. Novamente, você nunca deve confiar na entrada dos seus usuários! Sempre assuma que eles estão em busca de sangue. Você pode usar declarações preparadas em seus objetos PDO para prevenir injeção SQL.

// Assumindo que você tem Flight::db() registrado como seu objeto PDO
$statement = Flight::db()->prepare('SELECT * FROM users WHERE username = :username');
$statement->execute([':username' => $username]);
$users = $statement->fetchAll();

// Se você usar a classe PdoWrapper, isso pode ser feito facilmente em uma linha
$users = Flight::db()->fetchAll('SELECT * FROM users WHERE username = :username', [ 'username' => $username ]);

// Você pode fazer a mesma coisa com um objeto PDO com placeholders ?
$statement = Flight::db()->fetchAll('SELECT * FROM users WHERE username = ?', [ $username ]);

Exemplo Inseguro

O abaixo é o motivo pelo qual usamos declarações preparadas SQL para proteger de exemplos inocentes como o abaixo:

// o usuário final preenche um formulário web.
// para o valor do formulário, o hacker coloca algo como isso:
$username = "' OR 1=1; -- ";

$sql = "SELECT * FROM users WHERE username = '$username' LIMIT 5";
$users = Flight::db()->fetchAll($sql);
// Após a consulta ser construída, fica assim
// SELECT * FROM users WHERE username = '' OR 1=1; -- LIMIT 5

// Parece estranho, mas é uma consulta válida que funcionará. Na verdade,
// é um ataque de injeção SQL muito comum que retornará todos os usuários.

var_dump($users); // isso despejará todos os usuários no banco de dados, não apenas o único nome de usuário

CORS

Cross-Origin Resource Sharing (CORS) é um mecanismo que permite que muitos recursos (por exemplo, fontes, JavaScript, etc.) em uma página web sejam solicitados de outro domínio fora do domínio de origem do recurso. Flight não tem funcionalidade integrada, mas isso pode ser facilmente tratado com um gancho para executar antes do método Flight::start() ser chamado.

// app/utils/CorsUtil.php

namespace app\utils;

class CorsUtil
{
    public function set(array $params): void
    {
        $request = Flight::request();
        $response = Flight::response();
        if ($request->getVar('HTTP_ORIGIN') !== '') {
            $this->allowOrigins();
            $response->header('Access-Control-Allow-Credentials', 'true');
            $response->header('Access-Control-Max-Age', '86400');
        }

        if ($request->method === 'OPTIONS') {
            if ($request->getVar('HTTP_ACCESS_CONTROL_REQUEST_METHOD') !== '') {
                $response->header(
                    'Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD'
                );
            }
            if ($request->getVar('HTTP_ACCESS_CONTROL_REQUEST_HEADERS') !== '') {
                $response->header(
                    "Access-Control-Allow-Headers",
                    $request->getVar('HTTP_ACCESS_CONTROL_REQUEST_HEADERS')
                );
            }

            $response->status(200);
            $response->send();
            exit;
        }
    }

    private function allowOrigins(): void
    {
        // personalize seus hosts permitidos aqui.
        $allowed = [
            'capacitor://localhost',
            'ionic://localhost',
            'http://localhost',
            'http://localhost:4200',
            'http://localhost:8080',
            'http://localhost:8100',
        ];

        $request = Flight::request();

        if (in_array($request->getVar('HTTP_ORIGIN'), $allowed, true) === true) {
            $response = Flight::response();
            $response->header("Access-Control-Allow-Origin", $request->getVar('HTTP_ORIGIN'));
        }
    }
}

// index.php ou onde você tem suas rotas
$CorsUtil = new CorsUtil();

// Isso precisa ser executado antes de start ser executado.
Flight::before('start', [ $CorsUtil, 'setupCors' ]);

Tratamento de Erros

Esconda detalhes de erros sensíveis em produção para evitar vazamento de informações para atacantes. Em produção, registre erros em vez de exibi-los com display_errors definido como 0.

// No seu bootstrap.php ou index.php

// adicione isso ao seu app/config/config.php
$environment = ENVIRONMENT;
if ($environment === 'production') {
    ini_set('display_errors', 0); // Desabilita exibição de erros
    ini_set('log_errors', 1);     // Registra erros em vez disso
    ini_set('error_log', '/path/to/error.log');
}

// Nas suas rotas ou controladores
// Use Flight::halt() para respostas de erro controladas
Flight::halt(403, 'Access denied');

Sanitização de Entrada

Nunca confie na entrada do usuário. Sanitize-a usando filter_var antes de processar para prevenir que dados maliciosos se infiltrem.


// Vamos assumir uma solicitação $_POST com $_POST['input'] e $_POST['email']

// Sanitiza uma entrada de string
$clean_input = filter_var(Flight::request()->data->input, FILTER_SANITIZE_STRING);
// Sanitiza um email
$clean_email = filter_var(Flight::request()->data->email, FILTER_SANITIZE_EMAIL);

Hash de Senhas

Armazene senhas de forma segura e verifique-as com segurança usando as funções integradas do PHP como password_hash e password_verify. As senhas nunca devem ser armazenadas em texto plano, nem devem ser criptografadas com métodos reversíveis. O hashing garante que, mesmo se o seu banco de dados for comprometido, as senhas reais permaneçam protegidas.

$password = Flight::request()->data->password;
// Hash de uma senha ao armazenar (por exemplo, durante o registro)
$hashed_password = password_hash($password, PASSWORD_DEFAULT);

// Verifica uma senha (por exemplo, durante o login)
if (password_verify($password, $stored_hash)) {
    // Senha corresponde
}

Limitação de Taxa

Proteja contra ataques de força bruta ou ataques de negação de serviço limitando as taxas de solicitação com um cache.

// Assumindo que você tem flightphp/cache instalado e registrado
// Usando flightphp/cache em um filtro
Flight::before('start', function() {
    $cache = Flight::cache();
    $ip = Flight::request()->ip;
    $key = "rate_limit_{$ip}";
    $attempts = (int) $cache->retrieve($key);

    if ($attempts >= 10) {
        Flight::halt(429, 'Too many requests');
    }

    $cache->set($key, $attempts + 1, 60); // Redefine após 60 segundos
});

Veja Também

Solução de Problemas

Changelog

Learn/routing

Roteamento

Visão Geral

O roteamento no Flight PHP mapeia padrões de URL para funções de callback ou métodos de classe, permitindo o tratamento rápido e simples de requisições. Ele é projetado para sobrecarga mínima, uso amigável para iniciantes e extensibilidade sem dependências externas.

Entendendo

O roteamento é o mecanismo principal que conecta requisições HTTP à lógica da sua aplicação no Flight. Ao definir rotas, você especifica como diferentes URLs acionam código específico, seja por meio de funções, métodos de classe ou ações de controlador. O sistema de roteamento do Flight é flexível, suportando padrões básicos, parâmetros nomeados, expressões regulares e recursos avançados como injeção de dependência e roteamento de recursos. Essa abordagem mantém seu código organizado e fácil de manter, enquanto permanece rápido e simples para iniciantes e extensível para usuários avançados.

Nota: Quer entender mais sobre roteamento? Confira a página "por que um framework?" para uma explicação mais aprofundada.

Uso Básico

Definindo uma Rota Simples

O roteamento básico no Flight é feito combinando um padrão de URL com uma função de callback ou um array de classe e método.

Flight::route('/', function(){
    echo 'hello world!';
});

As rotas são combinadas na ordem em que são definidas. A primeira rota que combinar com uma requisição será invocada.

Usando Funções como Callbacks

O callback pode ser qualquer objeto que seja chamável. Então, você pode usar uma função regular:

function hello() {
    echo 'hello world!';
}

Flight::route('/', 'hello');

Usando Classes e Métodos como um Controlador

Você também pode usar um método (estático ou não) de uma classe:

class GreetingController {
    public function hello() {
        echo 'hello world!';
    }
}

Flight::route('/', [ 'GreetingController','hello' ]);
// ou
Flight::route('/', [ GreetingController::class, 'hello' ]); // método preferido
// ou
Flight::route('/', [ 'GreetingController::hello' ]);
// ou 
Flight::route('/', [ 'GreetingController->hello' ]);

Ou criando um objeto primeiro e depois chamando o método:

use flight\Engine;

// GreetingController.php
class GreetingController
{
    protected Engine $app
    public function __construct(Engine $app) {
        $this->app = $app;
        $this->name = 'John Doe';
    }

    public function hello() {
        echo "Hello, {$this->name}!";
    }
}

// index.php
$app = Flight::app();
$greeting = new GreetingController($app);

Flight::route('/', [ $greeting, 'hello' ]);

Nota: Por padrão, quando um controlador é chamado dentro do framework, a classe flight\Engine é sempre injetada, a menos que você especifique através de um contêiner de injeção de dependência

Roteamento Específico para Métodos

Por padrão, os padrões de rota são combinados com todos os métodos de requisição. Você pode responder a métodos específicos colocando um identificador antes da URL.

Flight::route('GET /', function () {
  echo 'I received a GET request.';
});

Flight::route('POST /', function () {
  echo 'I received a POST request.';
});

// Você não pode usar Flight::get() para rotas, pois esse é um método 
//    para obter variáveis, não para criar uma rota.
Flight::post('/', function() { /* code */ });
Flight::patch('/', function() { /* code */ });
Flight::put('/', function() { /* code */ });
Flight::delete('/', function() { /* code */ });

Você também pode mapear múltiplos métodos para um único callback usando o delimitador |:

Flight::route('GET|POST /', function () {
  echo 'I received either a GET or a POST request.';
});

Tratamento Especial para Requisições HEAD e OPTIONS

O Flight fornece tratamento integrado para requisições HTTP HEAD e OPTIONS:

Requisições HEAD

Flight::route('GET /info', function() {
    echo 'This is some info!';
});
// Uma requisição HEAD para /info retornará os mesmos cabeçalhos, mas sem corpo.

Requisições OPTIONS

Requisições OPTIONS são tratadas automaticamente pelo Flight para qualquer rota definida.

// Para uma rota definida como:
Flight::route('GET|POST /users', function() { /* ... */ });

// Uma requisição OPTIONS para /users responderá com:
//
// Status: 204 No Content
// Allow: GET, POST, HEAD, OPTIONS

Usando o Objeto Router

Adicionalmente, você pode obter o objeto Router, que tem alguns métodos auxiliares para você usar:


$router = Flight::router();

// mapeia todos os métodos como Flight::route()
$router->map('/', function() {
    echo 'hello world!';
});

// requisição GET
$router->get('/users', function() {
    echo 'users';
});
$router->post('/users',             function() { /* code */});
$router->put('/users/update/@id',   function() { /* code */});
$router->delete('/users/@id',       function() { /* code */});
$router->patch('/users/@id',        function() { /* code */});

Expressões Regulares (Regex)

Você pode usar expressões regulares em suas rotas:

Flight::route('/user/[0-9]+', function () {
  // Isso combinará com /user/1234
});

Embora esse método esteja disponível, é recomendado usar parâmetros nomeados, ou parâmetros nomeados com expressões regulares, pois eles são mais legíveis e fáceis de manter.

Parâmetros Nomeados

Você pode especificar parâmetros nomeados em suas rotas, que serão passados para sua função de callback. Isso é mais para a legibilidade da rota do que qualquer outra coisa. Veja a seção abaixo sobre uma ressalva importante.

Flight::route('/@name/@id', function (string $name, string $id) {
  echo "hello, $name ($id)!";
});

Você também pode incluir expressões regulares com seus parâmetros nomeados usando o delimitador ::

Flight::route('/@name/@id:[0-9]{3}', function (string $name, string $id) {
  // Isso combinará com /bob/123
  // Mas não combinará com /bob/12345
});

Nota: Combinar grupos de regex () com parâmetros posicionais não é suportado. Ex: :'\(

Ressalva Importante

Embora no exemplo acima pareça que @name está diretamente ligado à variável $name, não é o caso. A ordem dos parâmetros na função de callback é o que determina o que é passado para ela. Se você inverter a ordem dos parâmetros na função de callback, as variáveis também serão invertidas. Aqui está um exemplo:

Flight::route('/@name/@id', function (string $id, string $name) {
  echo "hello, $name ($id)!";
});

E se você acessar a seguinte URL: /bob/123, a saída seria hello, 123 (bob)!. Seja cuidadoso ao configurar suas rotas e funções de callback!

Parâmetros Opcionais

Você pode especificar parâmetros nomeados que são opcionais para combinação envolvendo segmentos em parênteses.

Flight::route(
  '/blog(/@year(/@month(/@day)))',
  function(?string $year, ?string $month, ?string $day) {
    // Isso combinará com as seguintes URLs:
    // /blog/2012/12/10
    // /blog/2012/12
    // /blog/2012
    // /blog
  }
);

Quaisquer parâmetros opcionais que não forem combinados serão passados como NULL.

Roteamento com Curinga

A combinação é feita apenas em segmentos individuais de URL. Se você quiser combinar múltiplos segmentos, pode usar o curinga *.

Flight::route('/blog/*', function () {
  // Isso combinará com /blog/2000/02/01
});

Para rotear todas as requisições para um único callback, você pode fazer:

Flight::route('*', function () {
  // Faça algo
});

Manipulador de 404 Não Encontrado

Por padrão, se uma URL não puder ser encontrada, o Flight enviará uma resposta HTTP 404 Not Found que é muito simples e básica. Se você quiser uma resposta 404 mais personalizada, pode mapear seu próprio método notFound:

Flight::map('notFound', function() {
    $url = Flight::request()->url;

    // Você também poderia usar Flight::render() com um template personalizado.
    $output = <<<HTML
        <h1>My Custom 404 Not Found</h1>
        <h3>The page you have requested {$url} could not be found.</h3>
        HTML;

    $this->response()
        ->clearBody()
        ->status(404)
        ->write($output)
        ->send();
});

Manipulador de Método Não Encontrado

Por padrão, se uma URL for encontrada, mas o método não for permitido, o Flight enviará uma resposta HTTP 405 Method Not Allowed que é muito simples e básica (Ex: Method Not Allowed. Allowed Methods are: GET, POST). Ele também incluirá um cabeçalho Allow com os métodos permitidos para aquela URL.

Se você quiser uma resposta 405 mais personalizada, pode mapear seu próprio método methodNotFound:

use flight\net\Route;

Flight::map('methodNotFound', function(Route $route) {
    $url = Flight::request()->url;
    $methods = implode(', ', $route->methods);

    // Você também poderia usar Flight::render() com um template personalizado.
    $output = <<<HTML
        <h1>My Custom 405 Method Not Allowed</h1>
        <h3>The method you have requested for {$url} is not allowed.</h3>
        <p>Allowed Methods are: {$methods}</p>
        HTML;

    $this->response()
        ->clearBody()
        ->status(405)
        ->setHeader('Allow', $methods)
        ->write($output)
        ->send();
});

Uso Avançado

Injeção de Dependência em Rotas

Se você quiser usar injeção de dependência via um contêiner (PSR-11, PHP-DI, Dice, etc), o único tipo de rotas onde isso está disponível é criando o objeto diretamente você mesmo e usando o contêiner para criar seu objeto, ou você pode usar strings para definir a classe e o método a chamar. Você pode ir à página Injeção de Dependência para mais informações.

Aqui está um exemplo rápido:


use flight\database\PdoWrapper;

// Greeting.php
class Greeting
{
    protected PdoWrapper $pdoWrapper;
    public function __construct(PdoWrapper $pdoWrapper) {
        $this->pdoWrapper = $pdoWrapper;
    }

    public function hello(int $id) {
        // faça algo com $this->pdoWrapper
        $name = $this->pdoWrapper->fetchField("SELECT name FROM users WHERE id = ?", [ $id ]);
        echo "Hello, world! My name is {$name}!";
    }
}

// index.php

// Configure o contêiner com quaisquer parâmetros que você precisar
// Veja a página de Injeção de Dependência para mais informações sobre PSR-11
$dice = new \Dice\Dice();

// Não esqueça de reatribuir a variável com '$dice = '!!!!!
$dice = $dice->addRule('flight\database\PdoWrapper', [
    'shared' => true,
    'constructParams' => [ 
        'mysql:host=localhost;dbname=test', 
        'root',
        'password'
    ]
]);

// Registre o manipulador do contêiner
Flight::registerContainerHandler(function($class, $params) use ($dice) {
    return $dice->create($class, $params);
});

// Rotas como normal
Flight::route('/hello/@id', [ 'Greeting', 'hello' ]);
// ou
Flight::route('/hello/@id', 'Greeting->hello');
// ou
Flight::route('/hello/@id', 'Greeting::hello');

Flight::start();

Passando a Execução para a Próxima Rota

Depreciado Você pode passar a execução para a próxima rota combinante retornando true da sua função de callback.

Flight::route('/user/@name', function (string $name) {
  // Verifique alguma condição
  if ($name !== "Bob") {
    // Continue para a próxima rota
    return true;
  }
});

Flight::route('/user/*', function () {
  // Isso será chamado
});

Agora é recomendado usar middleware para lidar com casos de uso complexos como este.

Aliasing de Rotas

Ao atribuir um alias a uma rota, você pode chamar esse alias dinamicamente em sua aplicação para ser gerado mais tarde no seu código (ex: um link em um template HTML, ou gerando uma URL de redirecionamento).

Flight::route('/users/@id', function($id) { echo 'user:'.$id; }, false, 'user_view');
// ou 
Flight::route('/users/@id', function($id) { echo 'user:'.$id; })->setAlias('user_view');

// mais tarde no código em algum lugar
class UserController {
    public function update() {

        // código para salvar usuário...
        $id = $user['id']; // 5 por exemplo

        $redirectUrl = Flight::getUrl('user_view', [ 'id' => $id ]); // retornará '/users/5'
        Flight::redirect($redirectUrl);
    }
}

Isso é especialmente útil se sua URL acontecer de mudar. No exemplo acima, digamos que users foi movido para /admin/users/@id em vez disso. Com o aliasing no lugar para a rota, você não precisa mais encontrar todas as URLs antigas no seu código e alterá-las porque o alias agora retornará /admin/users/5 como no exemplo acima.

O aliasing de rotas ainda funciona em grupos também:

Flight::group('/users', function() {
    Flight::route('/@id', function($id) { echo 'user:'.$id; }, false, 'user_view');
    // ou
    Flight::route('/@id', function($id) { echo 'user:'.$id; })->setAlias('user_view');
});

Inspecionando Informações de Rota

Se você quiser inspecionar as informações da rota combinante, há 2 maneiras de fazer isso:

  1. Você pode usar uma propriedade executedRoute no objeto Flight::router().
  2. Você pode solicitar que o objeto de rota seja passado para seu callback passando true como o terceiro parâmetro no método de rota. O objeto de rota sempre será o último parâmetro passado para sua função de callback.

executedRoute

Flight::route('/', function() {
  $route = Flight::router()->executedRoute;
  // Faça algo com $route
  // Array de métodos HTTP combinados
  $route->methods;

  // Array de parâmetros nomeados
  $route->params;

  // Expressão regular combinante
  $route->regex;

  // Contém o conteúdo de qualquer '*' usado no padrão de URL
  $route->splat;

  // Mostra o caminho da url....se você realmente precisar
  $route->pattern;

  // Mostra o middleware atribuído a isso
  $route->middleware;

  // Mostra o alias atribuído a esta rota
  $route->alias;
});

Nota: A propriedade executedRoute só será definida após uma rota ter sido executada. Se você tentar acessá-la antes de uma rota ter sido executada, ela será NULL. Você também pode usar executedRoute em middleware!

Passar true na definição de rota

Flight::route('/', function(\flight\net\Route $route) {
  // Array de métodos HTTP combinados
  $route->methods;

  // Array de parâmetros nomeados
  $route->params;

  // Expressão regular combinante
  $route->regex;

  // Contém o conteúdo de qualquer '*' usado no padrão de URL
  $route->splat;

  // Mostra o caminho da url....se você realmente precisar
  $route->pattern;

  // Mostra o middleware atribuído a isso
  $route->middleware;

  // Mostra o alias atribuído a esta rota
  $route->alias;
}, true);// <-- Este parâmetro true é o que faz isso acontecer

Agrupamento de Rotas e Middleware

Pode haver vezes em que você queira agrupar rotas relacionadas juntas (como /api/v1). Você pode fazer isso usando o método group:

Flight::group('/api/v1', function () {
  Flight::route('/users', function () {
    // Combina com /api/v1/users
  });

  Flight::route('/posts', function () {
    // Combina com /api/v1/posts
  });
});

Você pode até aninhar grupos de grupos:

Flight::group('/api', function () {
  Flight::group('/v1', function () {
    // Flight::get() obtém variáveis, não define uma rota! Veja o contexto de objeto abaixo
    Flight::route('GET /users', function () {
      // Combina com GET /api/v1/users
    });

    Flight::post('/posts', function () {
      // Combina com POST /api/v1/posts
    });

    Flight::put('/posts/1', function () {
      // Combina com PUT /api/v1/posts
    });
  });
  Flight::group('/v2', function () {

    // Flight::get() obtém variáveis, não define uma rota! Veja o contexto de objeto abaixo
    Flight::route('GET /users', function () {
      // Combina com GET /api/v2/users
    });
  });
});

Agrupamento com Contexto de Objeto

Você ainda pode usar agrupamento de rotas com o objeto Engine da seguinte maneira:

$app = Flight::app();

$app->group('/api/v1', function (Router $router) {

  // use a variável $router
  $router->get('/users', function () {
    // Combina com GET /api/v1/users
  });

  $router->post('/posts', function () {
    // Combina com POST /api/v1/posts
  });
});

Nota: Este é o método preferido de definir rotas e grupos com o objeto $router.

Agrupamento com Middleware

Você também pode atribuir middleware a um grupo de rotas:

Flight::group('/api/v1', function () {
  Flight::route('/users', function () {
    // Combina com /api/v1/users
  });
}, [ MyAuthMiddleware::class ]); // ou [ new MyAuthMiddleware() ] se você quiser usar uma instância

Veja mais detalhes na página middleware de grupo.

Roteamento de Recursos

Você pode criar um conjunto de rotas para um recurso usando o método resource. Isso criará um conjunto de rotas para um recurso que segue as convenções RESTful.

Para criar um recurso, faça o seguinte:

Flight::resource('/users', UsersController::class);

E o que acontecerá em segundo plano é que ele criará as seguintes rotas:

[
      'index' => 'GET /users',
      'create' => 'GET /users/create',
      'store' => 'POST /users',
      'show' => 'GET /users/@id',
      'edit' => 'GET /users/@id/edit',
      'update' => 'PUT /users/@id',
      'destroy' => 'DELETE /users/@id'
]

E seu controlador usará os seguintes métodos:

class UsersController
{
    public function index(): void
    {
    }

    public function show(string $id): void
    {
    }

    public function create(): void
    {
    }

    public function store(): void
    {
    }

    public function edit(string $id): void
    {
    }

    public function update(string $id): void
    {
    }

    public function destroy(string $id): void
    {
    }
}

Nota: Você pode visualizar as rotas recém-adicionadas com runway executando php runway routes.

Personalizando Rotas de Recursos

Há algumas opções para configurar as rotas de recursos.

Base de Alias

Você pode configurar o aliasBase. Por padrão, o alias é a última parte da URL especificada. Por exemplo, /users/ resultaria em um aliasBase de users. Quando essas rotas são criadas, os aliases são users.index, users.create, etc. Se você quiser alterar o alias, defina o aliasBase para o valor que deseja.

Flight::resource('/users', UsersController::class, [ 'aliasBase' => 'user' ]);
Only e Except

Você também pode especificar quais rotas deseja criar usando as opções only e except.

// Lista branca apenas desses métodos e lista negra do resto
Flight::resource('/users', UsersController::class, [ 'only' => [ 'index', 'show' ] ]);
// Lista negra apenas desses métodos e lista branca do resto
Flight::resource('/users', UsersController::class, [ 'except' => [ 'create', 'store', 'edit', 'update', 'destroy' ] ]);

Essas são basicamente opções de lista branca e lista negra para que você possa especificar quais rotas deseja criar.

Middleware

Você também pode especificar middleware para ser executado em cada uma das rotas criadas pelo método resource.

Flight::resource('/users', UsersController::class, [ 'middleware' => [ MyAuthMiddleware::class ] ]);

Respostas em Streaming

Agora você pode transmitir respostas para o cliente usando stream() ou streamWithHeaders(). Isso é útil para enviar arquivos grandes, processos de longa duração ou gerar respostas grandes. Transmitir uma rota é tratada um pouco diferente de uma rota regular.

Nota: Respostas em streaming estão disponíveis apenas se você tiver flight.v2.output_buffering definido como false.

Stream com Cabeçalhos Manuais

Você pode transmitir uma resposta para o cliente usando o método stream() em uma rota. Se você fizer isso, deve definir todos os cabeçalhos manualmente antes de produzir qualquer coisa para o cliente. Isso é feito com a função php header() ou o método Flight::response()->setRealHeader().

Flight::route('/@filename', function($filename) {

    $response = Flight::response();

    // obviamente você sanitizaria o caminho e tal.
    $fileNameSafe = basename($filename);

    // Se você tiver cabeçalhos adicionais para definir aqui após a rota ter sido executada
    // você deve defini-los antes de qualquer coisa ser ecoada.
    // Eles devem ser uma chamada raw para a função header() ou 
    // uma chamada para Flight::response()->setRealHeader()
    header('Content-Disposition: attachment; filename="'.$fileNameSafe.'"');
    // ou
    $response->setRealHeader('Content-Disposition: attachment; filename="'.$fileNameSafe.'"');

    $filePath = '/some/path/to/files/'.$fileNameSafe;

    if (!is_readable($filePath)) {
        Flight::halt(404, 'File not found');
    }

    // defina manualmente o comprimento do conteúdo se quiser
    header('Content-Length: '.filesize($filePath));
    // ou
    $response->setRealHeader('Content-Length: '.filesize($filePath));

    // Transmita o arquivo para o cliente conforme ele é lido
    readfile($filePath);

// Esta é a linha mágica aqui
})->stream();

Stream com Cabeçalhos

Você também pode usar o método streamWithHeaders() para definir os cabeçalhos antes de começar a transmitir.

Flight::route('/stream-users', function() {

    // você pode adicionar quaisquer cabeçalhos adicionais que quiser aqui
    // você só deve usar header() ou Flight::response()->setRealHeader()

    // no entanto, como você puxa seus dados, apenas como exemplo...
    $users_stmt = Flight::db()->query("SELECT id, first_name, last_name FROM users");

    echo '{';
    $user_count = count($users);
    while($user = $users_stmt->fetch(PDO::FETCH_ASSOC)) {
        echo json_encode($user);
        if(--$user_count > 0) {
            echo ',';
        }

        // Isso é necessário para enviar os dados para o cliente
        ob_flush();
    }
    echo '}';

// É assim que você definirá os cabeçalhos antes de começar a transmitir.
})->streamWithHeaders([
    'Content-Type' => 'application/json',
    'Content-Disposition' => 'attachment; filename="users.json"',
    // código de status opcional, padrão para 200
    'status' => 200
]);

Veja Também

Solução de Problemas

404 Não Encontrado ou Comportamento Inesperado de Rota

Se você estiver vendo um erro 404 Não Encontrado (mas você jura pela sua vida que ele está realmente lá e não é um erro de digitação), isso na verdade pode ser um problema com você retornando um valor no endpoint da sua rota em vez de apenas ecoá-lo. A razão para isso é intencional, mas pode surpreender alguns desenvolvedores.

Flight::route('/hello', function(){
    // Isso pode causar um erro 404 Não Encontrado
    return 'Hello World';
});

// O que você provavelmente quer
Flight::route('/hello', function(){
    echo 'Hello World';
});

A razão para isso é por causa de um mecanismo especial incorporado no roteador que trata a saída de retorno como um sinal para "ir para a próxima rota". Você pode ver o comportamento documentado na seção Roteamento.

Changelog

Learn/learn

Aprenda Sobre o Flight

Flight é um framework rápido, simples e extensível para PHP. Ele é bastante versátil e pode ser usado para construir qualquer tipo de aplicação web. Ele é construído com simplicidade em mente e é escrito de uma forma que é fácil de entender e usar.

Nota: Você verá exemplos que usam Flight:: como uma variável estática e alguns que usam o objeto Engine $app->. Ambos funcionam de forma intercambiável com o outro. $app e $this->app em um controller/middleware é a abordagem recomendada pela equipe do Flight.

Componentes Principais

Routing

Aprenda como gerenciar rotas para sua aplicação web. Isso também inclui agrupar rotas, parâmetros de rota e middleware.

Middleware

Aprenda como usar middleware para filtrar requisições e respostas em sua aplicação.

Autoloading

Aprenda como autoloadar suas próprias classes em sua aplicação.

Requests

Aprenda como lidar com requisições e respostas em sua aplicação.

Responses

Aprenda como enviar respostas para seus usuários.

HTML Templates

Aprenda como usar o motor de visualização integrado para renderizar seus templates HTML.

Security

Aprenda como proteger sua aplicação contra ameaças de segurança comuns.

Configuration

Aprenda como configurar o framework para sua aplicação.

Event Manager

Aprenda como usar o sistema de eventos para adicionar eventos personalizados à sua aplicação.

Extending Flight

Aprenda como estender o framework adicionando seus próprios métodos e classes.

Method Hooks and Filtering

Aprenda como adicionar hooks de eventos aos seus métodos e métodos internos do framework.

Dependency Injection Container (DIC)

Aprenda como usar contêineres de injeção de dependência (DIC) para gerenciar as dependências de sua aplicação.

Classes de Utilidade

Collections

Collections são usadas para armazenar dados e serem acessíveis como um array ou como um objeto para facilitar o uso.

JSON Wrapper

Isso tem algumas funções simples para tornar a codificação e decodificação do seu JSON consistente.

PDO Wrapper

PDO às vezes pode adicionar mais dor de cabeça do que o necessário. Esta classe wrapper simples pode tornar significativamente mais fácil interagir com seu banco de dados.

Uploaded File Handler

Uma classe simples para ajudar a gerenciar arquivos enviados e movê-los para um local permanente.

Conceitos Importantes

Por Que um Framework?

Aqui está um artigo curto sobre por que você deve usar um framework. É uma boa ideia entender os benefícios de usar um framework antes de começar a usar um.

Adicionalmente, um excelente tutorial foi criado por @lubiana. Embora não entre em grandes detalhes sobre o Flight especificamente, este guia ajudará você a entender alguns dos principais conceitos ao redor de um framework e por que eles são benéficos de usar. Você pode encontrar o tutorial aqui.

Flight Comparado a Outros Frameworks

Se você está migrando de outro framework como Laravel, Slim, Fat-Free ou Symfony para o Flight, esta página ajudará você a entender as diferenças entre os dois.

Outros Tópicos

Unit Testing

Siga este guia para aprender como fazer testes unitários no seu código Flight para que seja sólido como uma rocha.

AI & Developer Experience

Aprenda como o Flight funciona com ferramentas de IA e fluxos de trabalho modernos de desenvolvedor para ajudá-lo a codificar mais rápido e de forma mais inteligente.

Migrating v2 -> v3

A compatibilidade com versões anteriores foi mantida na maior parte, mas há algumas mudanças das quais você deve estar ciente ao migrar da v2 para a v3.

Learn/unit_testing

Testes Unitários

Visão Geral

Os testes unitários no Flight ajudam você a garantir que sua aplicação se comporte como esperado, capture bugs cedo e torne seu código mais fácil de manter. O Flight é projetado para funcionar suavemente com PHPUnit, o framework de testes PHP mais popular.

Entendendo

Os testes unitários verificam o comportamento de pequenas partes da sua aplicação (como controladores ou serviços) de forma isolada. No Flight, isso significa testar como suas rotas, controladores e lógica respondem a diferentes entradas — sem depender de estado global ou serviços externos reais.

Princípios chave:

Uso Básico

Configurando o PHPUnit

  1. Instale o PHPUnit com o Composer: 
    composer require --dev phpunit/phpunit
  2. Crie um diretório tests na raiz do seu projeto.
  3. Adicione um script de teste ao seu composer.json: 
    "scripts": {
   "test": "phpunit --configuration phpunit.xml"
}
  4. Crie um arquivo phpunit.xml: 
    <?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php">
   <testsuites>
       <testsuite name="Flight Tests">
           <directory>tests</directory>
       </testsuite>
   </testsuites>
</phpunit>

Agora você pode executar seus testes com composer test.

Testando um Manipulador de Rota Simples

Suponha que você tenha uma rota que valida um e-mail:

// index.php
$app->route('POST /register', [ UserController::class, 'register' ]);

// UserController.php
class UserController {
    protected $app;
    public function __construct(flight\Engine $app) {
        $this->app = $app;
    }
    public function register() {
        $email = $this->app->request()->data->email;
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            return $this->app->json(['status' => 'error', 'message' => 'Invalid email']);
        }
        return $this->app->json(['status' => 'success', 'message' => 'Valid email']);
    }
}

Um teste simples para este controlador:

use PHPUnit\Framework\TestCase;
use flight\Engine;

class UserControllerTest extends TestCase {
    public function testValidEmailReturnsSuccess() {
        $app = new Engine();
        $app->request()->data->email = 'test@example.com';
        $controller = new UserController($app);
        $controller->register();
        $response = $app->response()->getBody();
        $output = json_decode($response, true);
        $this->assertEquals('success', $output['status']);
        $this->assertEquals('Valid email', $output['message']);
    }

    public function testInvalidEmailReturnsError() {
        $app = new Engine();
        $app->request()->data->email = 'invalid-email';
        $controller = new UserController($app);
        $controller->register();
        $response = $app->response()->getBody();
        $output = json_decode($response, true);
        $this->assertEquals('error', $output['status']);
        $this->assertEquals('Invalid email', $output['message']);
    }
}

Dicas:

Usando Injeção de Dependências para Controladores Testáveis

Injete dependências (como o banco de dados ou remetente de e-mail) em seus controladores para torná-los fáceis de simular em testes:

use flight\database\PdoWrapper;

class UserController {
    protected $app;
    protected $db;
    protected $mailer;
    public function __construct($app, $db, $mailer) {
        $this->app = $app;
        $this->db = $db;
        $this->mailer = $mailer;
    }
    public function register() {
        $email = $this->app->request()->data->email;
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            return $this->app->json(['status' => 'error', 'message' => 'Invalid email']);
        }
        $this->db->runQuery('INSERT INTO users (email) VALUES (?)', [$email]);
        $this->mailer->sendWelcome($email);
        return $this->app->json(['status' => 'success', 'message' => 'User registered']);
    }
}

E um teste com simulações:

use PHPUnit\Framework\TestCase;

class UserControllerDICTest extends TestCase {
    public function testValidEmailSavesAndSendsEmail() {
        $mockDb = $this->createMock(flight\database\PdoWrapper::class);
        $mockDb->method('runQuery')->willReturn(true);
        $mockMailer = new class {
            public $sentEmail = null;
            public function sendWelcome($email) { $this->sentEmail = $email; return true; }
        };
        $app = new flight\Engine();
        $app->request()->data->email = 'test@example.com';
        $controller = new UserController($app, $mockDb, $mockMailer);
        $controller->register();
        $response = $app->response()->getBody();
        $result = json_decode($response, true);
        $this->assertEquals('success', $result['status']);
        $this->assertEquals('User registered', $result['message']);
        $this->assertEquals('test@example.com', $mockMailer->sentEmail);
    }
}

Uso Avançado

Veja Também

Solução de Problemas

Registro de Alterações

Learn/flight_vs_symfony

Flight vs Symfony

O que é Symfony?

Symfony é um conjunto de componentes PHP reutilizáveis e um framework PHP para projetos web.

A base padrão na qual as melhores aplicações PHP são construídas. Escolha qualquer um dos 50 componentes independentes disponíveis para suas próprias aplicações.

Acelere a criação e manutenção de suas aplicações web PHP. Encerre tarefas repetitivas de codificação e aproveite o poder de controlar seu código.

Prós comparados ao Flight

Contras comparados ao Flight

Learn/flight_vs_another_framework

Comparando Flight com Outro Framework

Se você está migrando de outro framework como Laravel, Slim, Fat-Free, ou Symfony para o Flight, esta página irá ajudá-lo a entender as diferenças entre os dois.

Laravel

Laravel é um framework completo que possui todos os recursos e uma incrível ecossistema focado no desenvolvedor, mas com um custo em desempenho e complexidade.

Veja a comparação entre Laravel e Flight.

Slim

Slim é um micro-framework que é semelhante ao Flight. Ele é projetado para ser leve e fácil de usar, mas pode ser um pouco mais complexo do que o Flight.

Veja a comparação entre Slim e Flight.

Fat-Free

Fat-Free é um framework full-stack em um pacote muito menor. Embora tenha todas as ferramentas necessárias, ele possui uma arquitetura de dados que pode tornar alguns projetos mais complexos do que precisam ser.

Veja a comparação entre Fat-Free e Flight.

Symfony

Symfony é um framework modular de nível empresarial projetado para ser flexível e escalável. Para projetos menores ou desenvolvedores mais novos, Symfony pode ser um pouco avassalador.

Veja a comparação entre Symfony e Flight.

Learn/pdo_wrapper

Classe Auxiliar PDO PdoWrapper

Visão Geral

A classe PdoWrapper no Flight é um auxiliar amigável para trabalhar com bancos de dados usando PDO. Ela simplifica tarefas comuns de banco de dados, adiciona alguns métodos úteis para buscar resultados e retorna os resultados como Collections para acesso fácil. Ela também suporta log de consultas e monitoramento de desempenho de aplicação (APM) para casos de uso avançados.

Entendendo

Trabalhar com bancos de dados em PHP pode ser um pouco verboso, especialmente ao usar PDO diretamente. PdoWrapper estende PDO e adiciona métodos que facilitam muito a consulta, busca e manipulação de resultados. Em vez de lidar com declarações preparadas e modos de busca, você obtém métodos simples para tarefas comuns, e cada linha é retornada como uma Collection, para que você possa usar notação de array ou objeto.

Você pode registrar o PdoWrapper como um serviço compartilhado no Flight, e então usá-lo em qualquer lugar da sua aplicação via Flight::db().

Uso Básico

Registrando o Auxiliar PDO

Primeiro, registre a classe PdoWrapper com o Flight:

Flight::register('db', \flight\database\PdoWrapper::class, [
    'mysql:host=localhost;dbname=cool_db_name', 'user', 'pass', [
        PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES \'utf8mb4\'',
        PDO::ATTR_EMULATE_PREPARES => false,
        PDO::ATTR_STRINGIFY_FETCHES => false,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC
    ]
]);

Agora você pode usar Flight::db() em qualquer lugar para obter sua conexão com o banco de dados.

Executando Consultas

runQuery()

function runQuery(string $sql, array $params = []): PDOStatement

Use isso para INSERTs, UPDATEs, ou quando você quiser buscar resultados manualmente:

$db = Flight::db();
$statement = $db->runQuery("SELECT * FROM users WHERE status = ?", ['active']);
while ($row = $statement->fetch()) {
    // $row é um array
}

Você também pode usá-lo para gravações:

$db->runQuery("INSERT INTO users (name) VALUES (?)", ['Alice']);
$db->runQuery("UPDATE users SET name = ? WHERE id = ?", ['Bob', 1]);

fetchField()

function fetchField(string $sql, array $params = []): mixed

Obtenha um único valor do banco de dados:

$count = Flight::db()->fetchField("SELECT COUNT(*) FROM users WHERE status = ?", ['active']);

fetchRow()

function fetchRow(string $sql, array $params = []): Collection

Obtenha uma única linha como uma Collection (acesso array/objeto):

$user = Flight::db()->fetchRow("SELECT * FROM users WHERE id = ?", [123]);
echo $user['name'];
// ou
echo $user->name;

fetchAll()

function fetchAll(string $sql, array $params = []): array<Collection>

Obtenha todas as linhas como um array de Collections:

$users = Flight::db()->fetchAll("SELECT * FROM users WHERE status = ?", ['active']);
foreach ($users as $user) {
    echo $user['name'];
    // ou
    echo $user->name;
}

Usando Placeholders IN()

Você pode usar um único ? em uma cláusula IN() e passar um array ou string separada por vírgulas:

$ids = [1, 2, 3];
$users = Flight::db()->fetchAll("SELECT * FROM users WHERE id IN (?)", [$ids]);
// ou
$users = Flight::db()->fetchAll("SELECT * FROM users WHERE id IN (?)", ['1,2,3']);

Uso Avançado

Log de Consultas & APM

Se você quiser rastrear o desempenho de consultas, habilite o rastreamento APM ao registrar:

Flight::register('db', \flight\database\PdoWrapper::class, [
    'mysql:host=localhost;dbname=cool_db_name', 'user', 'pass', [/* options */], true // último parâmetro habilita APM
]);

Após executar consultas, você pode registrá-las manualmente, mas o APM as registrará automaticamente se habilitado:

Flight::db()->logQueries();

Isso acionará um evento (flight.db.queries) com métricas de conexão e consulta, que você pode escutar usando o sistema de eventos do Flight.

Exemplo Completo

Flight::route('/users', function () {
    // Obter todos os usuários
    $users = Flight::db()->fetchAll('SELECT * FROM users');

    // Transmitir todos os usuários
    $statement = Flight::db()->runQuery('SELECT * FROM users');
    while ($user = $statement->fetch()) {
        echo $user['name'];
    }

    // Obter um único usuário
    $user = Flight::db()->fetchRow('SELECT * FROM users WHERE id = ?', [123]);

    // Obter um único valor
    $count = Flight::db()->fetchField('SELECT COUNT(*) FROM users');

    // Sintaxe especial IN()
    $users = Flight::db()->fetchAll('SELECT * FROM users WHERE id IN (?)', [[1,2,3,4,5]]);
    $users = Flight::db()->fetchAll('SELECT * FROM users WHERE id IN (?)', ['1,2,3,4,5']);

    // Inserir um novo usuário
    Flight::db()->runQuery("INSERT INTO users (name, email) VALUES (?, ?)", ['Bob', 'bob@example.com']);
    $insert_id = Flight::db()->lastInsertId();

    // Atualizar um usuário
    Flight::db()->runQuery("UPDATE users SET name = ? WHERE id = ?", ['Bob', 123]);

    // Deletar um usuário
    Flight::db()->runQuery("DELETE FROM users WHERE id = ?", [123]);

    // Obter o número de linhas afetadas
    $statement = Flight::db()->runQuery("UPDATE users SET name = ? WHERE name = ?", ['Bob', 'Sally']);
    $affected_rows = $statement->rowCount();
});

Veja Também

Solução de Problemas

Registro de Alterações

Learn/dependency_injection_container

Contêiner de Injeção de Dependência

Visão Geral

O Contêiner de Injeção de Dependência (DIC) é uma melhoria poderosa que permite gerenciar as dependências da sua aplicação.

Entendendo

A Injeção de Dependência (DI) é um conceito chave em frameworks PHP modernos e é usada para gerenciar a instanciação e configuração de objetos. Alguns exemplos de bibliotecas DIC são: flightphp/container, Dice, Pimple, PHP-DI, e league/container.

Um DIC é uma forma elegante de permitir que você crie e gerencie suas classes em um local centralizado. Isso é útil quando você precisa passar o mesmo objeto para múltiplas classes (como seus controladores ou middleware, por exemplo).

Uso Básico

A forma antiga de fazer as coisas pode parecer assim:


require 'vendor/autoload.php';

// class to manage users from the database
class UserController {

    protected PDO $pdo;

    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }

    public function view(int $id) {
        $stmt = $this->pdo->prepare('SELECT * FROM users WHERE id = :id');
        $stmt->execute(['id' => $id]);

        print_r($stmt->fetch());
    }
}

// in your routes.php file

$db = new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');

$UserController = new UserController($db);
Flight::route('/user/@id', [ $UserController, 'view' ]);
// other UserController routes...

Flight::start();

Você pode ver no código acima que estamos criando um novo objeto PDO e passando-o para nossa classe UserController. Isso é bom para uma aplicação pequena, mas à medida que sua aplicação cresce, você descobrirá que está criando ou passando o mesmo objeto PDO em múltiplos lugares. É aí que um DIC se torna útil.

Aqui está o mesmo exemplo usando um DIC (usando Dice):


require 'vendor/autoload.php';

// same class as above. Nothing changed
class UserController {

    protected PDO $pdo;

    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }

    public function view(int $id) {
        $stmt = $this->pdo->prepare('SELECT * FROM users WHERE id = :id');
        $stmt->execute(['id' => $id]);

        print_r($stmt->fetch());
    }
}

// create a new container
$container = new \Dice\Dice;

// add a rule to tell the container how to create a PDO object
// don't forget to reassign it to itself like below!
$container = $container->addRule('PDO', [
    // shared means that the same object will be returned each time
    'shared' => true,
    'constructParams' => ['mysql:host=localhost;dbname=test', 'user', 'pass' ]
]);

// This registers the container handler so Flight knows to use it.
Flight::registerContainerHandler(function($class, $params) use ($container) {
    return $container->create($class, $params);
});

// now we can use the container to create our UserController
Flight::route('/user/@id', [ UserController::class, 'view' ]);

Flight::start();

Aposto que você pode estar pensando que houve muito código extra adicionado ao exemplo. A mágica vem quando você tem outro controlador que precisa do objeto PDO.


// If all your controllers have a constructor that needs a PDO object
// each of the routes below will automatically have it injected!!!
Flight::route('/company/@id', [ CompanyController::class, 'view' ]);
Flight::route('/organization/@id', [ OrganizationController::class, 'view' ]);
Flight::route('/category/@id', [ CategoryController::class, 'view' ]);
Flight::route('/settings', [ SettingsController::class, 'view' ]);

O bônus adicional de utilizar um DIC é que os testes unitários se tornam muito mais fáceis. Você pode criar um objeto mock e passá-lo para sua classe. Isso é um grande benefício quando você está escrevendo testes para sua aplicação!

Criando um manipulador DIC centralizado

Você pode criar um manipulador DIC centralizado no seu arquivo de serviços estendendo sua app. Aqui está um exemplo:

// services.php

// create a new container
$container = new \Dice\Dice;
// don't forget to reassign it to itself like below!
$container = $container->addRule('PDO', [
    // shared means that the same object will be returned each time
    'shared' => true,
    'constructParams' => ['mysql:host=localhost;dbname=test', 'user', 'pass' ]
]);

// now we can create a mappable method to create any object. 
Flight::map('make', function($class, $params = []) use ($container) {
    return $container->create($class, $params);
});

// This registers the container handler so Flight knows to use it for controllers/middleware
Flight::registerContainerHandler(function($class, $params) {
    Flight::make($class, $params);
});

// lets say we have the following sample class that takes a PDO object in the constructor
class EmailCron {
    protected PDO $pdo;

    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }

    public function send() {
        // code that sends an email
    }
}

// And finally you can create objects using dependency injection
$emailCron = Flight::make(EmailCron::class);
$emailCron->send();

flightphp/container

Flight tem um plugin que fornece um contêiner simples compatível com PSR-11 que você pode usar para gerenciar sua injeção de dependência. Aqui está um exemplo rápido de como usá-lo:


// index.php for example
require 'vendor/autoload.php';

use flight\Container;

$container = new Container;

$container->set(PDO::class, fn(): PDO => new PDO('sqlite::memory:'));

Flight::registerContainerHandler([$container, 'get']);

class TestController {
  private PDO $pdo;

  function __construct(PDO $pdo) {
    $this->pdo = $pdo;
  }

  function index() {
    var_dump($this->pdo);
    // will output this correctly!
  }
}

Flight::route('GET /', [TestController::class, 'index']);

Flight::start();

Uso Avançado de flightphp/container

Você também pode resolver dependências recursivamente. Aqui está um exemplo:

<?php

require 'vendor/autoload.php';

use flight\Container;

class User {}

interface UserRepository {
  function find(int $id): ?User;
}

class PdoUserRepository implements UserRepository {
  private PDO $pdo;

  function __construct(PDO $pdo) {
    $this->pdo = $pdo;
  }

  function find(int $id): ?User {
    // Implementation ...
    return null;
  }
}

$container = new Container;

$container->set(PDO::class, static fn(): PDO => new PDO('sqlite::memory:'));
$container->set(UserRepository::class, PdoUserRepository::class);

$userRepository = $container->get(UserRepository::class);
var_dump($userRepository);

/*
object(PdoUserRepository)#4 (1) {
  ["pdo":"PdoUserRepository":private]=>
  object(PDO)#3 (0) {
  }
}
 */

DICE

Você também pode criar seu próprio manipulador DIC. Isso é útil se você tiver um contêiner personalizado que deseja usar que não é PSR-11 (Dice). Veja a seção de uso básico para como fazer isso.

Além disso, há alguns padrões úteis que facilitarão sua vida ao usar Flight.

Instância Engine

Se você estiver usando a instância Engine em seus controladores/middleware, aqui está como você configuraria:


// Somewhere in your bootstrap file
$engine = Flight::app();

$container = new \Dice\Dice;
$container = $container->addRule('*', [
    'substitutions' => [
        // This is where you pass in the instance
        Engine::class => $engine
    ]
]);

$engine->registerContainerHandler(function($class, $params) use ($container) {
    return $container->create($class, $params);
});

// Now you can use the Engine instance in your controllers/middleware

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

    public function index() {
        $this->app->render('index');
    }
}

Adicionando Outras Classes

Se você tiver outras classes que deseja adicionar ao contêiner, com Dice é fácil, pois elas serão resolvidas automaticamente pelo contêiner. Aqui está um exemplo:


$container = new \Dice\Dice;
// If you don't need to inject any dependencies into your classes
// you don't need to define anything!
Flight::registerContainerHandler(function($class, $params) use ($container) {
    return $container->create($class, $params);
});

class MyCustomClass {
    public function parseThing() {
        return 'thing';
    }
}

class UserController {

    protected MyCustomClass $MyCustomClass;

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

    public function index() {
        echo $this->MyCustomClass->parseThing();
    }
}

Flight::route('/user', 'UserController->index');

PSR-11

Flight também pode usar qualquer contêiner compatível com PSR-11. Isso significa que você pode usar qualquer contêiner que implemente a interface PSR-11. Aqui está um exemplo usando o contêiner PSR-11 da League:


require 'vendor/autoload.php';

// same UserController class as above

$container = new \League\Container\Container();
$container->add(UserController::class)->addArgument(PdoWrapper::class);
$container->add(PdoWrapper::class)
    ->addArgument('mysql:host=localhost;dbname=test')
    ->addArgument('user')
    ->addArgument('pass');
Flight::registerContainerHandler($container);

Flight::route('/user', [ 'UserController', 'view' ]);

Flight::start();

Isso pode ser um pouco mais verboso do que o exemplo anterior com Dice, mas ainda cumpre o trabalho com os mesmos benefícios!

Veja Também

Solução de Problemas

Changelog

Learn/middleware

Middleware

Visão Geral

Flight suporta middleware de rota e middleware de grupo de rotas. O middleware é uma parte da sua aplicação onde o código é executado antes (ou depois) do callback da rota. Essa é uma ótima maneira de adicionar verificações de autenticação de API no seu código, ou para validar que o usuário tem permissão para acessar a rota.

Entendendo

O middleware pode simplificar greatly sua app. Em vez de herança complexa de classes abstratas ou sobrescritas de métodos, o middleware permite que você controle suas rotas atribuindo sua lógica de app personalizada a elas. Você pode pensar no middleware como um sanduíche. Você tem pão por fora, e então camadas de ingredientes como alface, tomates, carnes e queijo. Então imagine que cada requisição é como dar uma mordida no sanduíche onde você come as camadas externas primeiro e trabalha seu caminho até o núcleo.

Aqui está uma visualização de como o middleware funciona. Em seguida, mostraremos um exemplo prático de como isso funciona.

Requisição do usuário na URL /api ----> 
    Middleware->before() executado ----->
        Callable/método anexado a /api executado e resposta gerada ------>
    Middleware->after() executado ----->
Usuário recebe resposta do servidor

E aqui está um exemplo prático:

Usuário navega para a URL /dashboard
    LoggedInMiddleware->before() executa
        before() verifica sessão logada válida
            se sim, não faz nada e continua a execução
            se não, redireciona o usuário para /login
                Callable/método anexado a /api executado e resposta gerada
    LoggedInMiddleware->after() não tem nada definido, então deixa a execução continuar
Usuário recebe HTML do dashboard do servidor

Ordem de Execução

As funções de middleware são executadas na ordem em que são adicionadas à rota. A execução é semelhante a como Slim Framework lida com isso.

Os métodos before() são executados na ordem adicionada, e os métodos after() são executados em ordem reversa.

Ex: Middleware1->before(), Middleware2->before(), Middleware2->after(), Middleware1->after().

Uso Básico

Você pode usar middleware como qualquer método callable, incluindo uma função anônima ou uma classe (recomendado)

Função Anônima

Aqui está um exemplo simples:

Flight::route('/path', function() { echo ' Here I am!'; })->addMiddleware(function() {
    echo 'Middleware first!';
});

Flight::start();

// Isso exibirá "Middleware first! Here I am!"

Nota: Ao usar uma função anônima, o único método interpretado é um método before(). Você não pode definir comportamento after() com uma classe anônima.

Usando Classes

O middleware pode (e deve) ser registrado como uma classe. Se você precisar da funcionalidade "after", você deve usar uma classe.

class MyMiddleware {
    public function before($params) {
        echo 'Middleware first!';
    }

    public function after($params) {
        echo 'Middleware last!';
    }
}

$MyMiddleware = new MyMiddleware();
Flight::route('/path', function() { echo ' Here I am! '; })->addMiddleware($MyMiddleware); 
// também ->addMiddleware([ $MyMiddleware, $MyMiddleware2 ]);

Flight::start();

// Isso exibirá "Middleware first! Here I am! Middleware last!"

Você também pode apenas definir o nome da classe de middleware e ela instanciará a classe.

Flight::route('/path', function() { echo ' Here I am! '; })->addMiddleware(MyMiddleware::class);

Nota: Se você passar apenas o nome do middleware, ele será automaticamente executado pelo container de injeção de dependência e o middleware será executado com os parâmetros que precisa. Se você não tiver um container de injeção de dependência registrado, ele passará por padrão a instância de flight\Engine no __construct(Engine $app).

Usando Rotas com Parâmetros

Se você precisar de parâmetros da sua rota, eles serão passados em um único array para a função de middleware. (function($params) { ... } ou public function before($params) { ... }). A razão para isso é que você pode estruturar seus parâmetros em grupos e em alguns desses grupos, seus parâmetros podem aparecer em uma ordem diferente, o que quebraria a função de middleware ao se referir ao parâmetro errado. Dessa forma, você pode acessá-los por nome em vez de posição.

use flight\Engine;

class RouteSecurityMiddleware {

    protected Engine $app;

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

    public function before(array $params) {
        $clientId = $params['clientId'];

        // jobId pode ou não ser passado
        $jobId = $params['jobId'] ?? 0;

        // talvez se não houver ID de job, você não precise buscar nada.
        if($jobId === 0) {
            return;
        }

        // execute uma busca de algum tipo no seu banco de dados
        $isValid = !!$this->app->db()->fetchField("SELECT 1 FROM client_jobs WHERE client_id = ? AND job_id = ?", [ $clientId, $jobId ]);

        if($isValid !== true) {
            $this->app->halt(400, 'You are blocked, muahahaha!');
        }
    }
}

// routes.php
$router->group('/client/@clientId/job/@jobId', function(Router $router) {

    // Este grupo abaixo ainda recebe o middleware do pai
    // Mas os parâmetros são passados em um único array 
    // no middleware.
    $router->group('/job/@jobId', function(Router $router) {
        $router->get('', [ JobController::class, 'view' ]);
        $router->put('', [ JobController::class, 'update' ]);
        $router->delete('', [ JobController::class, 'delete' ]);
        // mais rotas...
    });
}, [ RouteSecurityMiddleware::class ]);

Agrupando Rotas com Middleware

Você pode adicionar um grupo de rota, e então toda rota nesse grupo terá o mesmo middleware também. Isso é útil se você precisar agrupar um monte de rotas por, digamos, um middleware de Auth para verificar a chave de API no header.


// adicionado no final do método de grupo
Flight::group('/api', function() {

    // Esta rota "vazia" na verdade corresponderá a /api
    Flight::route('', function() { echo 'api'; }, false, 'api');
    // Isso corresponderá a /api/users
    Flight::route('/users', function() { echo 'users'; }, false, 'users');
    // Isso corresponderá a /api/users/1234
    Flight::route('/users/@id', function($id) { echo 'user:'.$id; }, false, 'user_view');
}, [ new ApiAuthMiddleware() ]);

Se você quiser aplicar um middleware global a todas as suas rotas, você pode adicionar um grupo "vazio":


// adicionado no final do método de grupo
Flight::group('', function() {

    // Isso ainda é /users
    Flight::route('/users', function() { echo 'users'; }, false, 'users');
    // E isso ainda é /users/1234
    Flight::route('/users/@id', function($id) { echo 'user:'.$id; }, false, 'user_view');
}, [ ApiAuthMiddleware::class ]); // ou [ new ApiAuthMiddleware() ], mesma coisa

Casos de Uso Comuns

Validação de Chave de API

Se você quiser proteger suas rotas /api verificando se a chave de API está correta, você pode lidar com isso facilmente com middleware.

use flight\Engine;

class ApiMiddleware {

    protected Engine $app;

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

    public function before(array $params) {
        $authorizationHeader = $this->app->request()->getHeader('Authorization');
        $apiKey = str_replace('Bearer ', '', $authorizationHeader);

        // faça uma busca no seu banco de dados pela chave de api
        $apiKeyHash = hash('sha256', $apiKey);
        $hasValidApiKey = !!$this->db()->fetchField("SELECT 1 FROM api_keys WHERE hash = ? AND valid_date >= NOW()", [ $apiKeyHash ]);

        if($hasValidApiKey !== true) {
            $this->app->jsonHalt(['error' => 'Invalid API Key']);
        }
    }
}

// routes.php
$router->group('/api', function(Router $router) {
    $router->get('/users', [ ApiController::class, 'getUsers' ]);
    $router->get('/companies', [ ApiController::class, 'getCompanies' ]);
    // mais rotas...
}, [ ApiMiddleware::class ]);

Agora todas as suas rotas de API estão protegidas por este middleware de validação de chave de API que você configurou! Se você adicionar mais rotas ao grupo do roteador, elas terão instantaneamente a mesma proteção!

Validação de Login

Você quer proteger algumas rotas para que estejam disponíveis apenas para usuários logados? Isso pode ser facilmente alcançado com middleware!

use flight\Engine;

class LoggedInMiddleware {

    protected Engine $app;

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

    public function before(array $params) {
        $session = $this->app->session();
        if($session->get('logged_in') !== true) {
            $this->app->redirect('/login');
            exit;
        }
    }
}

// routes.php
$router->group('/admin', function(Router $router) {
    $router->get('/dashboard', [ DashboardController::class, 'index' ]);
    $router->get('/clients', [ ClientController::class, 'index' ]);
    // mais rotas...
}, [ LoggedInMiddleware::class ]);

Validação de Parâmetro de Rota

Você quer proteger seus usuários de alterar valores na URL para acessar dados que não deveriam? Isso pode ser resolvido com middleware!

use flight\Engine;

class RouteSecurityMiddleware {

    protected Engine $app;

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

    public function before(array $params) {
        $clientId = $params['clientId'];
        $jobId = $params['jobId'];

        // execute uma busca de algum tipo no seu banco de dados
        $isValid = !!$this->app->db()->fetchField("SELECT 1 FROM client_jobs WHERE client_id = ? AND job_id = ?", [ $clientId, $jobId ]);

        if($isValid !== true) {
            $this->app->halt(400, 'You are blocked, muahahaha!');
        }
    }
}

// routes.php
$router->group('/client/@clientId/job/@jobId', function(Router $router) {
    $router->get('', [ JobController::class, 'view' ]);
    $router->put('', [ JobController::class, 'update' ]);
    $router->delete('', [ JobController::class, 'delete' ]);
    // mais rotas...
}, [ RouteSecurityMiddleware::class ]);

Lidando com a Execução de Middleware

Digamos que você tenha um middleware de autenticação e queira redirecionar o usuário para uma página de login se ele não estiver autenticado. Você tem algumas opções à sua disposição:

  1. Você pode retornar false da função de middleware e Flight retornará automaticamente um erro 403 Forbidden, mas sem customização.
  2. Você pode redirecionar o usuário para uma página de login usando Flight::redirect().
  3. Você pode criar um erro customizado dentro do middleware e interromper a execução da rota.

Simples e Direto

Aqui está um exemplo simples de return false; :

class MyMiddleware {
    public function before($params) {
        $hasUserKey = Flight::session()->exists('user');
        if ($hasUserKey === false) {
            return false;
        }

        // como é true, tudo continua
    }
}

Exemplo de Redirecionamento

Aqui está um exemplo de redirecionar o usuário para uma página de login:

class MyMiddleware {
    public function before($params) {
        $hasUserKey = Flight::session()->exists('user');
        if ($hasUserKey === false) {
            Flight::redirect('/login');
            exit;
        }
    }
}

Exemplo de Erro Customizado

Digamos que você precise lançar um erro JSON porque está construindo uma API. Você pode fazer isso assim:

class MyMiddleware {
    public function before($params) {
        $authorization = Flight::request()->getHeader('Authorization');
        if(empty($authorization)) {
            Flight::jsonHalt(['error' => 'You must be logged in to access this page.'], 403);
            // ou
            Flight::json(['error' => 'You must be logged in to access this page.'], 403);
            exit;
            // ou
            Flight::halt(403, json_encode(['error' => 'You must be logged in to access this page.']);
        }
    }
}

Veja Também

Solução de Problemas

Changelog

Learn/filtering

Filtragem

Visão Geral

O Flight permite que você filtre métodos mapeados antes e depois de serem chamados.

Entendendo

Não há ganchos predefinidos que você precise memorizar. Você pode filtrar qualquer um dos métodos padrão do framework, bem como qualquer método personalizado que você tenha mapeado.

Uma função de filtro se parece com esta:

/**
 * @param array $params Os parâmetros passados para o método sendo filtrado.
 * @param string $output (apenas buffer de saída v2) A saída do método sendo filtrado.
 * @return bool Retorne true/void ou não retorne para continuar a cadeia, false para quebrar a cadeia.
 */
function (array &$params, string &$output): bool {
  // Código do filtro
}

Usando as variáveis passadas, você pode manipular os parâmetros de entrada e/ou a saída.

Você pode fazer um filtro executar antes de um método fazendo:

Flight::before('start', function (array &$params, string &$output): bool {
  // Faça algo
});

Você pode fazer um filtro executar depois de um método fazendo:

Flight::after('start', function (array &$params, string &$output): bool {
  // Faça algo
});

Você pode adicionar quantos filtros quiser a qualquer método. Eles serão chamados na ordem em que são declarados.

Aqui está um exemplo do processo de filtragem:

// Mapeie um método personalizado
Flight::map('hello', function (string $name) {
  return "Olá, $name!";
});

// Adicione um filtro antes
Flight::before('hello', function (array &$params, string &$output): bool {
  // Manipule o parâmetro
  $params[0] = 'Fred';
  return true;
});

// Adicione um filtro depois
Flight::after('hello', function (array &$params, string &$output): bool {
  // Manipule a saída
  $output .= " Tenha um bom dia!";
  return true;
});

// Invoque o método personalizado
echo Flight::hello('Bob');

Isso deve exibir:

Olá Fred! Tenha um bom dia!

Se você tiver definido múltiplos filtros, você pode quebrar a cadeia retornando false em qualquer uma de suas funções de filtro:

Flight::before('start', function (array &$params, string &$output): bool {
  echo 'um';
  return true;
});

Flight::before('start', function (array &$params, string &$output): bool {
  echo 'dois';

  // Isso encerrará a cadeia
  return false;
});

// Isso não será chamado
Flight::before('start', function (array &$params, string &$output): bool {
  echo 'três';
  return true;
});

Nota: Métodos principais como map e register não podem ser filtrados porque são chamados diretamente e não invocados dinamicamente. Veja Estendendo o Flight para mais informações.

Veja Também

Solução de Problemas

Registro de Alterações

Learn/requests

Requests

Visão Geral

Flight encapsula a requisição HTTP em um único objeto, que pode ser acessado fazendo:

$request = Flight::request();

Compreendendo

As requisições HTTP são um dos aspectos principais a entender sobre o ciclo de vida HTTP. Um usuário realiza uma ação em um navegador web ou em um cliente HTTP, e eles enviam uma série de cabeçalhos, corpo, URL, etc. para o seu projeto. Você pode capturar esses cabeçalhos (a linguagem do navegador, que tipo de compressão eles podem lidar, o agente do usuário, etc.) e capturar o corpo e a URL que são enviados para a sua aplicação Flight. Essas requisições são essenciais para que o seu app entenda o que fazer em seguida.

Uso Básico

PHP possui vários super globais, incluindo $_GET, $_POST, $_REQUEST, $_SERVER, $_FILES e $_COOKIE. Flight abstrai esses em coleções práticas Collections. Você pode acessar as propriedades query, data, cookies e files como arrays ou objetos.

Nota: É ALTAMENTE desaconselhável usar esses super globais no seu projeto e eles devem ser referenciados através do objeto request().

Nota: Não há abstração disponível para $_ENV.

$_GET

Você pode acessar o array $_GET via a propriedade query:

// GET /search?keyword=something
Flight::route('/search', function(){
    $keyword = Flight::request()->query['keyword'];
    // ou
    $keyword = Flight::request()->query->keyword;
    echo "Você está procurando por: $keyword";
    // consultar um banco de dados ou algo mais com o $keyword
});

$_POST

Você pode acessar o array $_POST via a propriedade data:

Flight::route('POST /submit', function(){
    $name = Flight::request()->data['name'];
    $email = Flight::request()->data['email'];
    // ou
    $name = Flight::request()->data->name;
    $email = Flight::request()->data->email;
    echo "Você enviou: $name, $email";
    // salvar em um banco de dados ou algo mais com o $name e $email
});

$_COOKIE

Você pode acessar o array $_COOKIE via a propriedade cookies:

Flight::route('GET /login', function(){
    $savedLogin = Flight::request()->cookies['myLoginCookie'];
    // ou
    $savedLogin = Flight::request()->cookies->myLoginCookie;
    // verificar se foi realmente salvo ou não e se foi, fazer login automático
    if($savedLogin) {
        Flight::redirect('/dashboard');
        return;
    }
});

Para ajuda em definir novos valores de cookie, veja overclokk/cookie

$_SERVER

Há um atalho disponível para acessar o array $_SERVER via o método getVar():


$host = Flight::request()->getVar('HTTP_HOST');

$_FILES

Você pode acessar arquivos enviados via a propriedade files:

// acesso raw à propriedade $_FILES. Veja abaixo para a abordagem recomendada
$uploadedFile = Flight::request()->files['myFile']; 
// ou
$uploadedFile = Flight::request()->files->myFile;

Veja Uploaded File Handler para mais informações.

Processando Uploads de Arquivos

v3.12.0

Você pode processar uploads de arquivos usando o framework com alguns métodos auxiliares. Basicamente, isso se resume a extrair os dados do arquivo da requisição e movê-lo para um novo local.

Flight::route('POST /upload', function(){
    // Se você tivesse um campo de entrada como <input type="file" name="myFile">
    $uploadedFileData = Flight::request()->getUploadedFiles();
    $uploadedFile = $uploadedFileData['myFile'];
    $uploadedFile->moveTo('/path/to/uploads/' . $uploadedFile->getClientFilename());
});

Se você tiver múltiplos arquivos enviados, você pode iterar por eles:

Flight::route('POST /upload', function(){
    // Se você tivesse um campo de entrada como <input type="file" name="myFiles[]">
    $uploadedFiles = Flight::request()->getUploadedFiles()['myFiles'];
    foreach ($uploadedFiles as $uploadedFile) {
        $uploadedFile->moveTo('/path/to/uploads/' . $uploadedFile->getClientFilename());
    }
});

Nota de Segurança: Sempre valide e sanitize a entrada do usuário, especialmente ao lidar com uploads de arquivos. Sempre valide o tipo de extensões que você permitirá ser enviado, mas você também deve validar os "magic bytes" do arquivo para garantir que é realmente o tipo de arquivo que o usuário afirma que é. Há artigos e bibliotecas disponíveis para ajudar com isso.

Corpo da Requisição

Para obter o corpo raw da requisição HTTP, por exemplo ao lidar com requisições POST/PUT, você pode fazer:

Flight::route('POST /users/xml', function(){
    $xmlBody = Flight::request()->getBody();
    // faça algo com o XML que foi enviado.
});

Corpo JSON

Se você receber uma requisição com o tipo de conteúdo application/json e os dados de exemplo {"id": 123} ele estará disponível na propriedade data:

$id = Flight::request()->data->id;

Cabeçalhos da Requisição

Você pode acessar os cabeçalhos da requisição usando o método getHeader() ou getHeaders():


// Talvez você precise do cabeçalho Authorization
$host = Flight::request()->getHeader('Authorization');
// ou
$host = Flight::request()->header('Authorization');

// Se você precisar pegar todos os cabeçalhos
$headers = Flight::request()->getHeaders();
// ou
$headers = Flight::request()->headers();

Método da Requisição

Você pode acessar o método da requisição usando a propriedade method ou o método getMethod():

$method = Flight::request()->method; // na verdade populado pelo getMethod()
$method = Flight::request()->getMethod();

Nota: O método getMethod() primeiro puxa o método de $_SERVER['REQUEST_METHOD'], então ele pode ser sobrescrito por $_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'] se existir ou $_REQUEST['_method'] se existir.

Propriedades do Objeto Request

O objeto request fornece as seguintes propriedades:

Métodos Auxiliares

Há alguns métodos auxiliares para juntar partes de uma URL, ou lidar com certos cabeçalhos.

URL Completa

Você pode acessar a URL completa da requisição usando o método getFullUrl():

$url = Flight::request()->getFullUrl();
// https://example.com/some/path?foo=bar

URL Base

Você pode acessar a URL base usando o método getBaseUrl():

// http://example.com/path/to/something/cool?query=yes+thanks
$url = Flight::request()->getBaseUrl();
// https://example.com
// Note, sem barra no final.

Análise de Query

Você pode passar uma URL para o método parseQuery() para analisar a string de query em um array associativo:

$query = Flight::request()->parseQuery('https://example.com/some/path?foo=bar');
// ['foo' => 'bar']

Negociar Tipos de Conteúdo Aceitos

v3.17.2

Você pode usar o método negotiateContentType() para determinar o melhor tipo de conteúdo para responder com base no cabeçalho Accept enviado pelo cliente.


// Exemplo de cabeçalho Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8
// O abaixo define o que você suporta.
$availableTypes = ['application/json', 'application/xml'];
$typeToServe = Flight::request()->negotiateContentType($availableTypes);
if ($typeToServe === 'application/json') {
    // Sirva resposta JSON
} elseif ($typeToServe === 'application/xml') {
    // Sirva resposta XML
} else {
    // Padrão para algo mais ou lance um erro
}

Nota: Se nenhum dos tipos disponíveis for encontrado no cabeçalho Accept, o método retornará null. Se não houver cabeçalho Accept definido, o método retornará o primeiro tipo no array $availableTypes.

Veja Também

Solução de Problemas

Changelog

Learn/why_frameworks

Por que um Framework?

Alguns programadores são veementemente contra o uso de frameworks. Eles argumentam que os frameworks são inflados, lentos e difíceis de aprender. Dizem que os frameworks são desnecessários e que você pode escrever um código melhor sem eles. Certamente, há alguns pontos válidos a serem considerados sobre as desvantagens do uso de frameworks. No entanto, também existem muitas vantagens em usar frameworks.

Motivos para Usar um Framework

Aqui estão algumas razões pelas quais você pode querer considerar o uso de um framework:

Flight é um micro-framework. Isso significa que ele é pequeno e leve. Ele não fornece tanta funcionalidade quanto frameworks maiores como Laravel ou Symfony. No entanto, ele fornece muita da funcionalidade necessária para construir aplicações web. É também fácil de aprender e usar. Isso o torna uma boa escolha para construir aplicações web rapidamente e facilmente. Se você é novo em frameworks, o Flight é um ótimo framework para iniciantes a começar. Vai ajudá-lo a entender as vantagens de usar frameworks sem sobrecarregá-lo com muita complexidade. Depois de adquirir alguma experiência com o Flight, será mais fácil passar para frameworks mais complexos como Laravel ou Symfony, no entanto, o Flight ainda pode criar um aplicativo robusto e bem-sucedido.

O Que é Roteamento?

O roteamento é o núcleo do framework Flight, mas o que é exatamente? Roteamento é o processo de pegar uma URL e correspondê-la a uma função específica em seu código. É assim que você pode fazer seu site fazer coisas diferentes com base na URL solicitada. Por exemplo, você pode querer mostrar o perfil de um usuário quando ele visita /user/1234, mas mostrar uma lista de todos os usuários quando eles visitam /users. Tudo isso é feito por meio do roteamento.

Pode funcionar algo assim:

E Por que é Importante?

Ter um roteador centralizado apropriado pode realmente tornar sua vida dramaticamente mais fácil! Pode ser difícil ver isso à primeira vista. Aqui estão algumas razões:

Tenho certeza de que você está familiarizado com a maneira script por script de criar um site. Você pode ter um arquivo chamado index.php que possui um monte de declarações if para verificar a URL e em seguida executar uma função específica com base na URL. Isso é uma forma de roteamento, mas não é muito organizado e pode sair do controle rapidamente. O sistema de roteamento do Flight é uma maneira muito mais organizada e poderosa de lidar com o roteamento.

Isto?


// /user/view_profile.php?id=1234
if ($_GET['id']) {
    $id = $_GET['id'];
    viewUserProfile($id);
}

// /user/edit_profile.php?id=1234
if ($_GET['id']) {
    $id = $_GET['id'];
    editUserProfile($id);
}

// etc...

Ou isso?


// index.php
Flight::route('/user/@id', [ 'ControladorDeUsuario', 'verPerfilDoUsuario' ]);
Flight::route('/user/@id/edit', [ 'ControladorDeUsuario', 'editarPerfilDoUsuario' ]);

// Em talvez o seu app/controllers/ControladorDeUsuario.php
class ControladorDeUsuario {
    public function verPerfilDoUsuario($id) {
        // faça algo
    }

    public function editarPerfilDoUsuario($id) {
        // faça algo
    }
}

Espero que você comece a ver os benefícios de usar um sistema de roteamento centralizado. É muito mais fácil de gerenciar e entender a longo prazo!

Solicitações e Respostas

O Flight oferece uma maneira simples e fácil de lidar com solicitações e respostas. Este é o núcleo do que um framework web faz. Ele recebe uma solicitação de um navegador de um usuário, a processa e envia de volta uma resposta. Com isso, você pode construir aplicações web que realizem tarefas como mostrar o perfil de um usuário, permitir que um usuário faça login, ou permitir que um usuário poste uma nova postagem em um blog.

Solicitações

Uma solicitação é o que o navegador de um usuário envia para o seu servidor quando eles visitam o seu site. Esta solicitação contém informações sobre o que o usuário quer fazer. Por exemplo, ela pode conter informações sobre qual URL o usuário deseja visitar, quais dados o usuário deseja enviar para o seu servidor, ou que tipo de dados o usuário deseja receber do seu servidor. É importante saber que uma solicitação é somente leitura. Você não pode alterar a solicitação, mas pode lê-la.

O Flight fornece uma maneira simples de acessar informações sobre a solicitação. Você pode acessar informações sobre a solicitação usando o método Flight::request(). Este método retorna um objeto Request que contém informações sobre a solicitação. Você pode usar esse objeto para acessar informações sobre a solicitação, como a URL, o método, ou os dados que o usuário enviou para o seu servidor.

Respostas

Uma resposta é o que o seu servidor envia de volta para o navegador de um usuário quando eles visitam o seu site. Esta resposta contém informações sobre o que o seu servidor quer fazer. Por exemplo, ela pode conter informações sobre que tipo de dados o seu servidor quer enviar para o usuário, que tipo de dados seu servidor quer receber do usuário, ou que tipo de dados seu servidor quer armazenar no computador do usuário.

O Flight fornece uma maneira simples de enviar uma resposta para o navegador do usuário. Você pode enviar uma resposta usando o método Flight::response(). Este método recebe um objeto Response como argumento e envia a resposta para o navegador do usuário. Você pode usar este objeto para enviar uma resposta para o navegador do usuário, como HTML, JSON, ou um arquivo. O Flight ajuda a gerar automaticamente algumas partes da resposta para facilitar as coisas, mas, em última instância, você tem controle sobre o que enviar de volta para o usuário.

Learn/responses

Respostas

Visão Geral

Flight ajuda a gerar parte dos cabeçalhos de resposta para você, mas você mantém a maior parte do controle sobre o que envia de volta ao usuário. Na maioria das vezes, você acessará o objeto response() diretamente, mas Flight tem alguns métodos auxiliares para definir alguns dos cabeçalhos de resposta para você.

Entendendo

Após o usuário enviar sua request para sua aplicação, você precisa gerar uma resposta apropriada para eles. Eles enviaram informações como a linguagem que preferem, se podem lidar com certos tipos de compressão, seu agente de usuário, etc., e após processar tudo, é hora de enviar de volta uma resposta apropriada. Isso pode ser definir cabeçalhos, produzir um corpo de HTML ou JSON para eles, ou redirecioná-los para uma página.

Uso Básico

Enviando um Corpo de Resposta

Flight usa ob_start() para armazenar em buffer a saída. Isso significa que você pode usar echo ou print para enviar uma resposta ao usuário e Flight a capturará e a enviará de volta ao usuário com os cabeçalhos apropriados.


// Isso enviará "Hello, World!" para o navegador do usuário
Flight::route('/', function() {
    echo "Hello, World!";
});

// HTTP/1.1 200 OK
// Content-Type: text/html
//
// Hello, World!

Como alternativa, você pode chamar o método write() para adicionar ao corpo também.


// Isso enviará "Hello, World!" para o navegador do usuário
Flight::route('/', function() {
    // verboso, mas faz o trabalho às vezes quando você precisa
    Flight::response()->write("Hello, World!");

    // se você quiser recuperar o corpo que definiu neste ponto
    // você pode fazer assim
    $body = Flight::response()->getBody();
});

JSON

Flight fornece suporte para enviar respostas JSON e JSONP. Para enviar uma resposta JSON, você passa alguns dados para serem codificados em JSON:

Flight::route('/@companyId/users', function(int $companyId) {
    // de alguma forma, extraia seus usuários de um banco de dados, por exemplo
    $users = Flight::db()->fetchAll("SELECT id, first_name, last_name FROM users WHERE company_id = ?", [ $companyId ]);

    Flight::json($users);
});
// [{"id":1,"first_name":"Bob","last_name":"Jones"}, /* more users */ ]

Nota: Por padrão, Flight enviará um cabeçalho Content-Type: application/json com a resposta. Ele também usará as flags JSON_THROW_ON_ERROR e JSON_UNESCAPED_SLASHES ao codificar o JSON.

JSON com Código de Status

Você também pode passar um código de status como o segundo argumento:

Flight::json(['id' => 123], 201);

JSON com Impressão Bonita

Você também pode passar um argumento na última posição para ativar a impressão bonita:

Flight::json(['id' => 123], 200, true, 'utf-8', JSON_PRETTY_PRINT);

Alterando a Ordem dos Argumentos JSON

Flight::json() é um método muito antigo, mas o objetivo do Flight é manter a compatibilidade retroativa para projetos. Na verdade, é muito simples se você quiser refazer a ordem dos argumentos para usar uma sintaxe mais simples, você pode apenas remapear o método JSON como qualquer outro método do Flight:

Flight::map('json', function($data, $code = 200, $options = 0) {

    // agora você não precisa de `true, 'utf-8'` ao usar o método json()!
    Flight::_json($data, $code, true, 'utf-8', $options);
}

// E agora pode ser usado assim
Flight::json(['id' => 123], 200, JSON_PRETTY_PRINT);

JSON e Parando a Execução

v3.10.0

Se você quiser enviar uma resposta JSON e parar a execução, você pode usar o método jsonHalt(). Isso é útil para casos em que você está verificando talvez algum tipo de autorização e se o usuário não estiver autorizado, você pode enviar uma resposta JSON imediatamente, limpar o conteúdo do corpo existente e parar a execução.

Flight::route('/users', function() {
    $authorized = someAuthorizationCheck();
    // Verifica se o usuário está autorizado
    if($authorized === false) {
        Flight::jsonHalt(['error' => 'Unauthorized'], 401);
        // sem exit; necessário aqui.
    }

    // Continua com o resto da rota
});

Antes da v3.10.0, você teria que fazer algo assim:

Flight::route('/users', function() {
    $authorized = someAuthorizationCheck();
    // Verifica se o usuário está autorizado
    if($authorized === false) {
        Flight::halt(401, json_encode(['error' => 'Unauthorized']));
    }

    // Continua com o resto da rota
});

Limpando um Corpo de Resposta

Se você quiser limpar o corpo da resposta, você pode usar o método clearBody:

Flight::route('/', function() {
    if($someCondition) {
        Flight::response()->write("Hello, World!");
    } else {
        Flight::response()->clearBody();
    }
});

O caso de uso acima provavelmente não é comum, no entanto, poderia ser mais comum se isso fosse usado em um middleware.

Executando um Callback no Corpo da Resposta

Você pode executar um callback no corpo da resposta usando o método addResponseBodyCallback:

Flight::route('/users', function() {
    $db = Flight::db();
    $users = $db->fetchAll("SELECT * FROM users");
    Flight::render('users_table', ['users' => $users]);
});

// Isso fará gzip em todas as respostas para qualquer rota
Flight::response()->addResponseBodyCallback(function($body) {
    return gzencode($body, 9);
});

Você pode adicionar múltiplos callbacks e eles serão executados na ordem em que foram adicionados. Como isso pode aceitar qualquer callable, pode aceitar um array de classe [ $class, 'method' ], uma closure $strReplace = function($body) { str_replace('hi', 'there', $body); };, ou um nome de função 'minify' se você tivesse uma função para minificar seu código HTML, por exemplo.

Nota: Callbacks de rota não funcionarão se você estiver usando a opção de configuração flight.v2.output_buffering.

Callback de Rota Específica

Se você quisesse que isso se aplicasse apenas a uma rota específica, poderia adicionar o callback na própria rota:

Flight::route('/users', function() {
    $db = Flight::db();
    $users = $db->fetchAll("SELECT * FROM users");
    Flight::render('users_table', ['users' => $users]);

    // Isso fará gzip apenas na resposta desta rota
    Flight::response()->addResponseBodyCallback(function($body) {
        return gzencode($body, 9);
    });
});

Opção de Middleware

Você também pode usar middleware para aplicar o callback a todas as rotas via middleware:

// MinifyMiddleware.php
class MinifyMiddleware {
    public function before() {
        // Aplique o callback aqui no objeto response().
        Flight::response()->addResponseBodyCallback(function($body) {
            return $this->minify($body);
        });
    }

    protected function minify(string $body): string {
        // minifique o corpo de alguma forma
        return $body;
    }
}

// index.php
Flight::group('/users', function() {
    Flight::route('', function() { /* ... */ });
    Flight::route('/@id', function($id) { /* ... */ });
}, [ new MinifyMiddleware() ]);

Códigos de Status

Você pode definir o código de status da resposta usando o método status:

Flight::route('/@id', function($id) {
    if($id == 123) {
        Flight::response()->status(200);
        echo "Hello, World!";
    } else {
        Flight::response()->status(403);
        echo "Forbidden";
    }
});

Se você quiser obter o código de status atual, pode usar o método status sem argumentos:

Flight::response()->status(); // 200

Definindo um Cabeçalho de Resposta

Você pode definir um cabeçalho, como o tipo de conteúdo da resposta, usando o método header:

// Isso enviará "Hello, World!" para o navegador do usuário em texto plano
Flight::route('/', function() {
    Flight::response()->header('Content-Type', 'text/plain');
    // ou
    Flight::response()->setHeader('Content-Type', 'text/plain');
    echo "Hello, World!";
});

Redirecionamento

Você pode redirecionar a solicitação atual usando o método redirect() e passando uma nova URL:

Flight::route('/login', function() {
    $username = Flight::request()->data->username;
    $password = Flight::request()->data->password;
    $passwordConfirm = Flight::request()->data->password_confirm;

    if($password !== $passwordConfirm) {
        Flight::redirect('/new/location');
        return; // isso é necessário para que a funcionalidade abaixo não execute
    }

    // adicione o novo usuário...
    Flight::db()->runQuery("INSERT INTO users ....");
    Flight::redirect('/admin/dashboard');
});

Nota: Por padrão, Flight envia um código de status HTTP 303 ("See Other"). Você pode opcionalmente definir um código personalizado:

Flight::redirect('/new/location', 301); // permanente

Parando a Execução da Rota

Você pode parar o framework e sair imediatamente em qualquer ponto chamando o método halt:

Flight::halt();

Você também pode especificar um código de status HTTP opcional e mensagem:

Flight::halt(200, 'Be right back...');

Chamar halt descartará qualquer conteúdo de resposta até aquele ponto e parará toda a execução. Se você quiser parar o framework e produzir a resposta atual, use o método stop:

Flight::stop($httpStatusCode = null);

Nota: Flight::stop() tem algum comportamento estranho, como produzir a resposta, mas continuar executando seu script, o que pode não ser o que você deseja. Você pode usar exit ou return após chamar Flight::stop() para prevenir execução adicional, mas geralmente é recomendado usar Flight::halt().

Isso salvará a chave e o valor do cabeçalho no objeto de resposta. No final do ciclo de vida da solicitação, ele construirá os cabeçalhos e enviará uma resposta.

Uso Avançado

Enviando um Cabeçalho Imediatamente

Pode haver momentos em que você precisa fazer algo personalizado com o cabeçalho e precisa enviar o cabeçalho na própria linha de código com a qual está trabalhando. Se você estiver definindo uma rota transmitida, isso é o que você precisaria. Isso é alcançável através de response()->setRealHeader().

Flight::route('/', function() {
    Flight::response()->setRealHeader('Content-Type: text/plain');
    echo 'Streaming response...';
    sleep(5);
    echo 'Done!';
})->stream();

JSONP

Para solicitações JSONP, você pode opcionalmente passar o nome do parâmetro de consulta que está usando para definir sua função de callback:

Flight::jsonp(['id' => 123], 'q');

Então, ao fazer uma solicitação GET usando ?q=my_func, você deve receber a saída:

my_func({"id":123});

Se você não passar um nome de parâmetro de consulta, ele usará jsonp por padrão.

Nota: Se você ainda estiver usando solicitações JSONP em 2025 e além, entre no chat e nos diga por quê! Adoramos ouvir algumas boas histórias de batalha/horror!

Limpando Dados de Resposta

Você pode limpar o corpo da resposta e cabeçalhos usando o método clear(). Isso limpará quaisquer cabeçalhos atribuídos à resposta, limpará o corpo da resposta e definirá o código de status para 200.

Flight::response()->clear();

Limpando Apenas o Corpo da Resposta

Se você quiser limpar apenas o corpo da resposta, pode usar o método clearBody():

// Isso ainda manterá quaisquer cabeçalhos definidos no objeto response().
// Isso ainda manterá quaisquer cabeçalhos definidos no objeto response().
Flight::response()->clearBody();

Cache HTTP

Flight fornece suporte integrado para cache no nível HTTP. Se a condição de cache for atendida, Flight retornará uma resposta HTTP 304 Not Modified. Na próxima vez que o cliente solicitar o mesmo recurso, eles serão solicitados a usar sua versão em cache local.

Cache no Nível de Rota

Se você quiser armazenar em cache toda a sua resposta, pode usar o método cache() e passar o tempo para cache.


// Isso armazenará em cache a resposta por 5 minutos
Flight::route('/news', function () {
  Flight::response()->cache(time() + 300);
  echo 'This content will be cached.';
});

// Alternativamente, você pode usar uma string que passaria
// para o método strtotime()
Flight::route('/news', function () {
  Flight::response()->cache('+5 minutes');
  echo 'This content will be cached.';
});

Last-Modified

Você pode usar o método lastModified e passar um timestamp UNIX para definir a data e hora em que uma página foi modificada pela última vez. O cliente continuará usando seu cache até que o valor da última modificação seja alterado.

Flight::route('/news', function () {
  Flight::lastModified(1234567890);
  echo 'This content will be cached.';
});

ETag

O cache ETag é semelhante ao Last-Modified, exceto que você pode especificar qualquer ID que desejar para o recurso:

Flight::route('/news', function () {
  Flight::etag('my-unique-id');
  echo 'This content will be cached.';
});

Tenha em mente que chamar lastModified ou etag definirá e verificará o valor do cache. Se o valor do cache for o mesmo entre as solicitações, Flight enviará imediatamente uma resposta HTTP 304 e parará o processamento.

Baixar um Arquivo

v3.12.0

Há um método auxiliar para transmitir um arquivo ao usuário final. Você pode usar o método download e passar o caminho.

Flight::route('/download', function () {
  Flight::download('/path/to/file.txt');
  // A partir da v3.17.1, você pode especificar um nome de arquivo personalizado para o download
  Flight::download('/path/to/file.txt', 'custom_name.txt');
});

Veja Também

Solução de Problemas

Changelog

Learn/events

Gerenciador de Eventos

a partir da v3.15.0

Visão Geral

Os eventos permitem que você registre e dispare comportamentos personalizados em sua aplicação. Com a adição de Flight::onEvent() e Flight::triggerEvent(), você pode agora se conectar a momentos chave do ciclo de vida da sua aplicação ou definir seus próprios eventos (como notificações e e-mails) para tornar seu código mais modular e extensível. Esses métodos fazem parte dos métodos mapeáveis da Flight, o que significa que você pode sobrescrever seu comportamento para atender às suas necessidades.

Entendendo

Os eventos permitem que você separe diferentes partes da sua aplicação para que elas não dependam excessivamente umas das outras. Essa separação — frequentemente chamada de desacoplamento — torna seu código mais fácil de atualizar, estender ou depurar. Em vez de escrever tudo em um grande bloco, você pode dividir sua lógica em peças menores e independentes que respondem a ações específicas (eventos).

Imagine que você está construindo uma aplicação de blog:

Sem eventos, você enfiaria tudo isso em uma única função. Com eventos, você pode dividi-lo: uma parte salva o comentário, outra dispara um evento como 'comment.posted', e ouvintes separados lidam com o e-mail e o registro. Isso mantém seu código mais limpo e permite que você adicione ou remova recursos (como notificações) sem tocar na lógica principal.

Casos de Uso Comuns

Na maior parte do tempo, os eventos são bons para coisas que são opcionais, mas não uma parte absolutamente central do seu sistema. Por exemplo, os seguintes são bons de ter, mas se eles falharem por algum motivo, sua aplicação ainda deve funcionar:

No entanto, digamos que você tenha um recurso de esquecimento de senha. Isso deve fazer parte da funcionalidade principal e não ser um evento, porque se esse e-mail não for enviado, o usuário não pode redefinir a senha e usar sua aplicação.

Uso Básico

O sistema de eventos da Flight é construído em torno de dois métodos principais: Flight::onEvent() para registrar ouvintes de eventos e Flight::triggerEvent() para disparar eventos. Aqui está como você pode usá-los:

Registrando Ouvintes de Eventos

Para escutar um evento, use Flight::onEvent(). Esse método permite que você defina o que deve acontecer quando um evento ocorre.

Flight::onEvent(string $event, callable $callback): void

Você "se inscreve" em um evento ao dizer à Flight o que fazer quando ele acontece. O callback pode aceitar argumentos passados do disparo do evento.

O sistema de eventos da Flight é síncrono, o que significa que cada ouvinte de evento é executado em sequência, um após o outro. Quando você dispara um evento, todos os ouvintes registrados para esse evento serão executados até o fim antes que seu código continue. Isso é importante de entender, pois difere de sistemas de eventos assíncronos onde os ouvintes podem rodar em paralelo ou em um momento posterior.

Exemplo Simples

Flight::onEvent('user.login', function ($username) {
    echo "Bem-vindo de volta, $username!";

    // você pode enviar um e-mail se o login for de um novo local
});

Aqui, quando o evento 'user.login' é disparado, ele cumprimentará o usuário pelo nome e também pode incluir lógica para enviar um e-mail se necessário.

Nota: O callback pode ser uma função, uma função anônima ou um método de uma classe.

Disparando Eventos

Para fazer um evento acontecer, use Flight::triggerEvent(). Isso diz à Flight para executar todos os ouvintes registrados para esse evento, passando qualquer dado que você fornecer.

Flight::triggerEvent(string $event, ...$args): void

Exemplo Simples

$username = 'alice';
Flight::triggerEvent('user.login', $username);

Isso dispara o evento 'user.login' e envia 'alice' para o ouvinte que definimos anteriormente, o que exibirá: Welcome back, alice!.

Parando Eventos

Se um ouvinte retornar false, nenhum ouvinte adicional para esse evento será executado. Isso permite que você pare a cadeia de eventos com base em condições específicas. Lembre-se, a ordem dos ouvintes importa, pois o primeiro a retornar false impedirá o resto de rodar.

Exemplo:

Flight::onEvent('user.login', function ($username) {
    if (isBanned($username)) {
        logoutUser($username);
        return false; // Para ouvintes subsequentes
    }
});
Flight::onEvent('user.login', function ($username) {
    sendWelcomeEmail($username); // isso nunca é enviado
});

Sobrescrevendo Métodos de Eventos

Flight::onEvent() e Flight::triggerEvent() estão disponíveis para serem estendidos, o que significa que você pode redefinir como eles funcionam. Isso é ótimo para usuários avançados que querem personalizar o sistema de eventos, como adicionar registro ou alterar como os eventos são despachados.

Exemplo: Personalizando onEvent

Flight::map('onEvent', function (string $event, callable $callback) {
    // Registra toda inscrição de evento
    error_log("Novo ouvinte de evento adicionado para: $event");
    // Chama o comportamento padrão (assumindo um sistema de eventos interno)
    Flight::_onEvent($event, $callback);
});

Agora, toda vez que você registrar um evento, ele será registrado antes de prosseguir.

Por Que Sobrescrever?

Onde Colocar Seus Eventos

Se você é novo nos conceitos de eventos no seu projeto, pode se perguntar: onde eu registro todos esses eventos na minha aplicação? A simplicidade da Flight significa que não há uma regra estrita — você pode colocá-los onde fizer sentido para o seu projeto. No entanto, mantê-los organizados ajuda a manter seu código à medida que sua aplicação cresce. Aqui estão algumas opções práticas e melhores práticas, adaptadas à natureza leve da Flight:

Opção 1: No Seu index.php Principal

Para aplicações pequenas ou protótipos rápidos, você pode registrar eventos diretamente no seu arquivo index.php junto com suas rotas. Isso mantém tudo em um só lugar, o que é bom quando a simplicidade é a prioridade.

require 'vendor/autoload.php';

// Registra eventos
Flight::onEvent('user.login', function ($username) {
    error_log("$username logged in at " . date('Y-m-d H:i:s'));
});

// Define rotas
Flight::route('/login', function () {
    $username = 'bob';
    Flight::triggerEvent('user.login', $username);
    echo "Logged in!";
});

Flight::start();

Opção 2: Um Arquivo events.php Separado

Para uma aplicação um pouco maior, considere mover os registros de eventos para um arquivo dedicado como app/config/events.php. Inclua este arquivo no seu index.php antes das suas rotas. Isso imita como as rotas são frequentemente organizadas em app/config/routes.php em projetos Flight.

// app/config/events.php
Flight::onEvent('user.login', function ($username) {
    error_log("$username logged in at " . date('Y-m-d H:i:s'));
});

Flight::onEvent('user.registered', function ($email, $name) {
    echo "Email sent to $email: Welcome, $name!";
});
// index.php
require 'vendor/autoload.php';
require 'app/config/events.php';

Flight::route('/login', function () {
    $username = 'bob';
    Flight::triggerEvent('user.login', $username);
    echo "Logged in!";
});

Flight::start();

Opção 3: Perto de Onde Eles São Disparados

Outra abordagem é registrar eventos perto de onde eles são disparados, como dentro de um controlador ou definição de rota. Isso funciona bem se um evento for específico para uma parte da sua aplicação.

Flight::route('/signup', function () {
    // Registra evento aqui
    Flight::onEvent('user.registered', function ($email) {
        echo "Welcome email sent to $email!";
    });

    $email = 'jane@example.com';
    Flight::triggerEvent('user.registered', $email);
    echo "Signed up!";
});

Melhor Prática para Flight

Dica: Agrupe por Propósito

Em events.php, agrupe eventos relacionados (ex.: todos os eventos relacionados a usuários juntos) com comentários para clareza:

// app/config/events.php
// Eventos de Usuário
Flight::onEvent('user.login', function ($username) {
    error_log("$username logged in");
});
Flight::onEvent('user.registered', function ($email) {
    echo "Welcome to $email!";
});

// Eventos de Página
Flight::onEvent('page.updated', function ($pageId) {
    Flight::cache()->delete("page_$pageId");
});

Essa estrutura escala bem e permanece amigável para iniciantes.

Exemplos do Mundo Real

Vamos percorrer alguns cenários do mundo real para mostrar como os eventos funcionam e por que eles são úteis.

Exemplo 1: Registrando um Login de Usuário

// Passo 1: Registra um ouvinte
Flight::onEvent('user.login', function ($username) {
    $time = date('Y-m-d H:i:s');
    error_log("$username logged in at $time");
});

// Passo 2: Dispare-o na sua aplicação
Flight::route('/login', function () {
    $username = 'bob'; // Finja que isso vem de um formulário
    Flight::triggerEvent('user.login', $username);
    echo "Hi, $username!";
});

Por Que É Útil: O código de login não precisa saber sobre o registro — ele apenas dispara o evento. Você pode adicionar mais ouvintes depois (ex.: enviar um e-mail de boas-vindas) sem alterar a rota.

Exemplo 2: Notificando Sobre Novos Usuários

// Ouvinte para novos registros
Flight::onEvent('user.registered', function ($email, $name) {
    // Simula o envio de um e-mail
    echo "Email sent to $email: Welcome, $name!";
});

// Dispare quando alguém se inscreve
Flight::route('/signup', function () {
    $email = 'jane@example.com';
    $name = 'Jane';
    Flight::triggerEvent('user.registered', $email, $name);
    echo "Thanks for signing up!";
});

Por Que É Útil: A lógica de inscrição foca em criar o usuário, enquanto o evento lida com notificações. Você pode adicionar mais ouvintes (ex.: registrar a inscrição) depois.

Exemplo 3: Limpando um Cache

// Ouvinte para limpar um cache
Flight::onEvent('page.updated', function ($pageId) {
    // se usando o plugin flightphp/cache
    Flight::cache()->delete("page_$pageId");
    echo "Cache cleared for page $pageId.";
});

// Dispare quando uma página é editada
Flight::route('/edit-page/(@id)', function ($pageId) {
    // Finja que atualizamos a página
    Flight::triggerEvent('page.updated', $pageId);
    echo "Page $pageId updated.";
});

Por Que É Útil: O código de edição não se importa com cache — ele apenas sinaliza a atualização. Outras partes da aplicação podem reagir conforme necessário.

Melhores Práticas

O sistema de eventos na Flight PHP, com Flight::onEvent() e Flight::triggerEvent(), dá a você uma forma simples, mas poderosa, de construir aplicações flexíveis. Ao permitir que diferentes partes da sua aplicação se comuniquem através de eventos, você pode manter seu código organizado, reutilizável e fácil de expandir. Seja registrando ações, enviando notificações ou gerenciando atualizações, os eventos ajudam você a fazer isso sem emaranhar sua lógica. Além disso, com a capacidade de sobrescrever esses métodos, você tem a liberdade de adaptar o sistema às suas necessidades. Comece pequeno com um único evento e veja como ele transforma a estrutura da sua aplicação!

Eventos Integrados

A Flight PHP vem com alguns eventos integrados que você pode usar para se conectar ao ciclo de vida do framework. Esses eventos são disparados em pontos específicos do ciclo de solicitação/resposta, permitindo que você execute lógica personalizada quando certas ações ocorrem.

Lista de Eventos Integrados

Veja Também

Solução de Problemas

Registro de Alterações

Learn/templates

Visualizações e Modelos HTML

Visão Geral

Flight fornece alguma funcionalidade básica de modelagem HTML por padrão. A modelagem é uma maneira muito eficaz para você desconectar a lógica da sua aplicação da camada de apresentação.

Compreendendo

Quando você está construindo uma aplicação, provavelmente terá HTML que você desejará entregar de volta ao usuário final. PHP por si só é uma linguagem de modelagem, mas é muito fácil envolver lógica de negócios como chamadas de banco de dados, chamadas de API, etc., no seu arquivo HTML e tornar o teste e o desacoplamento um processo muito difícil. Ao empurrar dados para um modelo e deixar o modelo renderizar a si mesmo, torna-se muito mais fácil desacoplar e testar unidades o seu código. Você nos agradecerá se usar modelos!

Uso Básico

Flight permite que você troque o mecanismo de visualização padrão simplesmente registrando sua própria classe de visualização. Desça para ver exemplos de como usar Smarty, Latte, Blade e mais!

Latte

recomendado

Aqui está como você usaria o mecanismo de modelo Latte para suas visualizações.

Instalação

composer require latte/latte

Configuração Básica

A ideia principal é que você sobrescreva o método render para usar Latte em vez do renderizador PHP padrão.

// sobrescreva o método render para usar latte em vez do renderizador PHP padrão
Flight::map('render', function(string $template, array $data, ?string $block): void {
    $latte = new Latte\Engine;

    // Onde latte armazena especificamente seu cache
    $latte->setTempDirectory(__DIR__ . '/../cache/');

    $finalPath = Flight::get('flight.views.path') . $template;

    $latte->render($finalPath, $data, $block);
});

Usando Latte no Flight

Agora que você pode renderizar com Latte, você pode fazer algo assim:

<!-- app/views/home.latte -->
<html>
  <head>
    <title>{$title ? $title . ' - '}My App</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <h1>Hello, {$name}!</h1>
  </body>
</html>
// routes.php
Flight::route('/@name', function ($name) {
    Flight::render('home.latte', [
        'title' => 'Home Page',
        'name' => $name
    ]);
});

Quando você visitar /Bob no seu navegador, a saída seria:

<html>
  <head>
    <title>Home Page - My App</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <h1>Hello, Bob!</h1>
  </body>
</html>

Leitura Adicional

Um exemplo mais complexo de uso do Latte com layouts é mostrado na seção de plugins incríveis desta documentação.

Você pode aprender mais sobre as capacidades completas do Latte, incluindo tradução e capacidades de linguagem, lendo a documentação oficial.

Mecanismo de Visualização Integrado

deprecado

Nota: Embora isso ainda seja a funcionalidade padrão e ainda funcione tecnicamente.

Para exibir um modelo de visualização, chame o método render com o nome do arquivo de modelo e dados de modelo opcionais:

Flight::render('hello.php', ['name' => 'Bob']);

Os dados de modelo que você passa são automaticamente injetados no modelo e podem ser referenciados como uma variável local. Arquivos de modelo são simplesmente arquivos PHP. Se o conteúdo do arquivo de modelo hello.php for:

Hello, <?= $name ?>!

A saída seria:

Hello, Bob!

Você também pode definir variáveis de visualização manualmente usando o método set:

Flight::view()->set('name', 'Bob');

A variável name agora está disponível em todas as suas visualizações. Então você pode simplesmente fazer:

Flight::render('hello');

Observe que ao especificar o nome do modelo no método render, você pode deixar de fora a extensão .php.

Por padrão, Flight procurará um diretório views para arquivos de modelo. Você pode definir um caminho alternativo para seus modelos definindo a seguinte configuração:

Flight::set('flight.views.path', '/path/to/views');

Layouts

É comum para sites ter um único arquivo de modelo de layout com conteúdo intercambiável. Para renderizar conteúdo a ser usado em um layout, você pode passar um parâmetro opcional para o método render.

Flight::render('header', ['heading' => 'Hello'], 'headerContent');
Flight::render('body', ['body' => 'World'], 'bodyContent');

Sua visualização então terá variáveis salvas chamadas headerContent e bodyContent. Você pode então renderizar seu layout fazendo:

Flight::render('layout', ['title' => 'Home Page']);

Se os arquivos de modelo parecerem assim:

header.php:

<h1><?= $heading ?></h1>

body.php:

<div><?= $body ?></div>

layout.php:

<html>
  <head>
    <title><?= $title ?></title>
  </head>
  <body>
    <?= $headerContent ?>
    <?= $bodyContent ?>
  </body>
</html>

A saída seria:

<html>
  <head>
    <title>Home Page</title>
  </head>
  <body>
    <h1>Hello</h1>
    <div>World</div>
  </body>
</html>

Smarty

Aqui está como você usaria o mecanismo de modelo Smarty para suas visualizações:

// Carrega a biblioteca Smarty
require './Smarty/libs/Smarty.class.php';

// Registra Smarty como a classe de visualização
// Também passa uma função de callback para configurar Smarty na carga
Flight::register('view', Smarty::class, [], function (Smarty $smarty) {
  $smarty->setTemplateDir('./templates/');
  $smarty->setCompileDir('./templates_c/');
  $smarty->setConfigDir('./config/');
  $smarty->setCacheDir('./cache/');
});

// Atribui dados de modelo
Flight::view()->assign('name', 'Bob');

// Exibe o modelo
Flight::view()->display('hello.tpl');

Para completude, você também deve sobrescrever o método render padrão do Flight:

Flight::map('render', function(string $template, array $data): void {
  Flight::view()->assign($data);
  Flight::view()->display($template);
});

Blade

Aqui está como você usaria o mecanismo de modelo Blade para suas visualizações:

Primeiro, você precisa instalar a biblioteca BladeOne via Composer:

composer require eftec/bladeone

Em seguida, você pode configurar BladeOne como a classe de visualização no Flight:

<?php
// Carrega a biblioteca BladeOne
use eftec\bladeone\BladeOne;

// Registra BladeOne como a classe de visualização
// Também passa uma função de callback para configurar BladeOne na carga
Flight::register('view', BladeOne::class, [], function (BladeOne $blade) {
  $views = __DIR__ . '/../views';
  $cache = __DIR__ . '/../cache';

  $blade->setPath($views);
  $blade->setCompiledPath($cache);
});

// Atribui dados de modelo
Flight::view()->share('name', 'Bob');

// Exibe o modelo
echo Flight::view()->run('hello', []);

Para completude, você também deve sobrescrever o método render padrão do Flight:

<?php
Flight::map('render', function(string $template, array $data): void {
  echo Flight::view()->run($template, $data);
});

Neste exemplo, o arquivo de modelo hello.blade.php pode parecer assim:

<?php
Hello, {{ $name }}!

A saída seria:

Hello, Bob!

Veja Também

Solução de Problemas

Registro de Alterações

Learn/collections

Coleções

Visão Geral

A classe Collection no Flight é uma utilidade prática para gerenciar conjuntos de dados. Ela permite acessar e manipular dados usando tanto notação de array quanto de objeto, tornando seu código mais limpo e flexível.

Entendendo

Uma Collection é basicamente um wrapper ao redor de um array, mas com alguns poderes extras. Você pode usá-la como um array, iterar sobre ela, contar seus itens e até acessar itens como se fossem propriedades de objeto. Isso é especialmente útil quando você quer passar dados estruturados em seu app, ou quando quer tornar seu código um pouco mais legível.

Collections implementam várias interfaces do PHP:

Uso Básico

Criando uma Collection

Você pode criar uma collection simplesmente passando um array para seu construtor:

use flight\util\Collection;

$data = [
  'name' => 'Flight',
  'version' => 3,
  'features' => ['routing', 'views', 'extending']
];

$collection = new Collection($data);

Acessando Itens

Você pode acessar itens usando notação de array ou de objeto:

// Notação de array
echo $collection['name']; // Saída: FlightPHP

// Notação de objeto
echo $collection->version; // Saída: 3

Se você tentar acessar uma chave que não existe, você obterá null em vez de um erro.

Definindo Itens

Você pode definir itens usando qualquer uma das notações também:

// Notação de array
$collection['author'] = 'Mike Cao';

// Notação de objeto
$collection->license = 'MIT';

Verificando e Removendo Itens

Verifique se um item existe:

if (isset($collection['name'])) {
  // Faça algo
}

if (isset($collection->version)) {
  // Faça algo
}

Remova um item:

unset($collection['author']);
unset($collection->license);

Iterando Sobre uma Collection

Collections são iteráveis, então você pode usá-las em um loop foreach:

foreach ($collection as $key => $value) {
  echo "$key: $value\n";
}

Contando Itens

Você pode contar o número de itens em uma collection:

echo count($collection); // Saída: 4

Obtendo Todas as Chaves ou Dados

Obtenha todas as chaves:

$keys = $collection->keys(); // ['name', 'version', 'features', 'license']

Obtenha todos os dados como um array:

$data = $collection->getData();

Limpando a Collection

Remova todos os itens:

$collection->clear();

Serialização JSON

Collections podem ser facilmente convertidas para JSON:

echo json_encode($collection);
// Saída: {"name":"FlightPHP","version":3,"features":["routing","views","extending"],"license":"MIT"}

Uso Avançado

Você pode substituir o array de dados interno completamente, se necessário:

$collection->setData(['foo' => 'bar']);

Collections são especialmente úteis quando você quer passar dados estruturados entre componentes, ou quando quer fornecer uma interface mais orientada a objetos para dados de array.

Veja Também

Solução de Problemas

Changelog

Learn/flight_vs_fat_free

Flight vs Fat-Free

O que é Fat-Free?

Fat-Free (carinhosamente conhecido como F3) é um micro-framework PHP poderoso e fácil de usar, projetado para ajudá-lo a construir aplicativos web dinâmicos e robustos - rapidamente!

Flight se compara ao Fat-Free de muitas maneiras e é provavelmente o primo mais próximo em termos de recursos e simplicidade. Fat-Free tem muitos recursos que Flight não tem, mas também tem muitos recursos que Flight tem. Fat-Free está começando a mostrar sua idade e não é tão popular quanto costumava ser.

As atualizações estão se tornando menos frequentes e a comunidade não é tão ativa quanto costumava ser. O código é simples o suficiente, mas às vezes a falta de disciplina de sintaxe pode torná-lo difícil de ler e entender. Ele funciona para PHP 8.3, mas o código em si ainda parece que vive no PHP 5.3.

Prós em comparação com Flight

Contras em comparação com Flight

Learn/extending

Estendendo

Visão Geral

Flight é projetado para ser um framework extensível. O framework vem com um conjunto de métodos e componentes padrão, mas permite que você mapeie seus próprios métodos, registre suas próprias classes ou até substitua classes e métodos existentes.

Compreendendo

Existem 2 maneiras de você estender a funcionalidade do Flight:

  1. Mapeamento de Métodos - Isso é usado para criar métodos personalizados simples que você pode chamar de qualquer lugar em sua aplicação. Esses são tipicamente usados para funções utilitárias que você deseja poder chamar de qualquer lugar em seu código.
  2. Registrando Classes - Isso é usado para registrar suas próprias classes com o Flight. Isso é tipicamente usado para classes que têm dependências ou requerem configuração.

Você também pode substituir métodos existentes do framework para alterar seu comportamento padrão para melhor atender às necessidades do seu projeto.

Se você está procurando um DIC (Container de Injeção de Dependência), pule para a página Container de Injeção de Dependência.

Uso Básico

Substituindo Métodos do Framework

Flight permite que você substitua sua funcionalidade padrão para atender às suas próprias necessidades, sem precisar modificar nenhum código. Você pode ver todos os métodos que pode substituir abaixo.

Por exemplo, quando o Flight não consegue corresponder uma URL a uma rota, ele invoca o método notFound que envia uma resposta genérica HTTP 404. Você pode substituir esse comportamento usando o método map:

Flight::map('notFound', function() {
  // Exibe página 404 personalizada
  include 'errors/404.html';
});

Flight também permite que você substitua componentes principais do framework. Por exemplo, você pode substituir a classe Router padrão pela sua própria classe personalizada:

// crie sua classe Router personalizada
class MyRouter extends \flight\net\Router {
    // substitua métodos aqui
    // por exemplo, um atalho para requisições GET para remover
    // o recurso de passagem de rota
    public function get($pattern, $callback, $alias = '') {
        return parent::get($pattern, $callback, false, $alias);
    }
}

// Registre sua classe personalizada
Flight::register('router', MyRouter::class);

// Quando o Flight carrega a instância do Router, ele carregará sua classe
$myRouter = Flight::router();
$myRouter->get('/hello', function() {
  echo "Hello World!";
}, 'hello_alias');

Métodos do framework como map e register, no entanto, não podem ser substituídos. Você receberá um erro se tentar fazer isso (novamente, veja abaixo para uma lista de métodos).

Métodos Mapeáveis do Framework

A seguir está o conjunto completo de métodos para o framework. Ele consiste em métodos principais, que são métodos estáticos regulares, e métodos extensíveis, que são métodos mapeados que podem ser filtrados ou substituídos.

Métodos Principais

Esses métodos são principais para o framework e não podem ser substituídos.

Flight::map(string $name, callable $callback, bool $pass_route = false) // Cria um método personalizado do framework.
Flight::register(string $name, string $class, array $params = [], ?callable $callback = null) // Registra uma classe a um método do framework.
Flight::unregister(string $name) // Desregistra uma classe de um método do framework.
Flight::before(string $name, callable $callback) // Adiciona um filtro antes de um método do framework.
Flight::after(string $name, callable $callback) // Adiciona um filtro após um método do framework.
Flight::path(string $path) // Adiciona um caminho para carregamento automático de classes.
Flight::get(string $key) // Obtém uma variável definida por Flight::set().
Flight::set(string $key, mixed $value) // Define uma variável dentro do engine do Flight.
Flight::has(string $key) // Verifica se uma variável está definida.
Flight::clear(array|string $key = []) // Limpa uma variável.
Flight::init() // Inicializa o framework com suas configurações padrão.
Flight::app() // Obtém a instância do objeto de aplicação
Flight::request() // Obtém a instância do objeto de requisição
Flight::response() // Obtém a instância do objeto de resposta
Flight::router() // Obtém a instância do objeto de roteador
Flight::view() // Obtém a instância do objeto de visualização

Métodos Extensíveis

Flight::start() // Inicia o framework.
Flight::stop() // Para o framework e envia uma resposta.
Flight::halt(int $code = 200, string $message = '') // Para o framework com um código de status e mensagem opcionais.
Flight::route(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') // Mapeia um padrão de URL para um callback.
Flight::post(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') // Mapeia um padrão de URL de requisição POST para um callback.
Flight::put(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') // Mapeia um padrão de URL de requisição PUT para um callback.
Flight::patch(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') // Mapeia um padrão de URL de requisição PATCH para um callback.
Flight::delete(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') // Mapeia um padrão de URL de requisição DELETE para um callback.
Flight::group(string $pattern, callable $callback) // Cria agrupamento para URLs, o padrão deve ser uma string.
Flight::getUrl(string $name, array $params = []) // Gera uma URL baseada em um alias de rota.
Flight::redirect(string $url, int $code) // Redireciona para outra URL.
Flight::download(string $filePath) // Baixa um arquivo.
Flight::render(string $file, array $data, ?string $key = null) // Renderiza um arquivo de template.
Flight::error(Throwable $error) // Envia uma resposta HTTP 500.
Flight::notFound() // Envia uma resposta HTTP 404.
Flight::etag(string $id, string $type = 'string') // Realiza cache HTTP ETag.
Flight::lastModified(int $time) // Realiza cache HTTP de última modificação.
Flight::json(mixed $data, int $code = 200, bool $encode = true, string $charset = 'utf8', int $option) // Envia uma resposta JSON.
Flight::jsonp(mixed $data, string $param = 'jsonp', int $code = 200, bool $encode = true, string $charset = 'utf8', int $option) // Envia uma resposta JSONP.
Flight::jsonHalt(mixed $data, int $code = 200, bool $encode = true, string $charset = 'utf8', int $option) // Envia uma resposta JSON e para o framework.
Flight::onEvent(string $event, callable $callback) // Registra um ouvinte de evento.
Flight::triggerEvent(string $event, ...$args) // Dispara um evento.

Quaisquer métodos personalizados adicionados com map e register também podem ser filtrados. Para exemplos de como filtrar esses métodos, veja o guia Filtrando Métodos.

Classes Extensíveis do Framework

Existem várias classes que você pode substituir a funcionalidade estendendo-as e registrando sua própria classe. Essas classes são:

Flight::app() // Classe de Aplicação - estenda a classe flight\Engine
Flight::request() // Classe de Requisição - estenda a classe flight\net\Request
Flight::response() // Classe de Resposta - estenda a classe flight\net\Response
Flight::router() // Classe de Roteador - estenda a classe flight\net\Router
Flight::view() // Classe de Visualização - estenda a classe flight\template\View
Flight::eventDispatcher() // Classe de Dispatcher de Eventos - estenda a classe flight\core\Dispatcher

Mapeando Métodos Personalizados

Para mapear seu próprio método personalizado simples, você usa a função map:

// Mapeie seu método
Flight::map('hello', function (string $name) {
  echo "hello $name!";
});

// Chame seu método personalizado
Flight::hello('Bob');

Embora seja possível criar métodos personalizados simples, é recomendado apenas criar funções padrão em PHP. Isso tem autocompletar em IDEs e é mais fácil de ler. O equivalente do código acima seria:

function hello(string $name) {
  echo "hello $name!";
}

hello('Bob');

Isso é usado mais quando você precisa passar variáveis para o seu método para obter um valor esperado. Usar o método register() como abaixo é mais para passar configuração e depois chamar sua classe pré-configurada.

Registrando Classes Personalizadas

Para registrar sua própria classe e configurá-la, você usa a função register. A vantagem que isso tem sobre map() é que você pode reutilizar a mesma classe quando chamar essa função (seria útil com Flight::db() para compartilhar a mesma instância).

// Registre sua classe
Flight::register('user', User::class);

// Obtenha uma instância da sua classe
$user = Flight::user();

O método register também permite que você passe parâmetros para o construtor da sua classe. Então, quando você carrega sua classe personalizada, ela virá pré-inicializada. Você pode definir os parâmetros do construtor passando um array adicional. Aqui está um exemplo de carregamento de uma conexão de banco de dados:

// Registre a classe com parâmetros do construtor
Flight::register('db', PDO::class, ['mysql:host=localhost;dbname=test', 'user', 'pass']);

// Obtenha uma instância da sua classe
// Isso criará um objeto com os parâmetros definidos
//
// new PDO('mysql:host=localhost;dbname=test','user','pass');
//
$db = Flight::db();

// e se você precisar dela mais tarde no seu código, você apenas chama o mesmo método novamente
class SomeController {
  public function __construct() {
    $this->db = Flight::db();
  }
}

Se você passar um parâmetro de callback adicional, ele será executado imediatamente após a construção da classe. Isso permite que você execute qualquer procedimento de configuração para o seu novo objeto. A função de callback recebe um parâmetro, uma instância do novo objeto.

// O callback receberá o objeto que foi construído
Flight::register(
  'db',
  PDO::class,
  ['mysql:host=localhost;dbname=test', 'user', 'pass'],
  function (PDO $db) {
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
  }
);

Por padrão, toda vez que você carrega sua classe, você obterá uma instância compartilhada. Para obter uma nova instância de uma classe, simplesmente passe false como parâmetro:

// Instância compartilhada da classe
$shared = Flight::db();

// Nova instância da classe
$new = Flight::db(false);

Nota: Lembre-se de que os métodos mapeados têm precedência sobre as classes registradas. Se você declarar ambos usando o mesmo nome, apenas o método mapeado será invocado.

Exemplos

Aqui estão alguns exemplos de como você pode estender o Flight com funcionalidades que não estão integradas no núcleo.

Logging

Flight não tem um sistema de logging integrado, no entanto, é realmente fácil usar uma biblioteca de logging com o Flight. Aqui está um exemplo usando a biblioteca Monolog:

// services.php

// Registre o logger com o Flight
Flight::register('log', Monolog\Logger::class, [ 'name' ], function(Monolog\Logger $log) {
    $log->pushHandler(new Monolog\Handler\StreamHandler('path/to/your.log', Monolog\Logger::WARNING));
});

Agora que está registrado, você pode usá-lo em sua aplicação:

// Em seu controlador ou rota
Flight::log()->warning('This is a warning message');

Isso registrará uma mensagem no arquivo de log que você especificou. E se você quiser registrar algo quando um erro ocorrer? Você pode usar o método error:

// Em seu controlador ou rota
Flight::map('error', function(Throwable $ex) {
    Flight::log()->error($ex->getMessage());
    // Exiba sua página de erro personalizada
    include 'errors/500.html';
});

Você também poderia criar um sistema básico de APM (Monitoramento de Desempenho de Aplicação) usando os métodos before e after:

// Em seu arquivo services.php

Flight::before('start', function() {
    Flight::set('start_time', microtime(true));
});

Flight::after('start', function() {
    $end = microtime(true);
    $start = Flight::get('start_time');
    Flight::log()->info('Request '.Flight::request()->url.' took ' . round($end - $start, 4) . ' seconds');

    // Você também poderia adicionar os cabeçalhos de requisição ou resposta
    // para registrá-los também (tenha cuidado, pois isso seria um 
    // monte de dados se você tiver muitas requisições)
    Flight::log()->info('Request Headers: ' . json_encode(Flight::request()->headers));
    Flight::log()->info('Response Headers: ' . json_encode(Flight::response()->headers));
});

Cache

Flight não tem um sistema de cache integrado, no entanto, é realmente fácil usar uma biblioteca de cache com o Flight. Aqui está um exemplo usando a PHP File Cache biblioteca:

// services.php

// Registre o cache com o Flight
Flight::register('cache', \flight\Cache::class, [ __DIR__ . '/../cache/' ], function(\flight\Cache $cache) {
    $cache->setDevMode(ENVIRONMENT === 'development');
});

Agora que está registrado, você pode usá-lo em sua aplicação:

// Em seu controlador ou rota
$data = Flight::cache()->get('my_cache_key');
if (empty($data)) {
    // Faça algum processamento para obter os dados
    $data = [ 'some' => 'data' ];
    Flight::cache()->set('my_cache_key', $data, 3600); // cache por 1 hora
}

Instanciação Fácil de Objetos DIC

Se você está usando um DIC (Container de Injeção de Dependência) em sua aplicação, você pode usar o Flight para ajudá-lo a instanciar seus objetos. Aqui está um exemplo usando a biblioteca Dice:

// services.php

// crie um novo container
$container = new \Dice\Dice;
// não esqueça de reatribuí-lo a si mesmo como abaixo!
$container = $container->addRule('PDO', [
    // shared significa que o mesmo objeto será retornado a cada vez
    'shared' => true,
    'constructParams' => ['mysql:host=localhost;dbname=test', 'user', 'pass' ]
]);

// agora podemos criar um método mapeável para criar qualquer objeto. 
Flight::map('make', function($class, $params = []) use ($container) {
    return $container->create($class, $params);
});

// Isso registra o manipulador de container para que o Flight saiba usá-lo para controladores/middleware
Flight::registerContainerHandler(function($class, $params) {
    Flight::make($class, $params);
});

// digamos que tenhamos a seguinte classe de exemplo que recebe um objeto PDO no construtor
class EmailCron {
    protected PDO $pdo;

    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }

    public function send() {
        // código que envia um email
    }
}

// E finalmente você pode criar objetos usando injeção de dependência
$emailCron = Flight::make(EmailCron::class);
$emailCron->send();

Legal, né?

Veja Também

Solução de Problemas

Changelog

Learn/json

JSON Wrapper

Visão Geral

A classe Json no Flight fornece uma maneira simples e consistente de codificar e decodificar dados JSON em sua aplicação. Ela envolve as funções JSON nativas do PHP com melhor tratamento de erros e alguns padrões úteis, tornando mais fácil e seguro trabalhar com JSON.

Entendendo

Trabalhar com JSON é super comum em aplicações PHP modernas, especialmente ao construir APIs ou lidar com requisições AJAX. A classe Json centraliza toda a codificação e decodificação JSON, para que você não precise se preocupar com casos de borda estranhos ou erros crípticos das funções integradas do PHP.

Principais recursos:

Uso Básico

Codificando Dados para JSON

Para converter dados PHP em uma string JSON, use Json::encode():

use flight\util\Json;

$data = [
  'framework' => 'Flight',
  'version' => 3,
  'features' => ['routing', 'views', 'extending']
];

$json = Json::encode($data);
echo $json;
// Saída: {"framework":"Flight","version":3,"features":["routing","views","extending"]}

Se a codificação falhar, você receberá uma exceção com uma mensagem de erro útil.

Impressão Formatada

Quer que seu JSON seja legível por humanos? Use prettyPrint():

echo Json::prettyPrint($data);
/*
{
  "framework": "Flight",
  "version": 3,
  "features": [
    "routing",
    "views",
    "extending"
  ]
}
*/

Decodificando Strings JSON

Para converter uma string JSON de volta para dados PHP, use Json::decode():

$json = '{"framework":"Flight","version":3}';
$data = Json::decode($json);
echo $data->framework; // Saída: Flight

Se você quiser um array associativo em vez de um objeto, passe true como o segundo argumento:

$data = Json::decode($json, true);
echo $data['framework']; // Saída: Flight

Se a decodificação falhar, você receberá uma exceção com uma mensagem de erro clara.

Validando JSON

Verifique se uma string é um JSON válido:

if (Json::isValid($json)) {
  // É válido!
} else {
  // Não é JSON válido
}

Obtendo o Último Erro

Se você quiser verificar a última mensagem de erro JSON (das funções nativas do PHP):

$error = Json::getLastError();
if ($error !== '') {
  echo "Último erro JSON: $error";
}

Uso Avançado

Você pode personalizar as opções de codificação e decodificação se precisar de mais controle (veja opções do json_encode do PHP):

// Codificar com a opção JSON_HEX_TAG
$json = Json::encode($data, JSON_HEX_TAG);

// Decodificar com profundidade personalizada
$data = Json::decode($json, false, 1024);

Veja Também

Solução de Problemas

Changelog

Learn/flight_vs_slim

Flight vs Slim

O que é Slim?

Slim é um micro framework PHP que ajuda você a escrever rapidamente aplicativos web simples, mas poderosos, e APIs.

Muita da inspiração para alguns dos recursos da v3 do Flight na verdade veio do Slim. Agrupar rotas e executar middleware em uma ordem específica são dois recursos inspirados no Slim. O Slim v3 foi lançado com foco em simplicidade, mas houve críticas mistas em relação à v4.

Vantagens em comparação ao Flight

Desvantagens em comparação ao Flight

Learn/autoloading

Autoloading

Visão Geral

Autoloading é um conceito no PHP onde você especifica um diretório ou diretórios para carregar classes. Isso é muito mais benéfico do que usar require ou include para carregar classes. Também é um requisito para usar pacotes do Composer.

Entendendo

Por padrão, qualquer classe Flight é autoloaded automaticamente para você graças ao composer. No entanto, se você quiser autoload suas próprias classes, pode usar o método Flight::path() para especificar um diretório para carregar classes.

Usar um autoloader pode ajudar a simplificar seu código de forma significativa. Em vez de ter arquivos começando com uma infinidade de declarações include ou require no topo para capturar todas as classes usadas nesse arquivo, você pode chamar dinamicamente suas classes e elas serão incluídas automaticamente.

Uso Básico

Vamos assumir que temos uma árvore de diretórios como a seguinte:

# Exemplo de caminho
/home/user/project/my-flight-project/
├── app
│   ├── cache
│   ├── config
│   ├── controllers - contém os controllers para este projeto
│   ├── translations
│   ├── UTILS - contém classes apenas para esta aplicação (isso está em maiúsculas de propósito para um exemplo posterior)
│   └── views
└── public
    └── css
    └── js
    └── index.php

Você pode ter notado que esta é a mesma estrutura de arquivos deste site de documentação.

Você pode especificar cada diretório para carregar assim:


/**
 * public/index.php
 */

// Adicione um caminho ao autoloader
Flight::path(__DIR__.'/../app/controllers/');
Flight::path(__DIR__.'/../app/utils/');

/**
 * app/controllers/MyController.php
 */

// sem namespacing necessário

// Todas as classes autoloaded são recomendadas para serem Pascal Case (cada palavra capitalizada, sem espaços)
class MyController {

    public function index() {
        // faça algo
    }
}

Namespaces

Se você tiver namespaces, na verdade fica muito fácil implementar isso. Você deve usar o método Flight::path() para especificar o diretório raiz (não o document root ou pasta public/) da sua aplicação.


/**
 * public/index.php
 */

// Adicione um caminho ao autoloader
Flight::path(__DIR__.'/../');

Agora é assim que o seu controller pode parecer. Olhe o exemplo abaixo, mas preste atenção nos comentários para informações importantes.

/**
 * app/controllers/MyController.php
 */

// namespaces são necessários
// namespaces são os mesmos que a estrutura de diretórios
// namespaces devem seguir o mesmo case que a estrutura de diretórios
// namespaces e diretórios não podem ter underscores (a menos que Loader::setV2ClassLoading(false) seja definido)
namespace app\controllers;

// Todas as classes autoloaded são recomendadas para serem Pascal Case (cada palavra capitalizada, sem espaços)
// A partir de 3.7.2, você pode usar Pascal_Snake_Case para os nomes das suas classes executando Loader::setV2ClassLoading(false);
class MyController {

    public function index() {
        // faça algo
    }
}

E se você quisesse autoload uma classe no seu diretório utils, você faria basicamente a mesma coisa:


/**
 * app/UTILS/ArrayHelperUtil.php
 */

// namespace deve corresponder à estrutura de diretórios e case (note que o diretório UTILS está em maiúsculas
//     como na árvore de arquivos acima)
namespace app\UTILS;

class ArrayHelperUtil {

    public function changeArrayCase(array $array) {
        // faça algo
    }
}

Underscores nos Nomes de Classes

A partir de 3.7.2, você pode usar Pascal_Snake_Case para os nomes das suas classes executando Loader::setV2ClassLoading(false);. Isso permitirá que você use underscores nos nomes das suas classes. Isso não é recomendado, mas está disponível para aqueles que precisam.

use flight\core\Loader;

/**
 * public/index.php
 */

// Adicione um caminho ao autoloader
Flight::path(__DIR__.'/../app/controllers/');
Flight::path(__DIR__.'/../app/utils/');
Loader::setV2ClassLoading(false);

/**
 * app/controllers/My_Controller.php
 */

// sem namespacing necessário

class My_Controller {

    public function index() {
        // faça algo
    }
}

Veja Também

Solução de Problemas

Classe Não Encontrada (autoloading não funcionando)

Pode haver alguns motivos para isso não acontecer. Abaixo estão alguns exemplos, mas certifique-se de verificar também a seção autoloading.

Nome de Arquivo Incorreto

O mais comum é que o nome da classe não corresponda ao nome do arquivo.

Se você tiver uma classe chamada MyClass, o arquivo deve ser chamado MyClass.php. Se você tiver uma classe chamada MyClass e o arquivo for chamado myclass.php então o autoloader não conseguirá encontrá-lo.

Namespace Incorreto

Se você estiver usando namespaces, o namespace deve corresponder à estrutura de diretórios.

// ...código...

// se o seu MyController estiver no diretório app/controllers e estiver namespaced
// isso não funcionará.
Flight::route('/hello', 'MyController->hello');

// você precisará escolher uma dessas opções
Flight::route('/hello', 'app\controllers\MyController->hello');
// ou se você tiver uma declaração use no topo

use app\controllers\MyController;

Flight::route('/hello', [ MyController::class, 'hello' ]);
// também pode ser escrito
Flight::route('/hello', MyController::class.'->hello');
// também...
Flight::route('/hello', [ 'app\controllers\MyController', 'hello' ]);

path() não definido

No app skeleton, isso é definido dentro do arquivo config.php, mas para que suas classes sejam encontradas, você precisa garantir que o método path() seja definido (provavelmente para a raiz do seu diretório) antes de tentar usá-lo.

// Adicione um caminho ao autoloader
Flight::path(__DIR__.'/../');

Changelog

Learn/uploaded_file

Manipulador de Arquivo Enviado

Visão Geral

A classe UploadedFile no Flight facilita e torna seguro o manuseio de uploads de arquivos em sua aplicação. Ela encapsula os detalhes do processo de upload de arquivos do PHP, fornecendo uma maneira simples e orientada a objetos para acessar informações do arquivo e mover arquivos enviados.

Compreendendo

Quando um usuário envia um arquivo via formulário, o PHP armazena informações sobre o arquivo na superglobal $_FILES. No Flight, você raramente interage diretamente com $_FILES. Em vez disso, o objeto Request do Flight (acessível via Flight::request()) fornece um método getUploadedFiles() que retorna um array de objetos UploadedFile, tornando o manuseio de arquivos muito mais conveniente e robusto.

A classe UploadedFile fornece métodos para:

Essa classe ajuda você a evitar armadilhas comuns com uploads de arquivos, como lidar com erros ou mover arquivos de forma segura.

Uso Básico

Acessando Arquivos Enviados de uma Requisição

A maneira recomendada de acessar arquivos enviados é através do objeto de requisição:

Flight::route('POST /upload', function() {
    // Para um campo de formulário nomeado <input type="file" name="myFile">
    $uploadedFiles = Flight::request()->getUploadedFiles();
    $file = $uploadedFiles['myFile'];

    // Agora você pode usar os métodos do UploadedFile
    if ($file->getError() === UPLOAD_ERR_OK) {
        $file->moveTo('/path/to/uploads/' . $file->getClientFilename());
        echo "Arquivo enviado com sucesso!";
    } else {
        echo "Falha no envio: " . $file->getError();
    }
});

Manipulando Múltiplos Uploads de Arquivos

Se o seu formulário usa name="myFiles[]" para múltiplos uploads, você obterá um array de objetos UploadedFile:

Flight::route('POST /upload', function() {
    // Para um campo de formulário nomeado <input type="file" name="myFiles[]">
    $uploadedFiles = Flight::request()->getUploadedFiles();
    foreach ($uploadedFiles['myFiles'] as $file) {
        if ($file->getError() === UPLOAD_ERR_OK) {
            $file->moveTo('/path/to/uploads/' . $file->getClientFilename());
            echo "Enviado: " . $file->getClientFilename() . "<br>";
        } else {
            echo "Falha no envio: " . $file->getClientFilename() . "<br>";
        }
    }
});

Criando uma Instância de UploadedFile Manualmente

Normalmente, você não criará um UploadedFile manualmente, mas pode fazer isso se necessário:

use flight\net\UploadedFile;

$file = new UploadedFile(
  $_FILES['myfile']['name'],
  $_FILES['myfile']['type'],
  $_FILES['myfile']['size'],
  $_FILES['myfile']['tmp_name'],
  $_FILES['myfile']['error']
);

Acessando Informações do Arquivo

Você pode facilmente obter detalhes sobre o arquivo enviado:

echo $file->getClientFilename();   // Nome original do arquivo do computador do usuário
echo $file->getClientMediaType();  // Tipo MIME (ex.: image/png)
echo $file->getSize();             // Tamanho do arquivo em bytes
echo $file->getTempName();         // Caminho temporário do arquivo no servidor
echo $file->getError();            // Código de erro de upload (0 significa sem erro)

Movendo o Arquivo Enviado

Após validar o arquivo, mova-o para uma localização permanente:

try {
  $file->moveTo('/path/to/uploads/' . $file->getClientFilename());
  echo "Arquivo enviado com sucesso!";
} catch (Exception $e) {
  echo "Falha no envio: " . $e->getMessage();
}

O método moveTo() lançará uma exceção se algo der errado (como um erro de upload ou problema de permissão).

Manipulando Erros de Upload

Se houver um problema durante o upload, você pode obter uma mensagem de erro legível por humanos:

if ($file->getError() !== UPLOAD_ERR_OK) {
  // Você pode usar o código de erro ou capturar a exceção de moveTo()
  echo "Houve um erro ao enviar o arquivo.";
}

Veja Também

Solução de Problemas

Changelog

Guides/unit_testing

Testes Unitários no Flight PHP com PHPUnit

Este guia introduz os testes unitários no Flight PHP usando PHPUnit, direcionado a iniciantes que desejam entender por que os testes unitários são importantes e como aplicá-los de forma prática. Vamos focar em testar comportamentos—garantindo que sua aplicação faça o que você espera, como enviar um e-mail ou salvar um registro—em vez de cálculos triviais. Começaremos com um manipulador de rota simples e progrediremos para um controlador mais complexo, incorporando injeção de dependências (DI) e simulação de serviços de terceiros.

Por Que Fazer Testes Unitários?

Os testes unitários garantem que seu código se comporte como esperado, capturando bugs antes que cheguem à produção. Isso é especialmente valioso no Flight, onde o roteamento leve e a flexibilidade podem levar a interações complexas. Para desenvolvedores solo ou equipes, os testes unitários atuam como uma rede de segurança, documentando o comportamento esperado e prevenindo regressões quando você revisitar o código mais tarde. Eles também melhoram o design: código difícil de testar frequentemente sinaliza classes excessivamente complexas ou fortemente acopladas.

Diferente de exemplos simplistas (ex.: testar x * y = z), vamos focar em comportamentos do mundo real, como validar entrada, salvar dados ou acionar ações como e-mails. Nosso objetivo é tornar os testes acessíveis e significativos.

Princípios Gerais de Orientação

  1. Teste Comportamentos, Não Implementações: Foque em resultados (ex.: “e-mail enviado” ou “registro salvo”) em vez de detalhes internos. Isso torna os testes robustos contra refatorações.
  2. Pare de usar Flight::: Os métodos estáticos do Flight são terrivelmente convenientes, mas tornam os testes difíceis. Você deve se acostumar a usar a variável $app de $app = Flight::app();. A $app tem todos os mesmos métodos que Flight::. Você ainda poderá usar $app->route() ou $this->app->json() no seu controlador etc. Você também deve usar o roteador real do Flight com $router = $app->router() e então poderá usar $router->get(), $router->post(), $router->group() etc. Veja Routing.
  3. Mantenha os Testes Rápidos: Testes rápidos incentivam execuções frequentes. Evite operações lentas como chamadas de banco de dados em testes unitários. Se você tiver um teste lento, é um sinal de que está escrevendo um teste de integração, não um teste unitário. Testes de integração são quando você realmente envolve bancos de dados reais, chamadas HTTP reais, envio de e-mails reais etc. Eles têm seu lugar, mas são lentos e podem ser instáveis, significando que falham às vezes por um motivo desconhecido.
  4. Use Nomes Descritivos: Os nomes dos testes devem descrever claramente o comportamento sendo testado. Isso melhora a legibilidade e a manutenibilidade.
  5. Evite Globais Como a Peste: Minimize o uso de $app->set() e $app->get(), pois eles atuam como estado global, exigindo simulações em cada teste. Prefira DI ou um contêiner DI (veja Dependency Injection Container). Mesmo usar o método $app->map() é tecnicamente um "global" e deve ser evitado em favor de DI. Use uma biblioteca de sessão como flightphp/session para que você possa simular o objeto de sessão nos seus testes. Não chame $_SESSION diretamente no seu código, pois isso injeta uma variável global no seu código, tornando-o difícil de testar.
  6. Use Injeção de Dependências: Injete dependências (ex.: PDO, mailers) em controladores para isolar a lógica e simplificar a simulação. Se você tiver uma classe com muitas dependências, considere refatorá-la em classes menores que cada uma tenha uma única responsabilidade seguindo os princípios SOLID.
  7. Simule Serviços de Terceiros: Simule bancos de dados, clientes HTTP (cURL) ou serviços de e-mail para evitar chamadas externas. Teste uma ou duas camadas profundas, mas deixe sua lógica principal rodar. Por exemplo, se sua app envia uma mensagem de texto, você NÃO quer realmente enviar uma mensagem de texto toda vez que executar seus testes, pois essas cobranças vão se acumular (e será mais lento). Em vez disso, simule o serviço de mensagem de texto e apenas verifique se seu código chamou o serviço de mensagem de texto com os parâmetros certos.
  8. Mire em Alta Cobertura, Não Perfeição: 100% de cobertura de linhas é bom, mas não significa necessariamente que tudo no seu código está testado da forma que deveria (vá em frente e pesquise cobertura de ramificação/caminho no PHPUnit). Priorize comportamentos críticos (ex.: registro de usuário, respostas de API e captura de respostas falhas).
  9. Use Controladores para Rotas: Nas suas definições de rotas, use controladores em vez de closures. A instância flight\Engine $app é injetada em todo controlador via o construtor por padrão. Nos testes, use $app = new Flight\Engine() para instanciar o Flight dentro de um teste, injete-o no seu controlador e chame métodos diretamente (ex.: $controller->register()). Veja Extending Flight e Routing.
  10. Escolha um estilo de simulação e mantenha-se fiel a ele: O PHPUnit suporta vários estilos de simulação (ex.: prophecy, mocks integrados), ou você pode usar classes anônimas que têm seus próprios benefícios como completamento de código, quebra se você alterar a definição do método etc. Apenas seja consistente em todos os seus testes. Veja PHPUnit Mock Objects.
  11. Use visibilidade protected para métodos/propriedades que você quer testar em subclasses: Isso permite que você os sobrescreva em subclasses de teste sem torná-los públicos, isso é especialmente útil para mocks de classes anônimas.

Configurando o PHPUnit

Primeiro, configure o PHPUnit no seu projeto Flight PHP usando o Composer para testes fáceis. Veja o guia de início rápido do PHPUnit para mais detalhes.

  1. No diretório do seu projeto, execute:

    composer require --dev phpunit/phpunit

    Isso instala a versão mais recente do PHPUnit como uma dependência de desenvolvimento.

  2. Crie um diretório tests na raiz do seu projeto para arquivos de teste.

  3. Adicione um script de teste ao composer.json para conveniência:

    // outro conteúdo do composer.json
"scripts": {
   "test": "phpunit --configuration phpunit.xml"
}

  4. Crie um arquivo phpunit.xml na raiz:

    <?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php">
   <testsuites>
       <testsuite name="Flight Tests">
           <directory>tests</directory>
       </testsuite>
   </testsuites>
</phpunit>

Agora, quando seus testes estiverem construídos, você pode executar composer test para executar os testes.

Testando um Manipulador de Rota Simples

Vamos começar com uma rota básica que valida a entrada de e-mail de um usuário. Vamos testar seu comportamento: retornar uma mensagem de sucesso para e-mails válidos e um erro para inválidos. Para validação de e-mail, usamos filter_var.

// index.php
$app->route('POST /register', [ UserController::class, 'register' ]);

// UserController.php
class UserController {
    protected $app;

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

    public function register() {
        $email = $this->app->request()->data->email;
        $responseArray = [];
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            $responseArray = ['status' => 'error', 'message' => 'Invalid email'];
        } else {
            $responseArray = ['status' => 'success', 'message' => 'Valid email'];
        }

        $this->app->json($responseArray);
    }
}

Para testar isso, crie um arquivo de teste. Veja Unit Testing and SOLID Principles para mais sobre estruturar testes:

// tests/UserControllerTest.php
use PHPUnit\Framework\TestCase;
use Flight;
use flight\Engine;

class UserControllerTest extends TestCase {

    public function testValidEmailReturnsSuccess() {
        $app = new Engine();
        $request = $app->request();
        $request->data->email = 'test@example.com'; // Simulate POST data
        $UserController = new UserController($app);
        $UserController->register($request->data->email);
        $response = $app->response()->getBody();
        $output = json_decode($response, true);
        $this->assertEquals('success', $output['status']);
        $this->assertEquals('Valid email', $output['message']);
    }

    public function testInvalidEmailReturnsError() {
        $app = new Engine();
        $request = $app->request();
        $request->data->email = 'invalid-email'; // Simulate POST data
        $UserController = new UserController($app);
        $UserController->register($request->data->email);
        $response = $app->response()->getBody();
        $output = json_decode($response, true);
        $this->assertEquals('error', $output['status']);
        $this->assertEquals('Invalid email', $output['message']);
    }
}

Pontos Chave:

Execute composer test para verificar se a rota se comporta como esperado. Para mais sobre requests e responses no Flight, veja a documentação relevante.

Usando Injeção de Dependências para Controladores Testáveis

Para cenários mais complexos, use injeção de dependências (DI) para tornar controladores testáveis. Evite os globais do Flight (ex.: Flight::set(), Flight::map(), Flight::register()) pois eles atuam como estado global, exigindo simulações para cada teste. Em vez disso, use o contêiner DI do Flight, DICE, PHP-DI ou DI manual.

Vamos usar flight\database\PdoWrapper em vez de PDO cru. Este wrapper é muito mais fácil de simular e testar unitariamente!

Aqui está um controlador que salva um usuário em um banco de dados e envia um e-mail de boas-vindas:

use flight\database\PdoWrapper;

class UserController {
    protected $app;
    protected $db;
    protected $mailer;

    public function __construct(Engine $app, PdoWrapper $db, MailerInterface $mailer) {
        $this->app = $app;
        $this->db = $db;
        $this->mailer = $mailer;
    }

    public function register() {
        $email = $this->app->request()->data->email;
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            // adding the return here helps unit testing to stop execution
            return $this->app->jsonHalt(['status' => 'error', 'message' => 'Invalid email']);
        }

        $this->db->runQuery('INSERT INTO users (email) VALUES (?)', [$email]);
        $this->mailer->sendWelcome($email);

        return $this->app->json(['status' => 'success', 'message' => 'User registered']);
    }
}

Pontos Chave:

Testando o Controlador com Simulações

Agora, vamos testar o comportamento do UserController: validar e-mails, salvar no banco de dados e enviar e-mails. Vamos simular o banco de dados e o mailer para isolar o controlador.

// tests/UserControllerDICTest.php
use PHPUnit\Framework\TestCase;

class UserControllerDICTest extends TestCase {
    public function testValidEmailSavesAndSendsEmail() {

        // Sometimes mixing mocking styles is necessary
        // Here we use PHPUnit's built-in mock for PDOStatement
        $statementMock = $this->createMock(PDOStatement::class);
        $statementMock->method('execute')->willReturn(true);
        // Using an anonymous class to mock PdoWrapper
        $mockDb = new class($statementMock) extends PdoWrapper {
            protected $statementMock;
            public function __construct($statementMock) {
                $this->statementMock = $statementMock;
            }

            // When we mock it this way, we are not really making a database call.
            // We can further setup this to alter the PDOStatement mock to simulate failures, etc.
            public function runQuery(string $sql, array $params = []): PDOStatement {
                return $this->statementMock;
            }
        };
        $mockMailer = new class implements MailerInterface {
            public $sentEmail = null;
            public function sendWelcome($email): bool {
                $this->sentEmail = $email;
                return true;    
            }
        };
        $app = new Engine();
        $app->request()->data->email = 'test@example.com';
        $controller = new UserControllerDIC($app, $mockDb, $mockMailer);
        $controller->register();
        $response = $app->response()->getBody();
        $result = json_decode($response, true);
        $this->assertEquals('success', $result['status']);
        $this->assertEquals('User registered', $result['message']);
        $this->assertEquals('test@example.com', $mockMailer->sentEmail);
    }

    public function testInvalidEmailSkipsSaveAndEmail() {
         $mockDb = new class() extends PdoWrapper {
            // An empty constructor bypasses the parent constructor
            public function __construct() {}
            public function runQuery(string $sql, array $params = []): PDOStatement {
                throw new Exception('Should not be called');
            }
        };
        $mockMailer = new class implements MailerInterface {
            public $sentEmail = null;
            public function sendWelcome($email): bool {
                throw new Exception('Should not be called');
            }
        };
        $app = new Engine();
        $app->request()->data->email = 'invalid-email';

        // Need to map jsonHalt to avoid exiting
        $app->map('jsonHalt', function($data) use ($app) {
            $app->json($data, 400);
        });
        $controller = new UserControllerDIC($app, $mockDb, $mockMailer);
        $controller->register();
        $response = $app->response()->getBody();
        $result = json_decode($response, true);
        $this->assertEquals('error', $result['status']);
        $this->assertEquals('Invalid email', $result['message']);
    }
}

Pontos Chave:

Simulando Demais

Tenha cuidado para não simular demais do seu código. Deixe-me dar um exemplo abaixo sobre por que isso pode ser uma coisa ruim usando nosso UserController. Vamos mudar aquela verificação em um método chamado isEmailValid (usando filter_var) e as outras novas adições em um método separado chamado registerUser.

use flight\database\PdoWrapper;
use flight\Engine;

// UserControllerDICV2.php
class UserControllerDICV2 {
    protected $app;
    protected $db;
    protected $mailer;

    public function __construct(Engine $app, PdoWrapper $db, MailerInterface $mailer) {
        $this->app = $app;
        $this->db = $db;
        $this->mailer = $mailer;
    }

    public function register() {
        $email = $this->app->request()->data->email;
        if (!$this->isEmailValid($email)) {
            // adding the return here helps unit testing to stop execution
            return $this->app->jsonHalt(['status' => 'error', 'message' => 'Invalid email']);
        }

        $this->registerUser($email);

        $this->app->json(['status' => 'success', 'message' => 'User registered']);
    }

    protected function isEmailValid($email) {
        return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
    }

    protected function registerUser($email) {
        $this->db->runQuery('INSERT INTO users (email) VALUES (?)', [$email]);
        $this->mailer->sendWelcome($email);
    }
}

E agora o teste unitário excessivamente simulado que não testa nada de verdade:

use PHPUnit\Framework\TestCase;

class UserControllerTest extends TestCase {
    public function testValidEmailSavesAndSendsEmail() {
        $app = new Engine();
        $app->request()->data->email = 'test@example.com';
        // we are skipping the extra dependency injection here cause it's "easy"
        $controller = new class($app) extends UserControllerDICV2 {
            protected $app;
            // Bypass the deps in the construct
            public function __construct($app) {
                $this->app = $app;
            }

            // We'll just force this to be valid.
            protected function isEmailValid($email) {
                return true; // Always return true, bypassing real validation
            }

            // Bypass the actual DB and mailer calls
            protected function registerUser($email) {
                return false;
            }
        };
        $controller->register();
        $response = $app->response()->getBody();
        $result = json_decode($response, true);
        $this->assertEquals('success', $result['status']);
        $this->assertEquals('User registered', $result['message']);
    }
}

Hurra, temos testes unitários e eles estão passando! Mas espere, e se eu realmente mudar o funcionamento interno de isEmailValid ou registerUser? Meus testes ainda passarão porque eu simulei toda a funcionalidade. Deixe-me mostrar o que quero dizer.

// UserControllerDICV2.php
class UserControllerDICV2 {

    // ... other methods ...

    protected function isEmailValid($email) {
        // Changed logic
        $validEmail = filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
        // Now it should only have a specific domain
        $validDomain = strpos($email, '@example.com') !== false; 
        return $validEmail && $validDomain;
    }
}

Se eu executar meus testes unitários acima, eles ainda passam! Mas porque eu não estava testando para comportamento (deixando realmente alguma parte do código rodar), eu potencialmente codifiquei um bug esperando para acontecer na produção. O teste deveria ser modificado para considerar o novo comportamento, e também o oposto de quando o comportamento não é o que esperamos.

Exemplo Completo

Você pode encontrar um exemplo completo de um projeto Flight PHP com testes unitários no GitHub: n0nag0n/flight-unit-tests-guide. Para uma compreensão mais profunda, veja Unit Testing and SOLID Principles.

Armadilhas Comuns

Escalando com Testes Unitários

Os testes unitários brilham em projetos maiores ou quando revisitando código após meses. Eles documentam comportamentos e capturam regressões, poupando você de re-aprender sua app. Para devs solo, teste caminhos críticos (ex.: cadastro de usuário, processamento de pagamento). Para equipes, testes garantem comportamento consistente em contribuições. Veja Why Frameworks? para mais sobre os benefícios de usar frameworks e testes.

Contribua com suas próprias dicas de teste para o repositório de documentação do Flight PHP!

Escrito por n0nag0n 2025

Guides/blog

Construindo um Blog Simples com Flight PHP

Este guia o orienta na criação de um blog básico usando o framework Flight PHP. Você configurará um projeto, definirá rotas, gerenciará postagens com JSON e as renderizará com o motor de templates Latte—todos mostrando a simplicidade e flexibilidade do Flight. Ao final, você terá um blog funcional com uma página inicial, páginas de postagens individuais e um formulário de criação.

Pré-requisitos

Passo 1: Configure Seu Projeto

Comece criando um novo diretório de projeto e instalando o Flight via Composer.

  1. Criar um Diretório:

    mkdir flight-blog
cd flight-blog

  2. Instalar o Flight:

    composer require flightphp/core

  3. Criar um Diretório Público: O Flight utiliza um único ponto de entrada (index.php). Crie uma pasta public/ para ele:

    mkdir public

  4. index.php Básico: Crie public/index.php com uma rota simples de “hello world”:

    <?php
require '../vendor/autoload.php';

Flight::route('/', function () {
   echo 'Olá, Flight!';
});

Flight::start();

  5. Executar o Servidor Interno: Teste sua configuração com o servidor de desenvolvimento do PHP:

    php -S localhost:8000 -t public/

    Acesse http://localhost:8000 para ver “Olá, Flight!”.

Passo 2: Organize a Estrutura do Seu Projeto

Para uma configuração limpa, estruture seu projeto da seguinte forma:

flight-blog/
├── app/
│   ├── config/
│   └── views/
├── data/
├── public/
│   └── index.php
├── vendor/
└── composer.json

Passo 3: Instalar e Configurar o Latte

O Latte é um motor de templates leve que se integra bem com o Flight.

  1. Instalar o Latte:

    composer require latte/latte

  2. Configurar o Latte no Flight: Atualize public/index.php para registrar o Latte como o motor de visualização:

    <?php
require '../vendor/autoload.php';

use Latte\Engine;

Flight::register('view', Engine::class, [], function ($latte) {
   $latte->setTempDirectory(__DIR__ . '/../cache/');
   $latte->setLoader(new \Latte\Loaders\FileLoader(__DIR__ . '/../app/views/'));
});

Flight::route('/', function () {
   Flight::view()->render('home.latte', ['title' => 'Meu Blog']);
});

Flight::start();

  3. Criar um Template de Layout: Em app/views/layout.latte:

    <!DOCTYPE html>
<html>
<head>
<title>{$title}</title>
</head>
<body>
<header>
    <h1>Meu Blog</h1>
    <nav>
        <a href="/">Home</a> | 
        <a href="/create">Criar uma Postagem</a>
    </nav>
</header>
<main>
    {block content}{/block}
</main>
<footer>
    <p>&copy; {date('Y')} Blog Flight</p>
</footer>
</body>
</html>

  4. Criar um Template de Página Inicial: Em app/views/home.latte:

    {extends 'layout.latte'}

{block content}
    <h2>{$title}</h2>
    <ul>
    {foreach $posts as $post}
        <li><a href="/post/{$post['slug']}">{$post['title']}</a></li>
    {/foreach}
    </ul>
{/block}

    Reinicie o servidor se você saiu dele e visite http://localhost:8000 para ver a página renderizada.

  5. Criar um Arquivo de Dados:

    Use um arquivo JSON para simular um banco de dados para simplicidade.

    Em data/posts.json:

    [
   {
       "slug": "primeira-postagem",
       "title": "Minha Primeira Postagem",
       "content": "Esta é minha primeira postagem no blog com Flight PHP!"
   }
]

Passo 4: Definir Rotas

Separe suas rotas em um arquivo de configuração para melhor organização.

  1. Criar routes.php: Em app/config/routes.php:

    <?php
Flight::route('/', function () {
   Flight::view()->render('home.latte', ['title' => 'Meu Blog']);
});

Flight::route('/post/@slug', function ($slug) {
   Flight::view()->render('post.latte', ['title' => 'Post: ' . $slug, 'slug' => $slug]);
});

Flight::route('GET /create', function () {
   Flight::view()->render('create.latte', ['title' => 'Criar uma Postagem']);
});

  2. Atualizar index.php: Inclua o arquivo de rotas:

    <?php
require '../vendor/autoload.php';

use Latte\Engine;

Flight::register('view', Engine::class, [], function ($latte) {
   $latte->setTempDirectory(__DIR__ . '/../cache/');
   $latte->setLoader(new \Latte\Loaders\FileLoader(__DIR__ . '/../app/views/'));
});

require '../app/config/routes.php';

Flight::start();

Passo 5: Armazenar e Recuperar Postagens do Blog

Adicione os métodos para carregar e salvar postagens.

  1. Adicionar um Método de Postagens: Em index.php, adicione um método para carregar postagens:

    Flight::map('posts', function () {
   $file = __DIR__ . '/../data/posts.json';
   return json_decode(file_get_contents($file), true);
});

  2. Atualizar Rotas: Modifique app/config/routes.php para usar postagens:

    <?php
Flight::route('/', function () {
   $posts = Flight::posts();
   Flight::view()->render('home.latte', [
       'title' => 'Meu Blog',
       'posts' => $posts
   ]);
});

Flight::route('/post/@slug', function ($slug) {
   $posts = Flight::posts();
   $post = array_filter($posts, fn($p) => $p['slug'] === $slug);
   $post = reset($post) ?: null;
   if (!$post) {
       Flight::notFound();
       return;
   }
   Flight::view()->render('post.latte', [
       'title' => $post['title'],
       'post' => $post
   ]);
});

Flight::route('GET /create', function () {
   Flight::view()->render('create.latte', ['title' => 'Criar uma Postagem']);
});

Passo 6: Criar Templates

Atualize seus templates para exibir postagens.

  1. Página de Postagem (app/views/post.latte):

    {extends 'layout.latte'}

{block content}
    <h2>{$post['title']}</h2>
    <div class="post-content">
        <p>{$post['content']}</p>
    </div>
{/block}

Passo 7: Adicionar Criação de Postagens

Manipule a submissão de formulário para adicionar novas postagens.

  1. Criar Formulário (app/views/create.latte):

    {extends 'layout.latte'}

{block content}
    <h2>{$title}</h2>
    <form method="POST" action="/create">
        <div class="form-group">
            <label for="title">Título:</label>
            <input type="text" name="title" id="title" required>
        </div>
        <div class="form-group">
            <label for="content">Conteúdo:</label>
            <textarea name="content" id="content" required></textarea>
        </div>
        <button type="submit">Salvar Postagem</button>
    </form>
{/block}

  2. Adicionar Rota POST: Em app/config/routes.php:

    Flight::route('POST /create', function () {
   $request = Flight::request();
   $title = $request->data['title'];
   $content = $request->data['content'];
   $slug = strtolower(str_replace(' ', '-', $title));

   $posts = Flight::posts();
   $posts[] = ['slug' => $slug, 'title' => $title, 'content' => $content];
   file_put_contents(__DIR__ . '/../../data/posts.json', json_encode($posts, JSON_PRETTY_PRINT));

   Flight::redirect('/');
});

  3. Teste:

    • Acesse http://localhost:8000/create.
    • Envie uma nova postagem (por exemplo, “Segunda Postagem” com algum conteúdo).
    • Verifique a página inicial para vê-la listada.

Passo 8: Melhorar com Tratamento de Erros

Sobreponha o método notFound para uma melhor experiência de 404.

Em index.php:

Flight::map('notFound', function () {
    Flight::view()->render('404.latte', ['title' => 'Página Não Encontrada']);
});

Crie app/views/404.latte:

{extends 'layout.latte'}

{block content}
    <h2>404 - {$title}</h2>
    <p>Desculpe, essa página não existe!</p>
{/block}

Próximos Passos

Conclusão

Você construiu um blog simples com o Flight PHP! Este guia demonstra recursos principais como roteamento, templating com Latte e manipulação de envios de formulários—tudo isso mantendo as coisas leves. Explore a documentação do Flight para recursos mais avançados para levar seu blog adiante!

License

The MIT License (MIT)

Direitos de autor © 2024 @mikecao, @n0nag0n

É concedida permissão, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e documentação associada (arquivo PDF), para lidar com o software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do software, e permitir que as pessoas a quem o software é fornecido o façam, sujeito às seguintes condições:

O aviso de direitos de autor acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER REIVINDICAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM UMA AÇÃO DE CONTRATO, DELITO OU DE OUTRA FORMA, DECORRENTE DE, FORA DE OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTROS ACORDOS NO SOFTWARE.

About

Flight PHP Framework

Flight é um framework rápido, simples e extensível para PHP — criado para desenvolvedores que querem fazer as coisas rapidamente, sem complicações. Seja você construindo um app web clássico, uma API ultrarrápida ou experimentando com as ferramentas mais recentes impulsionadas por IA, o design de baixa pegada e direto ao ponto do Flight o torna uma escolha perfeita. Flight é projetado para ser enxuto, mas também pode lidar com requisitos de arquitetura empresarial.

Por que Escolher Flight?

Visão Geral em Vídeo

Simples o suficiente, certo?
Saiba mais sobre Flight na documentação!

Início Rápido

Para fazer uma instalação básica e rápida, instale com Composer:

composer require flightphp/core

Ou você pode baixar um zip do repositório aqui. Então, você terá um arquivo básico index.php como o seguinte:

<?php

// se instalado com composer
require 'vendor/autoload.php';
// ou se instalado manualmente por arquivo zip
// require 'flight/Flight.php';

Flight::route('/', function() {
  echo 'hello world!';
});

Flight::route('/json', function() {
  Flight::json([
    'hello' => 'world'
  ]);
});

Flight::start();

Isso é tudo! Você tem uma aplicação básica do Flight. Agora, você pode executar este arquivo com php -S localhost:8000 e visitar http://localhost:8000 no seu navegador para ver a saída.

App Skeleton/Boilerplate

Há um app de exemplo para ajudar você a iniciar seu projeto com Flight. Ele tem uma estrutura organizada, configurações básicas já definidas e lida com scripts do Composer diretamente! Confira flightphp/skeleton para um projeto pronto para uso, ou visite a página de exemplos para inspiração. Quer ver como a IA se encaixa? Explore exemplos impulsionados por IA.

Instalando o App Skeleton

Fácil o suficiente!

# Crie o novo projeto
composer create-project flightphp/skeleton my-project/
# Entre no diretório do seu novo projeto
cd my-project/
# Inicie o servidor de desenvolvimento local para começar imediatamente!
composer start

Isso criará a estrutura do projeto, configurará os arquivos necessários e você estará pronto para começar!

Alto Desempenho

Flight é um dos frameworks PHP mais rápidos disponíveis. Seu núcleo leve significa menos sobrecarga e mais velocidade — perfeito para apps tradicionais e projetos modernos impulsionados por IA. Você pode ver todos os benchmarks em TechEmpower.

Veja o benchmark abaixo com alguns outros frameworks PHP populares.

Framework Plaintext Reqs/sec JSON Reqs/sec
Flight 190,421 182,491
Yii 145,749 131,434
Fat-Free 139,238 133,952
Slim 89,588 87,348
Phalcon 95,911 87,675
Symfony 65,053 63,237
Lumen 40,572 39,700
Laravel 26,657 26,901
CodeIgniter 20,628 19,901

Flight e IA

Curioso sobre como ele lida com IA? Descubra como Flight facilita o trabalho com o seu LLM de codificação favorito!

Comunidade

Estamos no Matrix Chat

Matrix

E no Discord

Contribuindo

Existem duas maneiras de contribuir para Flight:

  1. Contribua para o framework principal visitando o repositório principal.
  2. Ajude a melhorar os docs! Este site de documentação é hospedado no Github. Se você encontrar um erro ou quiser melhorar algo, sinta-se à vontade para enviar um pull request. Adoramos atualizações e novas ideias — especialmente em torno de IA e novas tecnologias!

Requisitos

Flight requer PHP 7.4 ou superior.

Nota: PHP 7.4 é suportado porque, no momento da escrita (2024), o PHP 7.4 é a versão padrão para algumas distribuições Linux LTS. Forçar uma mudança para PHP >8 causaria problemas para esses usuários. O framework também suporta PHP >8.

Licença

Flight é liberado sob a licença MIT.

Awesome-plugins/php_cookie

Cookies

overclokk/cookie é uma biblioteca simples para gerenciar cookies em seu aplicativo.

Instalação

A instalação é simples com o composer.

composer require overclokk/cookie

Uso

O uso é tão simples quanto registrar um novo método na classe Flight.


use Overclokk\Cookie\Cookie;

/*
 * Defina em seu arquivo de inicialização ou public/index.php
 */

Flight::register('cookie', Cookie::class);

/**
 * ExampleController.php
 */

class ExampleController {
    public function login() {
        // Defina um cookie

        // você vai querer que isso seja falso para obter uma nova instância
        // use o comentário abaixo se quiser autocompletar
        /** @var \Overclokk\Cookie\Cookie $cookie */
        $cookie = Flight::cookie(false);
        $cookie->set(
            'stay_logged_in', // nome do cookie
            '1', // o valor que você deseja definir
            86400, // número de segundos que o cookie deve durar
            '/', // caminho em que o cookie estará disponível
            'example.com', // domínio em que o cookie estará disponível
            true, // o cookie só será transmitido por uma conexão HTTPS segura
            true // o cookie só estará disponível por meio do protocolo HTTP
        );

        // opcionalmente, se você quiser manter os valores padrão
        // e ter uma maneira rápida de definir um cookie por um longo tempo
        $cookie->forever('stay_logged_in', '1');
    }

    public function home() {
        // Verifique se você tem o cookie
        if (Flight::cookie()->has('stay_logged_in')) {
            // colocá-los na área do painel, por exemplo.
            Flight::redirect('/dashboard');
        }
    }
}

Awesome-plugins/php_encryption

Criptografia PHP

defuse/php-encryption é uma biblioteca que pode ser usada para criptografar e descriptografar dados. Começar a usar é bastante simples para começar a criptografar e descriptografar dados. Eles têm um ótimo tutorial que ajuda a explicar o básico de como usar a biblioteca, bem como importantes implicações de segurança relacionadas à criptografia.

Instalação

A instalação é simples com o composer.

composer require defuse/php-encryption

Configuração

Em seguida, você precisará gerar uma chave de criptografia.

vendor/bin/generate-defuse-key

Isso vai gerar uma chave que você precisará manter em segurança. Você poderia guardar a chave em seu arquivo app/config/config.php no array no final do arquivo. Embora não seja o local perfeito, é pelo menos algo.

Uso

Agora que você tem a biblioteca e uma chave de criptografia, você pode começar a criptografar e descriptografar dados.


use Defuse\Crypto\Crypto;
use Defuse\Crypto\Key;

/*
 * Defina em seu arquivo de inicialização ou public/index.php
 */

// Método de criptografia
Flight::map('encrypt', function($dados_brutos) {
    $chave_criptografia = /* $config['encryption_key'] ou um file_get_contents de onde você colocou a chave */;
    return Crypto::encrypt($dados_brutos, Key::loadFromAsciiSafeString($chave_criptografia));
});

// Método de descriptografia
Flight::map('decrypt', function($dados_criptografados) {
    $chave_criptografia = /* $config['encryption_key'] ou um file_get_contents de onde você colocou a chave */;
    try {
        $dados_brutos = Crypto::decrypt($dados_criptografados, Key::loadFromAsciiSafeString($chave_criptografia));
    } catch (Defuse\Crypto\Exception\WrongKeyOrModifiedCiphertextException $ex) {
        // Um ataque! Ou a chave errada foi carregada, ou o texto cifrado foi
        // alterado desde que foi criado - corrompido no banco de dados ou
        // intencionalmente modificado por Eve tentando realizar um ataque.

        // ... trate este caso de uma maneira adequada à sua aplicação ...
    }
    return $dados_brutos;
});

Flight::route('/encrypt', function() {
    $dados_criptografados = Flight::encrypt('Isto é um segredo');
    echo $dados_criptografados;
});

Flight::route('/decrypt', function() {
    $dados_criptografados = '...'; // Obtenha os dados criptografados de algum lugar
    $dados_descriptografados = Flight::decrypt($dados_criptografados);
    echo $dados_descriptografados;
});

Awesome-plugins/php_file_cache

flightphp/cache

Classe de cache PHP leve, simples e standalone em arquivo, bifurcada de Wruczek/PHP-File-Cache

Vantagens

Este site de documentação está usando esta biblioteca para cachear cada uma das páginas!

Clique aqui para ver o código.

Instalação

Instale via composer:

composer require flightphp/cache

Uso

O uso é bastante direto. Isso salva um arquivo de cache no diretório de cache.

use flight\Cache;

$app = Flight::app();

// Você passa o diretório onde o cache será armazenado no construtor
$app->register('cache', Cache::class, [ __DIR__ . '/../cache/' ], function(Cache $cache) {

    // Isso garante que o cache seja usado apenas no modo de produção
    // ENVIRONMENT é uma constante definida no seu arquivo de bootstrap ou em outro lugar na sua app
    $cache->setDevMode(ENVIRONMENT === 'development');
});

Obter um Valor de Cache

Você usa o método get() para obter um valor em cache. Se quiser um método de conveniência que atualize o cache se ele estiver expirado, você pode usar refreshIfExpired().


// Obter instância de cache
$cache = Flight::cache();
$data = $cache->refreshIfExpired('simple-cache-test', function () {
    return date("H:i:s"); // return data to be cached
}, 10); // 10 segundos

// ou
$data = $cache->get('simple-cache-test');
if(empty($data)) {
    $data = date("H:i:s");
    $cache->set('simple-cache-test', $data, 10); // 10 segundos
}

Armazenar um Valor de Cache

Você usa o método set() para armazenar um valor no cache.

Flight::cache()->set('simple-cache-test', 'my cached data', 10); // 10 segundos

Apagar um Valor de Cache

Você usa o método delete() para apagar um valor no cache.

Flight::cache()->delete('simple-cache-test');

Verificar se um Valor de Cache Existe

Você usa o método exists() para verificar se um valor existe no cache.

if(Flight::cache()->exists('simple-cache-test')) {
    // faça algo
}

Limpar o Cache

Você usa o método flush() para limpar todo o cache.

Flight::cache()->flush();

Extrair metadados com cache

Se você quiser extrair timestamps e outros metadados sobre uma entrada de cache, certifique-se de passar true como o parâmetro correto.

$data = $cache->refreshIfExpired("simple-cache-meta-test", function () {
    echo "Refreshing data!" . PHP_EOL;
    return date("H:i:s"); // return data to be cached
}, 10, true); // true = return with metadata
// ou
$data = $cache->get("simple-cache-meta-test", true); // true = return with metadata

/*
Exemplo de item em cache recuperado com metadados:
{
    "time":1511667506, <-- save unix timestamp
    "expire":10,       <-- expire time in seconds
    "data":"04:38:26", <-- unserialized data
    "permanent":false
}

Usando metadados, podemos, por exemplo, calcular quando o item foi salvo ou quando expira
Também podemos acessar os dados em si com a chave "data"
*/

$expiresin = ($data["time"] + $data["expire"]) - time(); // get unix timestamp when data expires and subtract current timestamp from it
$cacheddate = $data["data"]; // we access the data itself with the "data" key

echo "Última salvamento de cache: $cacheddate, expira em $expiresin segundos";

Documentação

Visite https://github.com/flightphp/cache para ver o código. Certifique-se de ver a pasta examples para maneiras adicionais de usar o cache.

Awesome-plugins/permissions

FlightPHP/Permissões

Este é um módulo de permissões que pode ser usado em seus projetos se você tiver vários papéis em seu aplicativo e cada papel tiver funcionalidades um pouco diferentes. Este módulo permite que você defina permissões para cada papel e depois verifique se o usuário atual tem permissão para acessar uma determinada página ou realizar uma determinada ação.

Clique aqui para acessar o repositório no GitHub.

Instalação

Execute composer require flightphp/permissions e pronto!

Uso

Primeiro, você precisa configurar suas permissões e, em seguida, informar ao seu aplicativo o que as permissões significam. Por fim, você verificará suas permissões com $Permissions->has(), ->can() ou is(). has() e can() têm a mesma funcionalidade, mas têm nomes diferentes para tornar seu código mais legível.

Exemplo Básico

Vamos supor que você tenha um recurso em seu aplicativo que verifica se um usuário está conectado. Você pode criar um objeto de permissões assim:

// index.php
require 'vendor/autoload.php';

// algum código 

// então você provavelmente tem algo que diz qual é o papel atual da pessoa
// provavelmente você tem algo que puxa o papel atual
// de uma variável de sessão que define isso
// depois que alguém faz o login, caso contrário eles terão um papel 'convidado' ou 'público'.
$current_role = 'admin';

// configurar permissões
$permission = new \flight\Permission($current_role);
$permission->defineRule('conectado', function($current_role) {
    return $current_role !== 'convidado';
});

// Você provavelmente vai querer persistir este objeto em algum lugar do Flight
Flight::set('permissão', $permissão);

Então em um controlador em algum lugar, você pode ter algo assim.

<?php

// algum controlador
class AlgunsController {
    public function algumaAção() {
        $permissão = Flight::get('permissão');
        if ($permissão->has('conectado')) {
            // faça algo
        } else {
            // faça algo diferente
        }
    }
}

Você também pode usar isso para rastrear se têm permissão para fazer algo em seu aplicativo. Por exemplo, se você tiver uma forma dos usuários interagirem com postagens em seu software, você pode verificar se eles têm permissão para realizar certas ações.

$current_role = 'admin';

// configurar permissões
$permission = new \flight\Permission($current_role);
$permission->defineRule('postagem', function($current_role) {
    if($current_role === 'admin') {
        $permissões = ['criar', 'ler', 'atualizar', 'apagar'];
    } else if($current_role === 'editor') {
        $permissões = ['criar', 'ler', 'atualizar'];
    } else if($current_role === 'autor') {
        $permissões = ['criar', 'ler'];
    } else if($current_role === 'contribuidor') {
        $permissões = ['criar'];
    } else {
        $permissões = [];
    }
    return $permissões;
});
Flight::set('permissão', $permissão);

Então em um controlador em algum lugar...

class ControladorDePostagem {
    public function criar() {
        $permissão = Flight::get('permissão');
        if ($permissão->can('postagem.criar')) {
            // faça algo
        } else {
            // faça algo diferente
        }
    }
}

Injetando dependências

Você pode injetar dependências no fechamento que define as permissões. Isso é útil se você tiver algum tipo de alternância, id ou qualquer outro ponto de dados que deseja verificar. O mesmo funciona para chamadas de Tipo Classe->Método, exceto que você define os argumentos no método.

Fechamentos

$Permission->defineRule('pedido', function(string $current_role, MyDependency $MyDependency = null) {
    // ... código
});

// em seu arquivo de controlador
public function criarPedido() {
    $MyDependency = Flight::myDependency();
    $permissão = Flight::get('permissão');
    if ($permissão->can('pedido.criar', $MyDependency)) {
        // faça algo
    } else {
        // faça algo diferente
    }
}

Classes

namespace MyApp;

class Permissões {

    public function pedido(string $current_role, MyDependency $MyDependency = null) {
        // ... código
    }
}

Atalho para definir permissões com classes

Você também pode usar classes para definir suas permissões. Isso é útil se você tiver muitas permissões e quiser manter seu código limpo. Você pode fazer algo assim:

<?php

// código de inicialização
$Permissões = new \flight\Permission($current_role);
$Permissões->defineRule('pedido', 'MyApp\Permissões->pedido');

// myapp/Permissões.php
namespace MyApp;

class Permissões {

    public function pedido(string $current_role, int $id_usuario) {
        // Pressupondo que você configurou isso antecipadamente
        /** @var \flight\database\PdoWrapper $db */
        $db = Flight::db();
        $permissões_permitidas = [ 'ler' ]; // todos podem visualizar um pedido
        if($current_role === 'gerente') {
            $permissões_permitidas[] = 'criar'; // gerentes podem criar pedidos
        }
        $alguma_alternancia_especial_do_db = $db->fetchField('SELECT alguma_alternancia_especial FROM ajustes WHERE id = ?', [ $id_usuario ]);
        if($alguma_alternancia_especial_do_db) {
            $permissões_permitidas[] = 'atualizar'; // se o usuário tiver uma alternância especial, ele pode atualizar pedidos
        }
        if($current_role === 'admin') {
            $permissões_permitidas[] = 'apagar'; // administradores podem excluir pedidos
        }
        return $permissões_permitidas;
    }
}

A parte legal é que também há um atalho que você pode usar (que também pode ser cacheado!!!) onde você apenas diz à classe de permissões para mapear todos os métodos de uma classe em permissões. Portanto, se você tiver um método chamado pedido() e um método chamado empresa(), esses serão mapeados automaticamente para que você possa simplesmente executar $Permissões->has('pedido.ler') ou `$Permissões->has('empresa.ler') e isso funcionará. Definir isso é muito difícil, então fique comigo aqui. Você só precisa fazer o seguinte:

Crie a classe de permissões que deseja agrupar.

class MinhasPermissões {
    public function pedido(string $current_role, int $id_pedido = 0): array {
        // código para determinar permissões
        return $array_de_permissoes;
    }

    public function empresa(string $current_role, int $id_empresa): array {
        // código para determinar permissões
        return $array_de_permissoes;
    }
}

Em seguida, torne as permissões descobríveis usando esta biblioteca.

$Permissões = new \flight\Permission($current_role);
$Permissões->defineRulesFromClassMethods(MyApp\Permissões::class);
Flight::set('permissões', $Permissões);

Finalmente, chame a permissão em sua base de código para verificar se o usuário tem permissão para realizar uma determinada permissão.

class AlgunsControlador {
    public function criarPedido() {
        if(Flight::get('permissões')->can('pedido.criar') === false) {
            die('Você não pode criar um pedido. Desculpe!');
        }
    }
}

Cache

Para habilitar o cache, consulte a simples biblioteca wruczak/phpfilecache. Um exemplo de habilitação está abaixo.


// este $app pode fazer parte do seu código, ou
// você pode simplesmente passar null e ele irá
// puxar de Flight::app() no construtor
$app = Flight::app();

// Por enquanto, aceita isso como um cache de arquivo. Outros podem ser facilmente
// adicionados no futuro. 
$Cache = new Wruczek\PhpFileCache\PhpFileCache;

$Permissões = new \flight\Permission($current_role, $app, $Cache);
$Permissões->defineRulesFromClassMethods(MyApp\Permissões::class, 3600); // 3600 é quantos segundos para armazenar em cache. Deixe isso de fora para não usar o cache

Awesome-plugins/simple_job_queue

Fila de Trabalho Simples

A Fila de Trabalho Simples é uma biblioteca que pode ser usada para processar trabalhos de forma assíncrona. Pode ser usada com beanstalkd, MySQL/MariaDB, SQLite e PostgreSQL.

Instalação

composer require n0nag0n/simple-job-queue

Uso

Para que isso funcione, você precisa de uma maneira de adicionar trabalhos à fila e uma maneira de processar os trabalhos (um trabalhador). Abaixo estão exemplos de como adicionar um trabalho à fila e como processar o trabalho.

Adicionando ao Flight

Adicionar isso ao Flight é simples e é feito usando o método register(). Abaixo está um exemplo de como adicionar isso ao Flight.

<?php
require 'vendor/autoload.php';

// Mude ['mysql'] para ['beanstalkd'] se você quiser usar beanstalkd
Flight::register('queue', n0nag0n\Job_Queue::class, ['mysql'], function($Job_Queue) {
    // se você já tiver uma conexão PDO em Flight::db();
    $Job_Queue->addQueueConnection(Flight::db());

    // ou se você estiver usando beanstalkd/Pheanstalk
    $pheanstalk = Pheanstalk\Pheanstalk::create('127.0.0.1');
    $Job_Queue->addQueueConnection($pheanstalk);
});

Adicionando um novo trabalho

Quando você adiciona um trabalho, precisa especificar um pipeline (fila). Isso é comparável a um canal no RabbitMQ ou um tubo no beanstalkd.

<?php
Flight::queue()->selectPipeline('send_important_emails');
Flight::queue()->addJob(json_encode([ 'something' => 'that', 'ends' => 'up', 'a' => 'string' ]));

Executando um trabalhador

Aqui está um arquivo de exemplo de como executar um trabalhador.

<?php

require 'vendor/autoload.php';

$Job_Queue = new n0nag0n\Job_Queue('mysql');
// Conexão PDO
$PDO = new PDO('mysql:dbname=testdb;host=127.0.0.1', 'user', 'pass');
$Job_Queue->addQueueConnection($PDO);

// ou se você estiver usando beanstalkd/Pheanstalk
$pheanstalk = Pheanstalk\Pheanstalk::create('127.0.0.1');
$Job_Queue->addQueueConnection($pheanstalk);

$Job_Queue->watchPipeline('send_important_emails');
while(true) {
    $job = $Job_Queue->getNextJobAndReserve();

    // ajuste para o que te faz dormir melhor à noite (para filas de banco de dados apenas, beanstalkd não precisa dessa instrução if)
    if(empty($job)) {
        usleep(500000);
        continue;
    }

    echo "Processando {$job['id']}\n";
    $payload = json_decode($job['payload'], true);

    try {
        $result = doSomethingThatDoesSomething($payload);

        if($result === true) {
            $Job_Queue->deleteJob($job);
        } else {
            // isso o tira da fila de prontos e o coloca em outra fila que pode ser coletada e "chutada" mais tarde.
            $Job_Queue->buryJob($job);
        }
    } catch(Exception $e) {
        $Job_Queue->buryJob($job);
    }
}

Manipulando Processos Longos com Supervisord

O Supervisord é um sistema de controle de processos que garante que seus processos de trabalhadores permaneçam em execução continuamente. Aqui está um guia mais completo sobre como configurá-lo com seu trabalhador da Fila de Trabalho Simples:

Instalando o Supervisord

# No Ubuntu/Debian
sudo apt-get install supervisor

# No CentOS/RHEL
sudo yum install supervisor

# No macOS com Homebrew
brew install supervisor

Criando um Script de Trabalhador

Primeiro, salve seu código de trabalhador em um arquivo PHP dedicado:

<?php

require 'vendor/autoload.php';

$Job_Queue = new n0nag0n\Job_Queue('mysql');
// Conexão PDO
$PDO = new PDO('mysql:dbname=your_database;host=127.0.0.1', 'username', 'password');
$Job_Queue->addQueueConnection($PDO);

// Defina o pipeline a ser monitorado
$Job_Queue->watchPipeline('send_important_emails');

// Registre o início do trabalhador
echo date('Y-m-d H:i:s') . " - Trabalhador iniciado\n";

while(true) {
    $job = $Job_Queue->getNextJobAndReserve();

    if(empty($job)) {
        usleep(500000); // Durma por 0,5 segundos
        continue;
    }

    echo date('Y-m-d H:i:s') . " - Processando trabalho {$job['id']}\n";
    $payload = json_decode($job['payload'], true);

    try {
        $result = doSomethingThatDoesSomething($payload);

        if($result === true) {
            $Job_Queue->deleteJob($job);
            echo date('Y-m-d H:i:s') . " - Trabalho {$job['id']} completado com sucesso\n";
        } else {
            $Job_Queue->buryJob($job);
            echo date('Y-m-d H:i:s') . " - Trabalho {$job['id']} falhou, enterrado\n";
        }
    } catch(Exception $e) {
        $Job_Queue->buryJob($job);
        echo date('Y-m-d H:i:s') . " - Exceção ao processar o trabalho {$job['id']}: {$e->getMessage()}\n";
    }
}

Configurando o Supervisord

Crie um arquivo de configuração para seu trabalhador:

[program:email_worker]
command=php /path/to/worker.php
directory=/path/to/project
autostart=true
autorestart=true
startretries=3
stderr_logfile=/var/log/simple_job_queue_err.log
stdout_logfile=/var/log/simple_job_queue.log
user=www-data
numprocs=2
process_name=%(program_name)s_%(process_num)02d

Principais Opções de Configuração:

Gerenciando Trabalhadores com Supervisorctl

Após criar ou modificar a configuração:

# Recarregar a configuração do supervisor
sudo supervisorctl reread
sudo supervisorctl update

# Controlar processos de trabalhadores específicos
sudo supervisorctl start email_worker:*
sudo supervisorctl stop email_worker:*
sudo supervisorctl restart email_worker:*
sudo supervisorctl status email_worker:*

Executando Múltiplos Pipelines

Para múltiplos pipelines, crie arquivos de trabalhadores e configurações separados:

[program:email_worker]
command=php /path/to/email_worker.php
# ... outras configurações ...

[program:notification_worker]
command=php /path/to/notification_worker.php
# ... outras configurações ...

Monitoramento e Logs

Verifique os logs para monitorar a atividade dos trabalhadores:

# Ver logs
sudo tail -f /var/log/simple_job_queue.log

# Verificar status
sudo supervisorctl status

Essa configuração garante que seus trabalhadores de tarefas continuem em execução mesmo após falhas, reinicializações de servidor ou outros problemas, tornando seu sistema de fila confiável para ambientes de produção.

Awesome-plugins/n0nag0n_wordpress

Integração com WordPress: n0nag0n/wordpress-integration-for-flight-framework

Quer usar o Flight PHP dentro do seu site WordPress? Este plugin facilita muito! Com n0nag0n/wordpress-integration-for-flight-framework, você pode executar um aplicativo Flight completo ao lado da sua instalação WordPress—perfeito para criar APIs personalizadas, microservices ou até aplicativos completos sem sair do conforto do WordPress.

O Que Ele Faz?

Instalação

  1. Carregue a pasta flight-integration no diretório /wp-content/plugins/.
  2. Ative o plugin no admin do WordPress (menu Plugins).
  3. Vá para Configurações > Flight Framework para configurar o plugin.
  4. Defina o caminho do vendor para a sua instalação do Flight (ou use Composer para instalar o Flight).
  5. Configure o caminho da pasta do seu app e crie a estrutura de pastas (o plugin pode ajudar com isso!).
  6. Comece a criar o seu aplicativo Flight!

Exemplos de Uso

Exemplo Básico de Rota

No seu arquivo app/config/routes.php:

Flight::route('GET /api/hello', function() {
    Flight::json(['message' => 'Hello World!']);
});

Exemplo de Controller

Crie um controller em app/controllers/ApiController.php:

namespace app\controllers;

use Flight;

class ApiController {
    public function getUsers() {
        // Você pode usar funções do WordPress dentro do Flight!
        $users = get_users();
        $result = [];
        foreach($users as $user) {
            $result[] = [
                'id' => $user->ID,
                'name' => $user->display_name,
                'email' => $user->user_email
            ];
        }
        Flight::json($result);
    }
}

Em seguida, no seu routes.php:

Flight::route('GET /api/users', [app\controllers\ApiController::class, 'getUsers']);

FAQ

P: Preciso saber sobre Flight para usar este plugin?
R: Sim, isso é para desenvolvedores que querem usar o Flight dentro do WordPress. Conhecimento básico sobre roteamento e manipulação de solicitações do Flight é recomendado.

P: Isso vai deixar meu site WordPress mais lento?
R: Não! O plugin processa apenas as solicitações que correspondem às rotas do Flight. Todas as outras solicitações vão para o WordPress como de costume.

P: Posso usar funções do WordPress no meu app Flight?
R: Absolutamente! Você tem acesso total a todas as funções, hooks e globals do WordPress dentro das suas rotas e controllers do Flight.

P: Como crio rotas personalizadas?
R: Defina suas rotas no arquivo config/routes.php na pasta do seu app. Consulte o arquivo de amostra criado pelo gerador de estrutura de pastas para exemplos.

Registro de Alterações

1.0.0
Lançamento inicial.

Para mais informações, consulte o GitHub repo.

Awesome-plugins/ghost_session

Ghostff/Session

Gerenciador de Sessões PHP (não bloqueante, flash, segmento, criptografia de sessão). Usa PHP open_ssl para criptografia/descriptografia opcional dos dados de sessão. Suporta File, MySQL, Redis e Memcached.

Clique here para visualizar o código.

Instalação

Instale com composer.

composer require ghostff/session

Configuração Básica

Você não precisa passar nada para usar as configurações padrão com sua sessão. Você pode ler sobre mais configurações no Github Readme.

use Ghostff\Session\Session;

require 'vendor/autoload.php';

$app = Flight::app();

$app->register('session', Session::class);

// uma coisa a lembrar é que você deve commitar sua sessão em cada carregamento de página
// ou você precisará executar auto_commit em sua configuração.

Exemplo Simples

Aqui vai um exemplo simples de como você pode usar isso.

Flight::route('POST /login', function() {
    $session = Flight::session();

    // faça sua lógica de login aqui
    // valide a senha, etc.

    // se o login for bem-sucedido
    $session->set('is_logged_in', true);
    $session->set('user', $user);

    // toda vez que você escrever na sessão, deve commitá-la deliberadamente.
    $session->commit();
});

// Esta verificação poderia estar na lógica da página restrita, ou envolvida com middleware.
Flight::route('/some-restricted-page', function() {
    $session = Flight::session();

    if(!$session->get('is_logged_in')) {
        Flight::redirect('/login');
    }

    // faça sua lógica de página restrita aqui
});

// a versão com middleware
Flight::route('/some-restricted-page', function() {
    // lógica de página regular
})->addMiddleware(function() {
    $session = Flight::session();

    if(!$session->get('is_logged_in')) {
        Flight::redirect('/login');
    }
});

Exemplo Mais Complexo

Aqui vai um exemplo mais complexo de como você pode usar isso.

use Ghostff\Session\Session;

require 'vendor/autoload.php';

$app = Flight::app();

// defina um caminho personalizado para o arquivo de configuração da sessão como o primeiro argumento
// ou forneça o array personalizado
$app->register('session', Session::class, [ 
    [
        // se você quiser armazenar seus dados de sessão em um banco de dados (bom para algo como, "deslogar de todos os dispositivos" funcionalidade)
        Session::CONFIG_DRIVER        => Ghostff\Session\Drivers\MySql::class,
        Session::CONFIG_ENCRYPT_DATA  => true,
        Session::CONFIG_SALT_KEY      => hash('sha256', 'my-super-S3CR3T-salt'), // por favor, mude isso para algo mais
        Session::CONFIG_AUTO_COMMIT   => true, // faça isso apenas se necessário e/ou se for difícil commitar() sua sessão.
                                                // adicionalmente, você poderia fazer Flight::after('start', function() { Flight::session()->commit(); });
        Session::CONFIG_MYSQL_DS         => [
            'driver'    => 'mysql',             # Driver do banco de dados para PDO dns ex(mysql:host=...;dbname=...)
            'host'      => '127.0.0.1',         # Host do banco de dados
            'db_name'   => 'my_app_database',   # Nome do banco de dados
            'db_table'  => 'sessions',          # Tabela do banco de dados
            'db_user'   => 'root',              # Usuário do banco de dados
            'db_pass'   => '',                  # Senha do banco de dados
            'persistent_conn'=> false,          # Evite a sobrecarga de estabelecer uma nova conexão toda vez que um script precisa falar com um banco de dados, resultando em uma aplicação web mais rápida. ENCONTRE O LADO NEGATIVO VOCÊ MESMO
        ]
    ] 
]);

Ajuda! Meus Dados de Sessão Não Estão Persistindo!

Você está definindo seus dados de sessão e eles não estão persistindo entre as solicitações? Talvez você tenha esquecido de commitar seus dados de sessão. Você pode fazer isso chamando $session->commit() após definir seus dados de sessão.

Flight::route('POST /login', function() {
    $session = Flight::session();

    // faça sua lógica de login aqui
    // valide a senha, etc.

    // se o login for bem-sucedido
    $session->set('is_logged_in', true);
    $session->set('user', $user);

    // toda vez que você escrever na sessão, deve commitá-la deliberadamente.
    $session->commit();
});

A outra forma de contornar isso é quando você configura seu serviço de sessão, você tem que definir auto_commit como true em sua configuração. Isso fará com que seus dados de sessão sejam commitados automaticamente após cada solicitação.

$app->register('session', Session::class, [ 'path/to/session_config.php', bin2hex(random_bytes(32)) ], function(Session $session) {
        $session->updateConfiguration([
            Session::CONFIG_AUTO_COMMIT   => true,
        ]);
    }
);

Adicionalmente, você poderia fazer Flight::after('start', function() { Flight::session()->commit(); }); para commitar seus dados de sessão após cada solicitação.

Documentação

Visite o Github Readme para a documentação completa. As opções de configuração são bem documentadas no arquivo default_config.php em si. O código é simples de entender se você quiser explorar este pacote você mesmo.

Awesome-plugins/async

Async

Async é um pequeno pacote para o framework Flight que permite executar seus aplicativos Flight dentro de servidores e runtimes assíncronos como Swoole, AdapterMan, ReactPHP, Amp, RoadRunner, Workerman, etc. De fábrica, ele inclui adaptadores para Swoole e AdapterMan.

O objetivo: desenvolver e depurar com PHP-FPM (ou o servidor integrado) e alternar para Swoole (ou outro driver assíncrono) para produção com mudanças mínimas.

Requisitos

Instalação

Instale via composer:

composer require flightphp/async

Se você planeja executar com Swoole, instale a extensão:

# usando pecl
pecl install swoole
# ou openswoole
pecl install openswoole

# ou com um gerenciador de pacotes (exemplo Debian/Ubuntu)
sudo apt-get install php-swoole

Exemplo rápido com Swoole

Abaixo está uma configuração mínima que mostra como suportar tanto PHP-FPM (ou servidor integrado) quanto Swoole usando o mesmo código base.

Arquivos que você precisará no seu projeto:

index.php

Este arquivo é um simples interruptor que força o aplicativo a executar no modo PHP para desenvolvimento.

// index.php
<?php

define('NOT_SWOOLE', true);

include 'swoole_server.php';

swoole_server.php

Este arquivo inicializa seu aplicativo Flight e iniciará o driver Swoole quando NOT_SWOOLE não estiver definido.

// swoole_server.php
<?php

require_once __DIR__ . '/vendor/autoload.php';

$app = Flight::app();

$app->route('/', function() use ($app) {
    $app->json(['hello' => 'world']);
});

if (!defined('NOT_SWOOLE')) {
    // Require a classe SwooleServerDriver quando executando no modo Swoole.
    require_once __DIR__ . '/SwooleServerDriver.php';

    Swoole\Runtime::enableCoroutine();
    $Swoole_Server = new SwooleServerDriver('127.0.0.1', 9501, $app);
    $Swoole_Server->start();
} else {
    $app->start();
}

SwooleServerDriver.php

Um driver conciso que mostra como conectar requisições Swoole ao Flight usando o AsyncBridge e os adaptadores Swoole.

// SwooleServerDriver.php
<?php

use flight\adapter\SwooleAsyncRequest;
use flight\adapter\SwooleAsyncResponse;
use flight\AsyncBridge;
use flight\Engine;
use Swoole\HTTP\Server as SwooleServer;
use Swoole\HTTP\Request as SwooleRequest;
use Swoole\HTTP\Response as SwooleResponse;

class SwooleServerDriver {
    protected $Swoole;
    protected $app;

    public function __construct(string $host, int $port, Engine $app) {
        $this->Swoole = new SwooleServer($host, $port);
        $this->app = $app;

        $this->setDefault();
        $this->bindWorkerEvents();
        $this->bindHttpEvent();
    }

    protected function setDefault() {
        $this->Swoole->set([
            'daemonize'             => false,
            'dispatch_mode'         => 1,
            'max_request'           => 8000,
            'open_tcp_nodelay'      => true,
            'reload_async'          => true,
            'max_wait_time'         => 60,
            'enable_reuse_port'     => true,
            'enable_coroutine'      => true,
            'http_compression'      => false,
            'enable_static_handler' => true,
            'document_root'         => __DIR__,
            'static_handler_locations' => ['/css', '/js', '/images', '/.well-known'],
            'buffer_output_size'    => 4 * 1024 * 1024,
            'worker_num'            => 4,
        ]);

        $app = $this->app;
        $app->map('stop', function (?int $code = null) use ($app) {
            if ($code !== null) {
                $app->response()->status($code);
            }
        });
    }

    protected function bindHttpEvent() {
        $app = $this->app;
        $AsyncBridge = new AsyncBridge($app);

        $this->Swoole->on('Start', function(SwooleServer $server) {
            echo "Servidor HTTP Swoole iniciado em http://127.0.0.1:9501\n";
        });

        $this->Swoole->on('Request', function (SwooleRequest $request, SwooleResponse $response) use ($AsyncBridge) {
            $SwooleAsyncRequest = new SwooleAsyncRequest($request);
            $SwooleAsyncResponse = new SwooleAsyncResponse($response);

            $AsyncBridge->processRequest($SwooleAsyncRequest, $SwooleAsyncResponse);

            $response->end();
            gc_collect_cycles();
        });
    }

    protected function bindWorkerEvents() {
        $createPools = function() {
            // criar pools de conexão específicos do worker aqui
        };
        $closePools = function() {
            // fechar pools / limpeza aqui
        };
        $this->Swoole->on('WorkerStart', $createPools);
        $this->Swoole->on('WorkerStop', $closePools);
        $this->Swoole->on('WorkerError', $closePools);
    }

    public function start() {
        $this->Swoole->start();
    }
}

Executando o servidor

Dica: Para produção, use um proxy reverso (Nginx) na frente do Swoole para lidar com TLS, arquivos estáticos e balanceamento de carga.

Notas de configuração

O driver Swoole expõe várias opções de configuração:

Ajuste esses valores para se adequar aos recursos do seu host e padrões de tráfego.

Tratamento de erros

AsyncBridge traduz erros do Flight em respostas HTTP adequadas. Você também pode adicionar tratamento de erros em nível de rota:

$app->route('/*', function() use ($app) {
    try {
        // lógica da rota
    } catch (Exception $e) {
        $app->response()->status(500);
        $app->json(['error' => $e->getMessage()]);
    }
});

AdapterMan e outros runtimes

AdapterMan é suportado como um adaptador de runtime alternativo. O pacote é projetado para ser adaptável — adicionar ou usar outros adaptadores geralmente segue o mesmo padrão: converter a requisição/resposta do servidor em requisição/resposta do Flight via AsyncBridge e os adaptadores específicos do runtime.

Awesome-plugins/migrations

Migrations

Uma migração para o seu projeto é o acompanhamento de todas as alterações de banco de dados envolvidas no seu projeto. byjg/php-migration é uma biblioteca central muito útil para começar.

Instalando

Biblioteca PHP

Se você quiser usar apenas a Biblioteca PHP em seu projeto:

composer require "byjg/migration"

Interface de Linha de Comando

A interface de linha de comando é autônoma e não requer instalação com seu projeto.

Você pode instalar globalmente e criar um link simbólico

composer require "byjg/migration-cli"

Por favor, visite byjg/migration-cli para obter mais informações sobre Migration CLI.

Bancos de dados suportados

Banco de dados Driver String de Conexão
Sqlite pdo_sqlite sqlite:///caminho/para/arquivo
MySql/MariaDb pdo_mysql mysql://usuario:senha@hostname:porta/banco
Postgres pdo_pgsql pgsql://usuario:senha@hostname:porta/banco
Sql Server pdo_dblib, pdo_sysbase Linux dblib://usuario:senha@hostname:porta/banco
Sql Server pdo_sqlsrv Windows sqlsrv://usuario:senha@hostname:porta/banco

Como Funciona?

A Migração de Banco de Dados utiliza SQL PURO para gerenciar a versionamento do banco de dados. Para funcionar, você precisa de:

Os Scripts SQL

Os scripts são divididos em três conjuntos de scripts:

O diretório dos scripts é:

 <diretório raiz>
     |
     +-- base.sql
     |
     +-- /migrations
              |
              +-- /up
                   |
                   +-- 00001.sql
                   +-- 00002.sql
              +-- /down
                   |
                   +-- 00000.sql
                   +-- 00001.sql

Ambiente de Desenvolvimento Múltiplo

Se você trabalha com vários desenvolvedores e múltiplas ramificações, pode ser muito difícil determinar qual é o próximo número.

Nesse caso, você tem o sufixo "-dev" após o número da versão.

Veja o cenário:

Em ambos os casos, os desenvolvedores criarão um arquivo chamado 43-dev.sql. Ambos os desenvolvedores migrarão para CIMA e para BAIXO sem problemas e sua versão local será 43.

Mas o desenvolvedor 1 mesclou suas alterações e criou uma versão final 43.sql (git mv 43-dev.sql 43.sql). Se o desenvolvedor 2 atualizar sua ramificação local, ele terá um arquivo 43.sql (do dev 1) e seu arquivo 43-dev.sql. Se ele tentar migrar para CIMA ou para BAIXO, o script de migração irá falhar e alertá-lo que há DUAS versões 43. Nesse caso, o desenvolvedor 2 terá que atualizar seu arquivo para 44-dev.sql e continuar a trabalhar até mesclar suas alterações e gerar uma versão final.

Usando a API PHP e Integrando-a em seus projetos

O uso básico é

Veja um exemplo:

<?php
// Criar o URI de Conexão
// Veja mais: https://github.com/byjg/anydataset#connection-based-on-uri
$connectionUri = new \ByJG\Util\Uri('mysql://migrateuser:migratepwd@localhost/migratedatabase');

// Registrar o Banco de Dados ou Bancos de Dados que podem manipular esse URI:
\ByJG\DbMigration\Migration::registerDatabase(\ByJG\DbMigration\Database\MySqlDatabase::class);

// Criar a instância de Migração
$migration = new \ByJG\DbMigration\Migration($connectionUri, '.');

// Adicionar uma função de progresso de callback para receber informações da execução
$migration->addCallbackProgress(function ($action, $currentVersion, $fileInfo) {
    echo "$action, $currentVersion, ${fileInfo['description']}\n";
});

// Restaurar o banco de dados usando o script "base.sql"
// e executar TODOS os scripts existentes para subir a versão do banco de dados para a versão mais recente
$migration->reset();

// Executar TODOS os scripts existentes para subir ou descer a versão do banco de dados
// da versão atual até o número $version;
// Se o número da versão não for especificado, migrar até a última versão do banco de dados
$migration->update($version = null);

O objeto Migration controla a versão do banco de dados.

Criando um controle de versão em seu projeto

<?php
// Registrar o Banco de Dados ou Bancos de Dados que podem manipular esse URI:
\ByJG\DbMigration\Migration::registerDatabase(\ByJG\DbMigration\Database\MySqlDatabase::class);

// Criar a instância de Migração
$migration = new \ByJG\DbMigration\Migration($connectionUri, '.');

// Este comando criará a tabela de versões em seu banco de dados
$migration->createVersion();

Obtendo a versão atual

<?php
$migration->getCurrentVersion();

Adicionar Callback para controlar o progresso

<?php
$migration->addCallbackProgress(function ($command, $version, $fileInfo) {
    echo "Executando Comando: $command na versão $version - ${fileInfo['description']}, ${fileInfo['exists']}, ${fileInfo['file']}, ${fileInfo['checksum']}\n";
});

Obtendo a instância do Driver de Db

<?php
$migration->getDbDriver();

Para utilizá-lo, visite: https://github.com/byjg/anydataset-db

Evitando Migração Parcial (não disponível para MySQL)

Uma migração parcial é quando o script de migração é interrompido no meio do processo devido a um erro ou uma interrupção manual.

A tabela de migração ficará com o status partial up ou partial down e precisará ser corrigida manualmente antes que possa ser migrada novamente.

Para evitar essa situação, você pode especificar que a migração será executada em um contexto transacional. Se o script de migração falhar, a transação será revertida e a tabela de migração será marcada como complete e a versão será a imediatamente anterior antes do script que causou o erro.

Para habilitar esse recurso, você precisa chamar o método withTransactionEnabled passando true como parâmetro:

<?php
$migration->withTransactionEnabled(true);

NOTA: Este recurso não está disponível para MySQL, pois não suporta comandos DDL dentro de uma transação. Se você usar este método com MySQL, a Migração irá ignorá-lo silenciosamente. Mais informações: https://dev.mysql.com/doc/refman/8.0/en/cannot-roll-back.html

Dicas para escrever migrações SQL para Postgres

Ao criar gatilhos e funções SQL

-- FAÇA
CREATE FUNCTION emp_stamp() RETURNS trigger AS $emp_stamp$
    BEGIN
        -- Verifique se empname e salary foram fornecidos
        IF NEW.empname IS NULL THEN
            RAISE EXCEPTION 'empname não pode ser nulo'; -- não importa se esses comentários estão em branco ou não
        END IF; --
        IF NEW.salary IS NULL THEN
            RAISE EXCEPTION '% não pode ter salário nulo', NEW.empname; --
        END IF; --

        -- Quem trabalha para nós quando eles devem pagar por isso?
        IF NEW.salary < 0 THEN
            RAISE EXCEPTION '% não pode ter um salário negativo', NEW.empname; --
        END IF; --

        -- Lembre-se de quem mudou a folha de pagamento quando
        NEW.last_date := current_timestamp; --
        NEW.last_user := current_user; --
        RETURN NEW; --
    END; --
$emp_stamp$ LANGUAGE plpgsql;

-- NÃO FAÇA
CREATE FUNCTION emp_stamp() RETURNS trigger AS $emp_stamp$
    BEGIN
        -- Verifique se empname e salary foram fornecidos
        IF NEW.empname IS NULL THEN
            RAISE EXCEPTION 'empname não pode ser nulo';
        END IF;
        IF NEW.salary IS NULL THEN
            RAISE EXCEPTION '% não pode ter salário nulo', NEW.empname;
        END IF;

        -- Quem trabalha para nós quando eles devem pagar por isso?
        IF NEW.salary < 0 THEN
            RAISE EXCEPTION '% não pode ter um salário negativo', NEW.empname;
        END IF;

        -- Lembre-se de quem mudou a folha de pagamento quando
        NEW.last_date := current_timestamp;
        NEW.last_user := current_user;
        RETURN NEW;
    END;
$emp_stamp$ LANGUAGE plpgsql;

Como a camada de abstração de banco de dados PDO não pode executar lotes de instruções SQL, quando byjg/migration lê um arquivo de migração, ele tem que dividir todo o conteúdo do arquivo SQL nos ponto e vírgula e executar as instruções uma a uma. No entanto, há um tipo de instrução que pode ter múltiplos ponto e vírgula em seu corpo: funções.

Para ser capaz de analisar funções corretamente, byjg/migration 2.1.0 começou a dividir arquivos de migração na sequência ponto e vírgula + EOL em vez de apenas no ponto e vírgula. Dessa forma, se você adicionar um comentário vazio após cada ponto e vírgula interno de uma definição de função, byjg/migration poderá analisá-lo.

Infelizmente, se você esquecer de adicionar algum desses comentários, a biblioteca dividirá a instrução CREATE FUNCTION em várias partes e a migração falhará.

Evitar o caractere de dois-pontos (:)

-- FAÇA
CREATE TABLE bookings (
  booking_id UUID PRIMARY KEY,
  booked_at  TIMESTAMPTZ NOT NULL CHECK (CAST(booked_at AS DATE) <= check_in),
  check_in   DATE NOT NULL
);

-- NÃO FAÇA
CREATE TABLE bookings (
  booking_id UUID PRIMARY KEY,
  booked_at  TIMESTAMPTZ NOT NULL CHECK (booked_at::DATE <= check_in),
  check_in   DATE NOT NULL
);

Como o PDO usa o caractere dois-pontos para prefixar parâmetros nomeados em instruções preparadas, seu uso causará problemas em outros contextos.

Por exemplo, as instruções PostgreSQL podem usar :: para converter valores entre tipos. Por outro lado, o PDO lerá isso como um parâmetro nomeado inválido em um contexto inválido e falhará ao tentar executá-lo.

A única maneira de corrigir essa inconsistência é evitar completamente os dois-pontos (neste caso, o PostgreSQL também tem uma sintaxe alternativa: CAST(value AS type)).

Use um editor SQL

Finalmente, escrever migrações SQL manuais pode ser cansativo, mas é significativamente mais fácil se você usar um editor capaz de entender a sintaxe SQL, fornecendo autocompletar, introspectando seu esquema de banco de dados atual e/ou autoformatando seu código.

Lidar com diferentes migrações dentro de um esquema

Se você precisar criar diferentes scripts de migração e versões dentro do mesmo esquema, é possível mas é muito arriscado e eu não recomendo de forma alguma.

Para fazer isso, você precisa criar diferentes "tabelas de migração" passando o parâmetro para o construtor.

<?php
$migration = new \ByJG\DbMigration\Migration("db:/uri", "/path", true, "NEW_MIGRATION_TABLE_NAME");

Por razões de segurança, esse recurso não está disponível na linha de comando, mas você pode usar a variável de ambiente MIGRATION_VERSION para armazenar o nome.

Recomendamos fortemente não usar esse recurso. A recomendação é uma migração para um esquema.

Executando Testes Unitários

Testes unitários básicos podem ser executados com:

vendor/bin/phpunit

Executando testes de banco de dados

Executar testes de integração requer que você tenha os bancos de dados em funcionamento. Fornecemos um básico docker-compose.yml e você pode usá-lo para iniciar os bancos de dados para testes.

Executando os bancos de dados

docker-compose up -d postgres mysql mssql

Executar os testes

vendor/bin/phpunit
vendor/bin/phpunit tests/SqliteDatabase*
vendor/bin/phpunit tests/MysqlDatabase*
vendor/bin/phpunit tests/PostgresDatabase*
vendor/bin/phpunit tests/SqlServerDblibDatabase*
vendor/bin/phpunit tests/SqlServerSqlsrvDatabase*

Opcionalmente, você pode definir o host e a senha usados pelos testes unitários

export MYSQL_TEST_HOST=localhost     # padrão é localhost
export MYSQL_PASSWORD=newpassword    # use '.' se quiser ter uma senha nula
export PSQL_TEST_HOST=localhost      # padrão é localhost
export PSQL_PASSWORD=newpassword     # use '.' se quiser ter uma senha nula
export MSSQL_TEST_HOST=localhost     # padrão é localhost
export MSSQL_PASSWORD=Pa55word
export SQLITE_TEST_HOST=/tmp/test.db      # padrão é /tmp/test.db

Awesome-plugins/session

FlightPHP Session - Manipulador de Sessão Leve Baseado em Arquivos

Isto é um plugin leve e baseado em arquivos para manipular sessões no Flight PHP Framework. Ele oferece uma solução simples e poderosa para gerenciar sessões, com recursos como leituras de sessão não bloqueantes, criptografia opcional, funcionalidade de auto-commit e um modo de teste para desenvolvimento. Os dados da sessão são armazenados em arquivos, tornando-o ideal para aplicações que não requerem um banco de dados.

Se você quiser usar um banco de dados, verifique o plugin ghostff/session que possui muitos desses mesmos recursos, mas com backend de banco de dados.

Visite o repositório no Github para o código-fonte completo e detalhes.

Instalação

Instale o plugin via Composer:

composer require flightphp/session

Uso Básico

Aqui está um exemplo simples de como usar o plugin flightphp/session na sua aplicação Flight:

require 'vendor/autoload.php';

use flight\Session;

$app = Flight::app();

// Registra o serviço de sessão
$app->register('session', Session::class);

// Exemplo de rota com uso de sessão
Flight::route('/login', function() {
    $session = Flight::session();
    $session->set('user_id', 123);
    $session->set('username', 'johndoe');
    $session->set('is_admin', false);

    echo $session->get('username'); // Saída: johndoe
    echo $session->get('preferences', 'default_theme'); // Saída: default_theme

    if ($session->get('user_id')) {
        Flight::json(['message' => 'Usuário está logado!', 'user_id' => $session->get('user_id')]);
    }
});

Flight::route('/logout', function() {
    $session = Flight::session();
    $session->clear(); // Limpa todos os dados da sessão
    Flight::json(['message' => 'Deslogado com sucesso']);
});

Flight::start();

Pontos Chave

Configuração

Você pode personalizar o manipulador de sessão passando um array de opções ao registrar:

// Sim, é um array duplo :)
$app->register('session', Session::class, [ [
    'save_path' => '/custom/path/to/sessions',         // Diretório para os arquivos de sessão
    'prefix' => 'myapp_',                              // Prefixo para os arquivos de sessão
    'encryption_key' => 'a-secure-32-byte-key-here',   // Ativa criptografia (32 bytes recomendados para AES-256-CBC)
    'auto_commit' => false,                            // Desativa auto-commit para controle manual
    'start_session' => true,                           // Inicia a sessão automaticamente (padrão: true)
    'test_mode' => false,                              // Ativa modo de teste para desenvolvimento
    'serialization' => 'json',                         // Método de serialização: 'json' (padrão) ou 'php' (legado)
] ]);

Opções de Configuração

Option Description Default Value
save_path Diretório onde os arquivos de sessão são armazenados sys_get_temp_dir() . '/flight_sessions'
prefix Prefixo para o arquivo de sessão salvo sess_
encryption_key Chave para criptografia AES-256-CBC (opcional) null (sem criptografia)
auto_commit Auto-salvar dados da sessão no desligamento true
start_session Iniciar a sessão automaticamente true
test_mode Executar no modo de teste sem afetar sessões PHP false
test_session_id ID de sessão personalizado para modo de teste (opcional) Gerado aleatoriamente se não definido
serialization Método de serialização: 'json' (padrão, seguro) ou 'php' (legado, permite objetos) 'json'

Modos de Serialização

Por padrão, esta biblioteca usa serialização JSON para os dados da sessão, o que é seguro e previne vulnerabilidades de injeção de objetos PHP. Se você precisar armazenar objetos PHP na sessão (não recomendado para a maioria dos apps), você pode optar pela serialização PHP legada:

Nota: Se você usar serialização JSON, tentar armazenar um objeto lançará uma exceção.

Uso Avançado

Commit Manual

Se você desativar o auto-commit, você deve commitar as alterações manualmente:

$app->register('session', Session::class, ['auto_commit' => false]);

Flight::route('/update', function() {
    $session = Flight::session();
    $session->set('key', 'value');
    $session->commit(); // Salva explicitamente as alterações
});

Segurança de Sessão com Criptografia

Ative a criptografia para dados sensíveis:

$app->register('session', Session::class, [
    'encryption_key' => 'your-32-byte-secret-key-here'
]);

Flight::route('/secure', function() {
    $session = Flight::session();
    $session->set('credit_card', '4111-1111-1111-1111'); // Criptografado automaticamente
    echo $session->get('credit_card'); // Descriptografado na recuperação
});

Regeneração de Sessão

Regenere o ID da sessão por segurança (ex.: após o login):

Flight::route('/post-login', function() {
    $session = Flight::session();
    $session->regenerate(); // Novo ID, mantém os dados
    // OU
    $session->regenerate(true); // Novo ID, deleta os dados antigos
});

Exemplo de Middleware

Proteja rotas com autenticação baseada em sessão:

Flight::route('/admin', function() {
    Flight::json(['message' => 'Bem-vindo ao painel de administração']);
})->addMiddleware(function() {
    $session = Flight::session();
    if (!$session->get('is_admin')) {
        Flight::halt(403, 'Acesso negado');
    }
});

Isto é apenas um exemplo simples de como usar isso em middleware. Para um exemplo mais detalhado, veja a documentação de middleware.

Métodos

A classe Session fornece esses métodos:

Todos os métodos, exceto get() e id(), retornam a instância Session para encadeamento.

Por Que Usar Este Plugin?

Detalhes Técnicos

Contribuindo

Contribuições são bem-vindas! Faça fork no repositório, faça suas alterações e envie um pull request. Relate bugs ou sugira recursos via o rastreador de issues do Github.

Licença

Este plugin é licenciado sob a Licença MIT. Veja o repositório no Github para detalhes.

Awesome-plugins/runway

Pista

A Pista é uma aplicação CLI que ajuda a gerenciar suas aplicações Flight. Ela pode gerar controladores, exibir todas as rotas e mais. É baseada na excelente biblioteca adhocore/php-cli.

Clique aqui para visualizar o código.

Instalação

Instale com o composer.

composer require flightphp/runway

Configuração Básica

Na primeira execução da Pista, ela guiará você por um processo de configuração e criará um arquivo de configuração .runway.json na raiz do seu projeto. Este arquivo conterá algumas configurações necessárias para que a Pista funcione corretamente.

Utilização

A Pista possui vários comandos que você pode usar para gerenciar sua aplicação Flight. Existem duas maneiras fáceis de usar a Pista.

  1. Se estiver usando o projeto esqueleto, você pode executar php runway [comando] a partir da raiz do seu projeto.
  2. Se estiver usando a Pista como um pacote instalado via composer, você pode executar vendor/bin/runway [comando] a partir da raiz do seu projeto.

Para qualquer comando, você pode inserir a flag --help para obter mais informações sobre como utilizar o comando.

php runway routes --help

Aqui estão alguns exemplos:

Gerar um Controlador

Com base na configuração em seu arquivo .runway.json, a localização padrão gerará um controlador para você no diretório app/controllers/.

php runway make:controller MeuControlador

Gerar um Modelo Active Record

Com base na configuração em seu arquivo .runway.json, a localização padrão gerará um controlador para você no diretório app/records/.

php runway make:record usuários

Se por acaso você tiver a tabela usuários com o seguinte esquema: id, nome, email, criado_em, atualizado_em, um arquivo semelhante ao seguinte será criado no arquivo app/records/RegistroUsuario.php:

<?php

declare(strict_types=1);

namespace app\records;

/**
 * Classe Active Record para a tabela de usuários.
 * @link https://docs.flightphp.com/awesome-plugins/active-record
 * 
 * @property int $id
 * @property string $nome
 * @property string $email
 * @property string $criado_em
 * @property string $atualizado_em
 * // você também pode adicionar relacionamentos aqui uma vez que os definir no array $relações
 * @property RegistroEmpresa $empresa Exemplo de um relacionamento
 */
class RegistroUsuario extends \flight\ActiveRecord
{
    /**
     * @var array $relações Define os relacionamentos para o modelo
     *   https://docs.flightphp.com/awesome-plugins/active-record#relationships
     */
    protected array $relações = [];

    /**
     * Construtor
     * @param mixed $conexãoBancoDados A conexão com o banco de dados
     */
    public function __construct($conexãoBancoDados)
    {
        parent::__construct($conexãoBancoDados, 'usuários');
    }
}

Exibir Todas as Rotas

Isso exibirá todas as rotas atualmente registradas com o Flight.

php runway routes

Se desejar visualizar apenas rotas específicas, você pode inserir uma flag para filtrar as rotas.

# Exibir apenas rotas GET
php runway routes --get

# Exibir apenas rotas POST
php runway routes --post

# etc.

Personalizando a Pista

Se você está criando um pacote para o Flight ou deseja adicionar seus próprios comandos personalizados ao seu projeto, pode fazer isso criando um diretório src/commands/, flight/commands/, app/commands/ ou commands/ para o seu projeto/pacote.

Para criar um comando, você simplesmente estende a classe AbstractBaseCommand e implementa, no mínimo, um método __construct e um método execute.

<?php

declare(strict_types=1);

namespace flight\commands;

class ComandoExemplo extends AbstractBaseCommand
{
    /**
     * Construtor
     *
     * @param array<string,mixed> $config Configuração JSON de .runway-config.json
     */
    public function __construct(array $config)
    {
        parent::__construct('make:example', 'Criar um exemplo para a documentação', $config);
        $this->argument('<gif-engracado>', 'O nome do gif engraçado');
    }

    /**
     * Executa a função
     *
     * @return void
     */
    public function execute(string $controlador)
    {
        $io = $this->app()->io();

        $io->info('Criando exemplo...');

        // Faça algo aqui

        $io->ok('Exemplo criado!');
    }
}

Consulte a Documentação do adhocore/php-cli para mais informações sobre como criar seus próprios comandos personalizados em sua aplicação Flight!

Awesome-plugins/tracy_extensions

Extensões do Painel Tracy Flight

=====

Este é um conjunto de extensões para tornar o trabalho com o Flight um pouco mais rico.

Este é o Painel

Flight Bar

E cada painel exibe informações muito úteis sobre sua aplicação!

Flight Data Flight Database Flight Request

Clique aqui para ver o código.

Instalação

Execute composer require flightphp/tracy-extensions --dev e você está pronto para começar!

Configuração

Há pouca configuração que você precisa fazer para começar. Você precisará iniciar o depurador Tracy antes de usar isso https://tracy.nette.org/en/guide:

<?php

use Tracy\Debugger;
use flight\debug\tracy\TracyExtensionLoader;

// bootstrap code
require __DIR__ . '/vendor/autoload.php';

Debugger::enable();
// Você pode precisar especificar seu ambiente com Debugger::enable(Debugger::DEVELOPMENT)

// se você usar conexões com banco de dados em sua aplicação, há um
// wrapper PDO obrigatório para usar APENAS EM DESENVOLVIMENTO (não em produção, por favor!)
// Ele tem os mesmos parâmetros que uma conexão PDO regular
$pdo = new PdoQueryCapture('sqlite:test.db', 'user', 'pass');
// ou se você anexar isso ao framework Flight
Flight::register('db', PdoQueryCapture::class, ['sqlite:test.db', 'user', 'pass']);
// agora, sempre que você fizer uma consulta, ela capturará o tempo, a consulta e os parâmetros

// Isso conecta os pontos
if(Debugger::$showBar === true) {
    // Isso precisa ser falso ou o Tracy não consegue renderizar :(
    Flight::set('flight.content_length', false);
    new TracyExtensionLoader(Flight::app());
}

// more code

Flight::start();

Configuração Adicional

Dados de Sessão

Se você tiver um manipulador de sessão personalizado (como ghostff/session), você pode passar qualquer array de dados de sessão para o Tracy e ele os exibirá automaticamente para você. Você o passa com a chave session_data no segundo parâmetro do construtor do TracyExtensionLoader.


use Ghostff\Session\Session;
// ou use flight\Session;

require 'vendor/autoload.php';

$app = Flight::app();

$app->register('session', Session::class);

if(Debugger::$showBar === true) {
    // Isso precisa ser falso ou o Tracy não consegue renderizar :(
    Flight::set('flight.content_length', false);
    new TracyExtensionLoader(Flight::app(), [ 'session_data' => Flight::session()->getAll() ]);
}

// routes and other things...

Flight::start();

Latte

O PHP 8.1+ é necessário para esta seção.

Se você tiver o Latte instalado em seu projeto, o Tracy tem uma integração nativa com o Latte para analisar seus templates. Você simplesmente registra a extensão com sua instância do Latte.


require 'vendor/autoload.php';

$app = Flight::app();

$app->map('render', function($template, $data, $block = null) {
    $latte = new Latte\Engine;

    // other configurations...

    // only add the extension if Tracy Debug Bar is enabled
    if(Debugger::$showBar === true) {
        // this is where you add the Latte Panel to Tracy
        $latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);
    }

    $latte->render($template, $data, $block);
});

Awesome-plugins/apm

Documentação do APM do FlightPHP

Bem-vindo ao FlightPHP APM—o treinador pessoal de desempenho do seu app! Este guia é o seu mapa para configurar, usar e dominar o Application Performance Monitoring (APM) com FlightPHP. Seja caçando requisições lentas ou apenas querendo se aprofundar em gráficos de latência, nós cobrimos tudo. Vamos tornar seu app mais rápido, seus usuários mais felizes e suas sessões de depuração uma brisa!

Veja uma demo do dashboard para o site Flight Docs.

FlightPHP APM

Por Que o APM Importa

Imagine isso: seu app é um restaurante movimentado. Sem uma forma de rastrear quanto tempo as ordens demoram ou onde a cozinha está travando, você está adivinhando por que os clientes estão saindo irritados. O APM é o seu sous-chef—ele observa cada passo, desde requisições de entrada até consultas de banco de dados, e sinaliza qualquer coisa que esteja te atrasando. Páginas lentas perdem usuários (estudos dizem que 53% abandonam se um site demora mais de 3 segundos para carregar!), e o APM te ajuda a capturar esses problemas antes que eles doam. É uma paz de espírito proativa—menos momentos de “por que isso está quebrado?”, mais vitórias de “olha como isso roda suave!”.

Instalação

Comece com o Composer:

composer require flightphp/apm

Você precisará de:

Bancos de Dados Suportados

O FlightPHP APM atualmente suporta os seguintes bancos de dados para armazenar métricas:

Você pode escolher o tipo de banco de dados durante o passo de configuração (veja abaixo). Certifique-se de que seu ambiente PHP tenha as extensões necessárias instaladas (ex.: pdo_sqlite ou pdo_mysql).

Começando

Aqui está o seu passo a passo para o APM incrível:

1. Registrar o APM

Adicione isso no seu index.php ou arquivo services.php para começar o rastreamento:

use flight\apm\logger\LoggerFactory;
use flight\Apm;

$ApmLogger = LoggerFactory::create(__DIR__ . '/../../.runway-config.json');
$Apm = new Apm($ApmLogger);
$Apm->bindEventsToFlightInstance($app);

// Se você estiver adicionando uma conexão de banco de dados
// Deve ser PdoWrapper ou PdoQueryCapture das Extensões Tracy
$pdo = new PdoWrapper('mysql:host=localhost;dbname=example', 'user', 'pass', null, true); // <-- True necessário para habilitar rastreamento no APM.
$Apm->addPdoConnection($pdo);

O que está acontecendo aqui?

Dica Pro: Amostragem Se o seu app estiver ocupado, registrar todas as requisições pode sobrecarregar as coisas. Use uma taxa de amostragem (0.0 a 1.0):

$Apm = new Apm($ApmLogger, 0.1); // Registra 10% das requisições

Isso mantém o desempenho ágil enquanto ainda te dá dados sólidos.

2. Configure-o

Execute isso para criar seu .runway-config.json:

php vendor/bin/runway apm:init

O que isso faz?

Esse processo também perguntará se você quer executar as migrações para essa configuração. Se você estiver configurando pela primeira vez, a resposta é sim.

Por que dois locais? Métricas brutas se acumulam rápido (pense em logs não filtrados). O worker as processa em um destino estruturado para o dashboard. Mantém tudo organizado!

3. Processar Métricas com o Worker

O worker transforma métricas brutas em dados prontos para o dashboard. Execute uma vez:

php vendor/bin/runway apm:worker

O que ele está fazendo?

Mantenha-o Rodando Para apps ao vivo, você quer processamento contínuo. Aqui estão suas opções:

Por que se preocupar? Sem o worker, seu dashboard está vazio. É a ponte entre logs brutos e insights acionáveis.

4. Inicie o Dashboard

Veja os vitais do seu app:

php vendor/bin/runway apm:dashboard

O que é isso?

Personalize-o:

php vendor/bin/runway apm:dashboard --host 0.0.0.0 --port 8080 --php-path=/usr/local/bin/php

Acesse a URL no seu navegador e explore!

Modo Produção

Para produção, você pode precisar tentar algumas técnicas para fazer o dashboard rodar, já que provavelmente há firewalls e outras medidas de segurança no lugar. Aqui estão algumas opções:

Quer um dashboard diferente?

Você pode construir o seu próprio dashboard se quiser! Olhe no diretório vendor/flightphp/apm/src/apm/presenter para ideias de como apresentar os dados para o seu próprio dashboard!

Recursos do Dashboard

O dashboard é o seu QG do APM—aqui está o que você verá:

Extras:

Exemplo: Uma requisição para /users pode mostrar:

Adicionando Eventos Personalizados

Rastreie qualquer coisa—como uma chamada de API ou processo de pagamento:

use flight\apm\CustomEvent;

$app->eventDispatcher()->trigger('apm.custom', new CustomEvent('api_call', [
    'endpoint' => 'https://api.example.com/users',
    'response_time' => 0.25,
    'status' => 200
]));

Onde aparece? Nos detalhes da requisição do dashboard sob “Eventos Personalizados”—expandível com formatação JSON bonita.

Caso de Uso:

$start = microtime(true);
$apiResponse = file_get_contents('https://api.example.com/data');
$app->eventDispatcher()->trigger('apm.custom', new CustomEvent('external_api', [
    'url' => 'https://api.example.com/data',
    'time' => microtime(true) - $start,
    'success' => $apiResponse !== false
]));

Agora você verá se essa API está arrastando seu app para baixo!

Monitoramento de Banco de Dados

Rastreie consultas PDO assim:

use flight\database\PdoWrapper;

$pdo = new PdoWrapper('sqlite:/path/to/db.sqlite', null, null, null, true); // <-- True necessário para habilitar rastreamento no APM.
$Apm->addPdoConnection($pdo);

O Que Você Obtém:

Atenção:

Saída de Exemplo:

Opções do Worker

Ajuste o worker ao seu gosto:

Exemplo:

php vendor/bin/runway apm:worker --daemon --batch_size 100 --timeout 3600

Roda por uma hora, processando 100 métricas de uma vez.

ID de Requisição no App

Cada requisição tem um ID de requisição único para rastreamento. Você pode usar esse ID no seu app para correlacionar logs e métricas. Por exemplo, você pode adicionar o ID de requisição a uma página de erro:

Flight::map('error', function($message) {
    // Obtenha o ID de requisição do cabeçalho de resposta X-Flight-Request-Id
    $requestId = Flight::response()->getHeader('X-Flight-Request-Id');

    // Além disso, você poderia obtê-lo da variável Flight
    // Esse método não funcionará bem em swoole ou outras plataformas assíncronas.
    // $requestId = Flight::get('apm.request_id');

    echo "Erro: $message (ID de Requisição: $requestId)";
});

Atualizando

Se você estiver atualizando para uma versão mais nova do APM, há uma chance de que haja migrações de banco de dados que precisam ser executadas. Você pode fazer isso executando o comando a seguir:

php vendor/bin/runway apm:migrate

Isso executará quaisquer migrações necessárias para atualizar o esquema do banco de dados para a versão mais recente.

Nota: Se o seu banco de dados APM for grande em tamanho, essas migrações podem demorar um pouco para rodar. Você pode querer executar esse comando durante horários de baixa atividade.

Limpando Dados Antigos

Para manter seu banco de dados organizado, você pode limpar dados antigos. Isso é especialmente útil se você estiver rodando um app movimentado e quiser manter o tamanho do banco de dados gerenciável. Você pode fazer isso executando o comando a seguir:

php vendor/bin/runway apm:purge

Isso removerá todos os dados mais antigos que 30 dias do banco de dados. Você pode ajustar o número de dias passando um valor diferente para a opção --days:

php vendor/bin/runway apm:purge --days 7

Isso removerá todos os dados mais antigos que 7 dias do banco de dados.

Solução de Problemas

Travado? Tente estes:

Awesome-plugins/tracy

Tracy

Tracy é um incrível manipulador de erros que pode ser usado com Flight. Possui vários painéis que podem ajudá-lo a depurar sua aplicação. É também muito fácil de estender e adicionar seus próprios painéis. A equipe do Flight criou alguns painéis especificamente para projetos do Flight com o plugin flightphp/tracy-extensions.

Instalação

Instale com o compositor. E na verdade, você vai querer instalar isso sem a versão de desenvolvimento, já que o Tracy vem com um componente de tratamento de erros de produção.

composer require tracy/tracy

Configuração Básica

Existem algumas opções de configuração básicas para começar. Você pode ler mais sobre elas na Documentação do Tracy.


require 'vendor/autoload.php';

use Tracy\Debugger;

// Habilitar Tracy
Debugger::enable();
// Debugger::enable(Debugger::DEVELOPMENT) // às vezes você precisa ser explícito (também Debugger::PRODUCTION)
// Debugger::enable('23.75.345.200'); // você também pode fornecer um array de endereços IP

// Aqui é onde os erros e exceções serão registrados. Certifique-se de que este diretório exista e seja gravável.
Debugger::$logDirectory = __DIR__ . '/../log/';
Debugger::$strictMode = true; // exibir todos os erros
// Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos os erros exceto avisos obsoletos
if (Debugger::$showBar) {
    $app->set('flight.content_length', false); // se a barra do Debugger estiver visível, então o comprimento do conteúdo não pode ser definido pelo Flight

    // Isso é específico para a Extensão do Tracy para o Flight se você incluiu isso
    // caso contrário, comente isso.
    new TracyExtensionLoader($app);
}

Dicas Úteis

Ao depurar seu código, existem algumas funções muito úteis para exibir dados para você.

Awesome-plugins/active_record

Flight Active Record

Um registro ativo é o mapeamento de uma entidade de banco de dados para um objeto PHP. Falando de forma simples, se você tiver uma tabela de usuários em seu banco de dados, você pode "traduzir" uma linha dessa tabela para uma classe User e um objeto $user em seu código. Veja exemplo básico.

Clique aqui para o repositório no GitHub.

Exemplo Básico

Vamos assumir que você tem a seguinte tabela:

CREATE TABLE users (
    id INTEGER PRIMARY KEY, 
    name TEXT, 
    password TEXT 
);

Agora você pode configurar uma nova classe para representar essa tabela:

/**
 * Uma classe ActiveRecord é geralmente singular
 * 
 * É altamente recomendável adicionar as propriedades da tabela como comentários aqui
 * 
 * @property int    $id
 * @property string $name
 * @property string $password
 */ 
class User extends flight\ActiveRecord {
    public function __construct($database_connection)
    {
        // você pode configurá-la assim
        parent::__construct($database_connection, 'users');
        // ou assim
        parent::__construct($database_connection, null, [ 'table' => 'users']);
    }
}

Agora assista a mágica acontecer!

// para sqlite
$database_connection = new PDO('sqlite:test.db'); // isso é apenas um exemplo, você provavelmente usaria uma conexão de banco de dados real

// para mysql
$database_connection = new PDO('mysql:host=localhost;dbname=test_db&charset=utf8bm4', 'username', 'password');

// ou mysqli
$database_connection = new mysqli('localhost', 'username', 'password', 'test_db');
// ou mysqli com criação não baseada em objeto
$database_connection = mysqli_connect('localhost', 'username', 'password', 'test_db');

$user = new User($database_connection);
$user->name = 'Bobby Tables';
$user->password = password_hash('uma senha legal');
$user->insert();
// ou $user->save();

echo $user->id; // 1

$user->name = 'Joseph Mamma';
$user->password = password_hash('uma nova senha legal!!!');
$user->insert();
// não pode usar $user->save() aqui ou ele achará que é uma atualização!

echo $user->id; // 2

E foi assim tão fácil adicionar um novo usuário! Agora que há uma linha de usuário no banco de dados, como você a extrai?

$user->find(1); // encontra id = 1 no banco de dados e o retorna.
echo $user->name; // 'Bobby Tables'

E se você quiser encontrar todos os usuários?

$users = $user->findAll();

E quanto a uma certa condição?

$users = $user->like('name', '%mamma%')->findAll();

Veja quanto é divertido isso? Vamos instalá-lo e começar!

Instalação

Basta instalar com o Composer

composer require flightphp/active-record

Uso

Isso pode ser utilizado como uma biblioteca autônoma ou com o Framework PHP Flight. Totalmente a seu critério.

Autônomo

Basta garantir que você passe uma conexão PDO para o construtor.

$pdo_connection = new PDO('sqlite:test.db'); // isso é apenas um exemplo, você provavelmente usaria uma conexão de banco de dados real

$User = new User($pdo_connection);

Não quer sempre configurar sua conexão de banco de dados no construtor? Veja Gerenciamento de Conexão de Banco de Dados para outras ideias!

Registrar como um método no Flight

Se você estiver usando o Framework PHP Flight, pode registrar a classe ActiveRecord como um serviço, mas honestamente, você não precisa.

Flight::register('user', 'User', [ $pdo_connection ]);

// então você pode usá-la assim em um controlador, uma função, etc.

Flight::user()->find(1);

Métodos runway

runway é uma ferramenta CLI para o Flight que possui um comando personalizado para esta biblioteca.

# Uso
php runway make:record nome_da_tabela_do_banco_de_dados [nome_da_classe]

# Exemplo
php runway make:record users

Isso criará uma nova classe no diretório app/records/ como UserRecord.php com o seguinte conteúdo:

<?php

declare(strict_types=1);

namespace app\records;

/**
 * Classe ActiveRecord para a tabela users.
 * @link https://docs.flightphp.com/awesome-plugins/active-record
 *
 * @property int $id
 * @property string $username
 * @property string $email
 * @property string $password_hash
 * @property string $created_dt
 */
class UserRecord extends \flight\ActiveRecord
{
    /**
     * @var array $relations Defina os relacionamentos para o modelo
     *   https://docs.flightphp.com/awesome-plugins/active-record#relationships
     */
    protected array $relations = [
        // 'nome_da_relação' => [ self::HAS_MANY, 'ClasseRelacionada', 'chave_estrangeira' ],
    ];

    /**
     * Construtor
     * @param mixed $databaseConnection A conexão com o banco de dados
     */
    public function __construct($databaseConnection)
    {
        parent::__construct($databaseConnection, 'users');
    }
}

Funções CRUD

find($id = null) : boolean|ActiveRecord

Encontra um registro e atribui ao objeto atual. Se você passar um $id de algum tipo, ele realizará uma busca na chave primária com esse valor. Se nada for passado, ele apenas encontrará o primeiro registro na tabela.

Além disso, você pode passar outros métodos auxiliares para consultar sua tabela.

// encontrar um registro com algumas condições previamente
$user->notNull('password')->orderBy('id DESC')->find();

// encontrar um registro por um id específico
$id = 123;
$user->find($id);

findAll(): array<int,ActiveRecord>

Encontra todos os registros na tabela que você especificar.

$user->findAll();

isHydrated(): boolean (v0.4.0)

Retorna true se o registro atual tiver sido hidratado (buscado do banco de dados).

$user->find(1);
// se um registro for encontrado com dados...
$user->isHydrated(); // true

insert(): boolean|ActiveRecord

Insere o registro atual no banco de dados.

$user = new User($pdo_connection);
$user->name = 'demo';
$user->password = md5('demo');
$user->insert();
Chaves Primárias Baseadas em Texto

Se você tiver uma chave primária baseada em texto (como um UUID), pode definir o valor da chave primária antes de inserir de duas maneiras.

$user = new User($pdo_connection, [ 'primaryKey' => 'uuid' ]);
$user->uuid = 'algum-uuid';
$user->name = 'demo';
$user->password = md5('demo');
$user->insert(); // ou $user->save();

ou você pode fazer com que a chave primária seja gerada automaticamente para você por meio de eventos.

class User extends flight\ActiveRecord {
    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users', [ 'primaryKey' => 'uuid' ]);
        // você também pode definir a chave primária assim em vez do array acima.
        $this->primaryKey = 'uuid';
    }

    protected function beforeInsert(self $self) {
        $self->uuid = uniqid(); // ou como você precisar gerar seus ids únicos
    }
}

Se você não definir a chave primária antes de inserir, ela será definida como o rowid e o banco de dados a gerará para você, mas não persistirá porque esse campo pode não existir em sua tabela. Por isso, é recomendável usar o evento para gerenciar isso automaticamente.

update(): boolean|ActiveRecord

Atualiza o registro atual no banco de dados.

$user->greaterThan('id', 0)->orderBy('id desc')->find();
$user->email = 'test@example.com';
$user->update();

save(): boolean|ActiveRecord

Insere ou atualiza o registro atual no banco de dados. Se o registro tiver um id, ele atualizará; caso contrário, ele irá inserir.

$user = new User($pdo_connection);
$user->name = 'demo';
$user->password = md5('demo');
$user->save();

Nota: Se você tiver relacionamentos definidos na classe, ele salvará recursivamente essas relações também, se foram definidas, instanciadas e possuem dados sujos para atualizar. (v0.4.0 e superior)

delete(): boolean

Exclui o registro atual do banco de dados.

$user->gt('id', 0)->orderBy('id desc')->find();
$user->delete();

Você também pode excluir vários registros executando uma pesquisa previamente.

$user->like('name', 'Bob%')->delete();

dirty(array $dirty = []): ActiveRecord

Dados sujos referem-se aos dados que foram alterados em um registro.

$user->greaterThan('id', 0)->orderBy('id desc')->find();

// nada está "sujo" até esse ponto.

$user->email = 'test@example.com'; // agora o e-mail é considerado "sujo" pois foi alterado.
$user->update();
// agora não há dados sujos porque foram atualizados e persistidos no banco de dados.

$user->password = password_hash('nova_senha'); // agora isso é sujo
$user->dirty(); // passando nada limpará todas as entradas sujas.
$user->update(); // nada será atualizado porque nada foi capturado como sujo.

$user->dirty([ 'name' => 'algo', 'password' => password_hash('uma senha diferente') ]);
$user->update(); // tanto nome quanto senha são atualizados.

copyFrom(array $data): ActiveRecord (v0.4.0)

Este é um alias para o método dirty(). É um pouco mais claro o que você está fazendo.

$user->copyFrom([ 'name' => 'algo', 'password' => password_hash('uma senha diferente') ]);
$user->update(); // tanto nome quanto senha são atualizados.

isDirty(): boolean (v0.4.0)

Retorna true se o registro atual tiver sido alterado.

$user->greaterThan('id', 0)->orderBy('id desc')->find();
$user->email = 'test@email.com';
$user->isDirty(); // true

reset(bool $include_query_data = true): ActiveRecord

Redefine o registro atual para seu estado inicial. Isso é muito bom para usar em tipos de comportamento de loop. Se você passar true, isso também redefinirá os dados da consulta usados para encontrar o objeto atual (comportamento padrão).

$users = $user->greaterThan('id', 0)->orderBy('id desc')->find();
$user_company = new UserCompany($pdo_connection);

foreach($users as $user) {
    $user_company->reset(); // comece com uma folha limpa
    $user_company->user_id = $user->id;
    $user_company->company_id = $some_company_id;
    $user_company->insert();
}

getBuiltSql(): string (v0.4.1)

Depois de executar um método find(), findAll(), insert(), update(), ou save(), você pode obter o SQL que foi construído e usá-lo para fins de depuração.

Métodos de Consulta SQL

select(string $field1 [, string $field2 ... ])

Você pode selecionar apenas algumas das colunas em uma tabela, se desejar (é mais eficiente em tabelas realmente largas com muitas colunas)

$user->select('id', 'name')->find();

from(string $table)

Você pode tecnicamente escolher outra tabela também! Por que não?!

$user->select('id', 'name')->from('user')->find();

join(string $table_name, string $join_condition)

Você pode até juntar a outra tabela no banco de dados.

$user->join('contacts', 'contacts.user_id = users.id')->find();

where(string $where_conditions)

Você pode definir alguns argumentos where personalizados (não pode definir parâmetros nesta declaração where)

$user->where('id=1 AND name="demo"')->find();

Nota de Segurança - Você pode ser tentado a fazer algo como $user->where("id = '{$id}' AND name = '{$name}'")->find();. Por favor, NÃO FAÇA ISSO!!! Isso é suscetível a ataques que são conhecidos como injeções de SQL. Existem muitos artigos online, por favor, pesquise "sql injection attacks php" e você encontrará muitos artigos sobre esse assunto. A maneira adequada de lidar com isso com esta biblioteca é, em vez desse método where(), você faria algo mais parecido com $user->eq('id', $id)->eq('name', $name)->find(); Se você absolutamente precisa fazer isso, a biblioteca PDO possui $pdo->quote($var) para escapar para você. Somente após usar quote() você pode usá-lo em uma declaração where().

group(string $group_by_statement)/groupBy(string $group_by_statement)

Agrupe seus resultados por uma condição particular.

$user->select('COUNT(*) as count')->groupBy('name')->findAll();

order(string $order_by_statement)/orderBy(string $order_by_statement)

Classifique a consulta retornada de uma certa maneira.

$user->orderBy('name DESC')->find();

limit(string $limit)/limit(int $offset, int $limit)

Limite a quantidade de registros retornados. Se um segundo int for dado, será offset, limit como em SQL.

$user->orderby('name DESC')->limit(0, 10)->findAll();

Condições WHERE

equal(string $field, mixed $value) / eq(string $field, mixed $value)

Onde field = $value

$user->eq('id', 1)->find();

notEqual(string $field, mixed $value) / ne(string $field, mixed $value)

Onde field <> $value

$user->ne('id', 1)->find();

isNull(string $field)

Onde field IS NULL

$user->isNull('id')->find();

isNotNull(string $field) / notNull(string $field)

Onde field IS NOT NULL

$user->isNotNull('id')->find();

greaterThan(string $field, mixed $value) / gt(string $field, mixed $value)

Onde field > $value

$user->gt('id', 1)->find();

lessThan(string $field, mixed $value) / lt(string $field, mixed $value)

Onde field < $value

$user->lt('id', 1)->find();

greaterThanOrEqual(string $field, mixed $value) / ge(string $field, mixed $value) / gte(string $field, mixed $value)

Onde field >= $value

$user->ge('id', 1)->find();

lessThanOrEqual(string $field, mixed $value) / le(string $field, mixed $value) / lte(string $field, mixed $value)

Onde field <= $value

$user->le('id', 1)->find();

like(string $field, mixed $value) / notLike(string $field, mixed $value)

Onde field LIKE $value ou field NOT LIKE $value

$user->like('name', 'de')->find();

in(string $field, array $values) / notIn(string $field, array $values)

Onde field IN($value) ou field NOT IN($value)

$user->in('id', [1, 2])->find();

between(string $field, array $values)

Onde field BETWEEN $value AND $value1

$user->between('id', [1, 2])->find();

Condições OR

É possível envolver suas condições em uma declaração OR. Isso é feito com o método startWrap() e endWrap() ou preenchendo o 3º parâmetro da condição após o campo e o valor.

// Método 1
$user->eq('id', 1)->startWrap()->eq('name', 'demo')->or()->eq('name', 'test')->endWrap('OR')->find();
// Isso será avaliado para `id = 1 AND (name = 'demo' OR name = 'test')`

// Método 2
$user->eq('id', 1)->eq('name', 'demo', 'OR')->find();
// Isso será avaliado para `id = 1 OR name = 'demo'`

Relacionamentos

Você pode definir vários tipos de relacionamentos usando esta biblioteca. Você pode definir relacionamentos um->muitos e um->um entre tabelas. Isso requer uma configuração extra na classe previamente.

Definir o array $relations não é difícil, mas adivinhar a sintaxe correta pode ser confuso.

protected array $relations = [
    // você pode nomear a chave como quiser. O nome do ActiveRecord provavelmente é bom. Ex: user, contact, client
    'user' => [
        // obrigatório
        // self::HAS_MANY, self::HAS_ONE, self::BELONGS_TO
        self::HAS_ONE, // este é o tipo de relacionamento

        // obrigatório
        'Some_Class', // esta é a classe ActiveRecord "outra" que será referenciada

        // obrigatório
        // dependendo do tipo de relacionamento
        // self::HAS_ONE = a chave estrangeira que referencia a junção
        // self::HAS_MANY = a chave estrangeira que referencia a junção
        // self::BELONGS_TO = a chave local que referencia a junção
        'local_or_foreign_key',
        // apenas FYI, isso também se junta apenas à chave primária do modelo "outro"

        // opcional
        [ 'eq' => [ 'client_id', 5 ], 'select' => 'COUNT(*) as count', 'limit' 5 ], // condições adicionais que você deseja ao juntar a relação
        // $record->eq('client_id', 5)->select('COUNT(*) as count')->limit(5))

        // opcional
        'back_reference_name' // isso é se você quiser referenciar essa relação de volta para si mesma Ex: $user->contact->user;
    ];
]
class User extends ActiveRecord {
    protected array $relations = [
        'contacts' => [ self::HAS_MANY, Contact::class, 'user_id' ],
        'contact' => [ self::HAS_ONE, Contact::class, 'user_id' ],
    ];

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }
}

class Contact extends ActiveRecord {
    protected array $relations = [
        'user' => [ self::BELONGS_TO, User::class, 'user_id' ],
        'user_with_backref' => [ self::BELONGS_TO, User::class, 'user_id', [], 'contact' ],
    ];
    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'contacts');
    }
}

Agora temos as referências configuradas para que possamos usá-las muito facilmente!

$user = new User($pdo_connection);

// encontrar o usuário mais recente.
$user->notNull('id')->orderBy('id desc')->find();

// obter contatos usando a relação:
foreach($user->contacts as $contact) {
    echo $contact->id;
}

// ou podemos fazer o caminho inverso.
$contact = new Contact();

// encontrar um contato
$contact->find();

// obter usuário usando a relação:
echo $contact->user->name; // este é o nome do usuário

Bem legal, não é?

Definindo Dados Personalizados

Às vezes você pode precisar anexar algo único ao seu ActiveRecord, como um cálculo personalizado que pode ser mais fácil apenas anexar ao objeto que então seria passado para, digamos, um modelo.

setCustomData(string $field, mixed $value)

Você anexa os dados personalizados com o método setCustomData().

$user->setCustomData('page_view_count', $page_view_count);

E então, você simplesmente faz referência a ele como uma propriedade normal do objeto.

echo $user->page_view_count;

Eventos

Mais uma super incrível característica sobre esta biblioteca é sobre eventos. Eventos são acionados em determinados momentos com base em certos métodos que você chama. Eles são muito úteis para configurar dados automaticamente para você.

onConstruct(ActiveRecord $ActiveRecord, array &config)

Isso é realmente útil se você precisar definir uma conexão padrão ou algo assim.

// index.php ou bootstrap.php
Flight::register('db', 'PDO', [ 'sqlite:test.db' ]);

//
//
//

// User.php
class User extends flight\ActiveRecord {

    protected function onConstruct(self $self, array &$config) { // não se esqueça da referência &
        // você poderia fazer isso para definir automaticamente a conexão
        $config['connection'] = Flight::db();
        // ou isso
        $self->transformAndPersistConnection(Flight::db());

        // Você também pode definir o nome da tabela dessa maneira.
        $config['table'] = 'users';
    } 
}

beforeFind(ActiveRecord $ActiveRecord)

Isso provavelmente só é útil se você precisar de uma manipulação de consulta toda vez.

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function beforeFind(self $self) {
        // sempre execute id >= 0 se isso for do seu agrado
        $self->gte('id', 0); 
    } 
}

afterFind(ActiveRecord $ActiveRecord)

Esse é provavelmente mais útil se você sempre precisar executar alguma lógica toda vez que este registro for buscado. Você precisa descriptografar algo? Você precisa executar uma consulta de contagem personalizada a cada vez (não performático, mas tudo bem)?

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function afterFind(self $self) {
        // descriptografando algo
        $self->secret = yourDecryptFunction($self->secret, $some_key);

        // talvez armazenando algo personalizado como uma consulta???
        $self->setCustomData('view_count', $self->select('COUNT(*) count')->from('user_views')->eq('user_id', $self->id)['count']; 
    } 
}

beforeFindAll(ActiveRecord $ActiveRecord)

Isso é provavelmente só útil se você precisar de uma manipulação de consulta toda vez.

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function beforeFindAll(self $self) {
        // sempre execute id >= 0 se isso for do seu agrado
        $self->gte('id', 0); 
    } 
}

afterFindAll(array<int,ActiveRecord> $results)

Semelhante ao afterFind(), mas você pode fazê-lo com todos os registros!

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function afterFindAll(array $results) {

        foreach($results as $self) {
            // faça algo legal como no afterFind()
        }
    } 
}

beforeInsert(ActiveRecord $ActiveRecord)

Realmente útil se você precisar definir alguns valores padrão toda vez.

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function beforeInsert(self $self) {
        // defina alguns padrões sensatos
        if(!$self->created_date) {
            $self->created_date = gmdate('Y-m-d');
        }

        if(!$self->password) {
            $self->password = password_hash((string) microtime(true));
        }
    } 
}

afterInsert(ActiveRecord $ActiveRecord)

Talvez você tenha um caso de uso para mudar dados após serem inseridos?

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function afterInsert(self $self) {
        // você faz o que quiser
        Flight::cache()->set('most_recent_insert_id', $self->id);
        // ou qualquer outra coisa....
    } 
}

beforeUpdate(ActiveRecord $ActiveRecord)

Realmente útil se você precisar definir alguns valores padrão cada vez que uma atualização ocorrer.

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function beforeInsert(self $self) {
        // defina alguns padrões sensatos
        if(!$self->updated_date) {
            $self->updated_date = gmdate('Y-m-d');
        }
    } 
}

afterUpdate(ActiveRecord $ActiveRecord)

Talvez você tenha um caso de uso para mudar dados após serem atualizados?

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function afterInsert(self $self) {
        // você faz o que quiser
        Flight::cache()->set('most_recently_updated_user_id', $self->id);
        // ou qualquer outra coisa....
    } 
}

beforeSave(ActiveRecord $ActiveRecord)/afterSave(ActiveRecord $ActiveRecord)

Isso é útil se você quiser que eventos aconteçam tanto quando inserções quanto atualizações ocorrerem. Vou poupar você da longa explicação, mas tenho certeza de que você pode imaginar o que é.

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function beforeSave(self $self) {
        $self->last_updated = gmdate('Y-m-d H:i:s');
    } 
}

beforeDelete(ActiveRecord $ActiveRecord)/afterDelete(ActiveRecord $ActiveRecord)

Não tenho certeza do que você gostaria de fazer aqui, mas sem julgamentos! Vá em frente!

class User extends flight\ActiveRecord {

    public function __construct($database_connection)
    {
        parent::__construct($database_connection, 'users');
    }

    protected function beforeDelete(self $self) {
        echo 'Ele foi um soldado valente... :cry-face:';
    } 
}

Gerenciamento de Conexão de Banco de Dados

Quando você estiver usando esta biblioteca, pode definir a conexão com o banco de dados de algumas maneiras diferentes. Você pode definir a conexão no construtor, pode defini-la via uma variável de configuração $config['connection'] ou pode defini-la via setDatabaseConnection() (v0.4.1).

$pdo_connection = new PDO('sqlite:test.db'); // por exemplo
$user = new User($pdo_connection);
// ou
$user = new User(null, [ 'connection' => $pdo_connection ]);
// ou
$user = new User();
$user->setDatabaseConnection($pdo_connection);

Se você deseja evitar configurar sempre uma $database_connection toda vez que chamar um registro ativo, existem maneiras de contornar isso!

// index.php ou bootstrap.php
// Defina isso como uma classe registrada no Flight
Flight::register('db', 'PDO', [ 'sqlite:test.db' ]);

// User.php
class User extends flight\ActiveRecord {

    public function __construct(array $config = [])
    {
        $database_connection = $config['connection'] ?? Flight::db();
        parent::__construct($database_connection, 'users', $config);
    }
}

// E agora, nenhum argumento é necessário!
$user = new User();

Nota: Se você planeja fazer testes unitários, fazer assim pode adicionar alguns desafios aos testes unitários, mas, no geral, porque você pode injetar sua conexão com setDatabaseConnection() ou $config['connection'], não é tão complicado.

Se você precisar atualizar a conexão do banco de dados, por exemplo, se estiver executando um script CLI de longa duração e precisar atualizar a conexão de tempos em tempos, pode redefinir a conexão com $your_record->setDatabaseConnection($pdo_connection).

Contribuindo

Por favor, contribua. :D

Configuração

Quando você contribuir, certifique-se de executar composer test-coverage para manter 100% de cobertura de testes (isso não é verdadeiro teste unitário, mais como teste de integração).

Além disso, certifique-se de executar composer beautify e composer phpcs para corrigir quaisquer erros de linting.

Licença

MIT

Awesome-plugins/latte

Latte

Latte é um motor de templates completo que é muito fácil de usar e se sente mais próximo de uma sintaxe PHP do que Twig ou Smarty. Também é muito fácil de estender e adicionar seus próprios filtros e funções.

Instalação

Instale com o composer.

composer require latte/latte

Configuração Básica

Existem algumas opções de configuração básicas para começar. Você pode ler mais sobre elas na Documentação do Latte.


require 'vendor/autoload.php';

$app = Flight::app();

$app->map('render', function(string $template, array $data, ?string $block): void {
    $latte = new Latte\Engine;

    // Onde o latte armazena especificamente seu cache
    $latte->setTempDirectory(__DIR__ . '/../cache/');

    $finalPath = Flight::get('flight.views.path') . $template;

    $latte->render($finalPath, $data, $block);
});

Exemplo Simples de Layout

Aqui está um exemplo simples de um arquivo de layout. Este é o arquivo que será usado para envolver todas as suas outras views.

<!-- app/views/layout.latte -->
<!doctype html>
<html lang="en">
    <head>
        <title>{$title ? $title . ' - '}Meu App</title>
        <link rel="stylesheet" href="style.css">
    </head>
    <body>
        <header>
            <nav>
                <!-- seus elementos de navegação aqui -->
            </nav>
        </header>
        <div id="content">
            <!-- Esta é a mágica bem aqui -->
            {block content}{/block}
        </div>
        <div id="footer">
            &copy; Copyright
        </div>
    </body>
</html>

E agora temos o seu arquivo que vai ser renderizado dentro daquele bloco de conteúdo:

<!-- app/views/home.latte -->
<!-- Isso diz ao Latte que este arquivo está "dentro" do arquivo layout.latte -->
{extends layout.latte}

<!-- Este é o conteúdo que será renderizado dentro do layout no bloco de conteúdo -->
{block content}
    <h1>Página Inicial</h1>
    <p>Bem-vindo ao meu app!</p>
{/block}

Então, quando você for renderizar isso dentro da sua função ou controlador, você faria algo assim:

// rota simples
Flight::route('/', function () {
    Flight::render('home.latte', [
        'title' => 'Página Inicial'
    ]);
});

// ou se você estiver usando um controlador
Flight::route('/', [HomeController::class, 'index']);

// HomeController.php
class HomeController
{
    public function index()
    {
        Flight::render('home.latte', [
            'title' => 'Página Inicial'
        ]);
    }
}

Consulte a Documentação do Latte para mais informações sobre como usar o Latte em todo o seu potencial!

Depuração com Tracy

O PHP 8.1+ é necessário para esta seção.

Você também pode usar o Tracy para ajudar na depuração dos seus arquivos de template Latte diretamente da caixa! Se você já tiver o Tracy instalado, precisa adicionar a extensão Latte ao Tracy.

// services.php
use Tracy\Debugger;

$app->map('render', function(string $template, array $data, ?string $block): void {
    $latte = new Latte\Engine;

    // Onde o latte armazena especificamente seu cache
    $latte->setTempDirectory(__DIR__ . '/../cache/');

    $finalPath = Flight::get('flight.views.path') . $template;

    // Isso só adicionará a extensão se a Barra de Depuração do Tracy estiver ativada
    if (Debugger::$showBar === true) {
        // é aqui que você adiciona o Painel Latte ao Tracy
        $latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);
    }
    $latte->render($finalPath, $data, $block);
});

Awesome-plugins/awesome_plugins

Plugins Incríveis

Flight é incrivelmente extensível. Existem vários plugins que podem ser usados para adicionar funcionalidade à sua aplicação Flight. Alguns são oficialmente suportados pela Equipe Flight e outros são bibliotecas micro/lite para ajudá-lo a começar.

Documentação de API

A documentação de API é crucial para qualquer API. Ela ajuda os desenvolvedores a entenderem como interagir com sua API e o que esperar em retorno. Existem algumas ferramentas disponíveis para ajudá-lo a gerar documentação de API para seus Projetos Flight.

Monitoramento de Desempenho de Aplicação (APM)

O Monitoramento de Desempenho de Aplicação (APM) é crucial para qualquer aplicação. Ele ajuda você a entender como sua aplicação está se saindo e onde estão os gargalos. Existem vários ferramentas APM que podem ser usadas com Flight.

Async

Flight já é um framework rápido, mas adicionar um motor turbo nele torna tudo mais divertido (e desafiador)!

Autorização/Permissões

Autorização e Permissões são cruciais para qualquer aplicação que requer controles para quem pode acessar o quê.

Cache

Cache é uma ótima forma de acelerar sua aplicação. Existem várias bibliotecas de cache que podem ser usadas com Flight.

CLI

Aplicações CLI são uma ótima forma de interagir com sua aplicação. Você pode usá-las para gerar controladores, exibir todas as rotas e mais.

Cookies

Cookies são uma ótima forma de armazenar pequenos pedaços de dados no lado do cliente. Eles podem ser usados para armazenar preferências de usuário, configurações de aplicação e mais.

Depuração

Depuração é crucial quando você está desenvolvendo em seu ambiente local. Existem alguns plugins que podem elevar sua experiência de depuração.

Bancos de Dados

Bancos de dados são o núcleo da maioria das aplicações. É assim que você armazena e recupera dados. Algumas bibliotecas de banco de dados são simplesmente wrappers para escrever consultas e algumas são ORMs completos.

Criptografia

Criptografia é crucial para qualquer aplicação que armazena dados sensíveis. Criptografar e descriptografar os dados não é terrivelmente difícil, mas armazenar corretamente a chave de criptografia pode ser difícil. A coisa mais importante é nunca armazenar sua chave de criptografia em um diretório público ou commitá-la em seu repositório de código.

Fila de Tarefas

Filas de tarefas são realmente úteis para processar tarefas de forma assíncrona. Isso pode ser enviar e-mails, processar imagens ou qualquer coisa que não precise ser feita em tempo real.

Sessão

Sessões não são realmente úteis para APIs, mas para construir uma aplicação web, sessões podem ser cruciais para manter o estado e informações de login.

Templating

Templating é o núcleo de qualquer aplicação web com uma UI. Existem vários motores de templating que podem ser usados com Flight.

Integração com WordPress

Quer usar Flight em seu projeto WordPress? Há um plugin prático para isso!

Contribuição

Tem um plugin que gostaria de compartilhar? Envie um pull request para adicioná-lo à lista!

Media

Mídia

Tentamos rastrear o que pudemos dos vários tipos de mídia na internet sobre o Flight. Veja abaixo diferentes recursos que você pode usar para aprender mais sobre o Flight.

Artigos e Escritos

Vídeos e Tutoriais

Faltando Algo?

Estamos faltando algo que você escreveu ou gravou? Deixe-nos saber com uma issue ou pull request!

Examples

Precisa de um início rápido?

Você tem duas opções para começar com um novo projeto Flight:

Exemplos contribuídos pela comunidade:

Precisa de Alguma Inspiração?

Embora estes não sejam oficialmente patrocinados pela Equipe Flight, eles podem dar ideias sobre como estruturar seus próprios projetos construídos com Flight!

Quer Compartilhar Seu Próprio Exemplo?

Se você tiver um projeto que deseja compartilhar, por favor, envie um pull request para adicioná-lo a esta lista!

Install/install

Instruções de Instalação

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

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

Instalação Básica

Se você estiver usando Composer, você pode executar 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, carregamento automático, etc. Esse método garante que nenhuma outra dependência além do Flight seja instalada.

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

Instalação Recomendada

É altamente recomendado começar com o aplicativo flightphp/skeleton para qualquer novo projeto. A instalação é muito simples.

composer create-project flightphp/skeleton my-project/

Isso configurará a estrutura do seu projeto, configurará o carregamento automático com namespaces, configurará uma configuração e fornecerá outras ferramentas como Tracy, Extensões do Tracy e Runway

Configurar seu Servidor Web

Servidor de Desenvolvimento PHP Integrado

Essa é, de longe, a maneira mais simples de começar. Você pode usar o servidor integrado para executar sua aplicação e até usar SQLite para um banco de dados (desde que o sqlite3 esteja instalado no seu sistema) e não precisar de muito mais nada! Basta executar o seguinte comando uma vez que o PHP esteja instalado:

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

Em seguida, abra seu navegador e vá para http://localhost:8000.

Se você quiser tornar o diretório raiz do documento do seu projeto um diretório diferente (Ex: seu projeto é ~/myproject, mas seu diretório raiz do documento é ~/myproject/public/), você pode executar o seguinte comando uma vez que estiver no diretório ~/myproject:

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

Em seguida, abra seu navegador e vá para 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 isso 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;
  }
}

Criar seu arquivo index.php

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

<?php

// Se você estiver usando Composer, exija o autoloader.
require 'vendor/autoload.php';
// se você não estiver usando 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 skeleton, isso já está configurado e tratado no seu arquivo app/config/routes.php. Os serviços são configurados em app/config/services.php

Instalando PHP

Se você já tiver o php instalado no seu sistema, vá em frente e pule essas instruções e vá para a seção de download

macOS

Instalando PHP usando Homebrew

  1. 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)"

  2. 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

  3. 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 PHP manualmente

  1. Baixe o PHP:

    • Visite PHP for 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.

  2. Extraia o PHP:

    • Extraia o arquivo zip baixado para C:\php.

  3. Adicione o PHP ao PATH do sistema:

    • Vá para 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.

  4. Configure o PHP:

    • Copie php.ini-development para php.ini.
    • Edite php.ini para configurar o PHP conforme necessário (ex.: definindo extension_dir, habilitando extensões).

  5. Verifique a instalação do PHP:

    • Abra o Prompt de Comando e execute: 
      php -v

Instalando Múltiplas Versões do PHP

  1. Repita os passos acima para cada versão, colocando cada uma em um diretório separado (ex.: C:\php7, C:\php8).

  2. Alterne entre 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 PHP usando apt

  1. Atualize as listas de pacotes:

    • Abra o Terminal e execute: 
      sudo apt update

  2. 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

  3. Instale módulos adicionais (opcional):

    • Por exemplo, para instalar suporte ao MySQL: 
      sudo apt install php8.1-mysql

  4. Alterne entre versões do PHP:

    • Use update-alternatives: 
      sudo update-alternatives --set php /usr/bin/php8.1

  5. Verifique a versão instalada:

    • Execute: 
      php -v

Rocky Linux

Instalando PHP usando yum/dnf

  1. Habilite o repositório EPEL:

    • Abra o Terminal e execute: 
      sudo dnf install epel-release

  2. Instale o repositório Remi's:

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

  3. 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

  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

  5. Verifique a versão instalada:

    • Execute: 
      php -v

Notas Gerais

Guides

Guias

Flight PHP é projetado para ser simples, mas poderoso, e nossos guias ajudarão você a construir aplicações do mundo real passo a passo. Esses tutoriais práticos guiam você por projetos completos para demonstrar como Flight pode ser usado de forma eficaz.

Guias Oficiais

Construindo um Blog

Aprenda como criar uma aplicação de blog funcional com Flight PHP. Este guia o leva por:

Este tutorial é perfeito para iniciantes que querem ver como todas as peças se encaixam em uma aplicação real.

Testes Unitários e Princípios SOLID

Este guia cobre os fundamentos dos testes unitários em aplicações Flight PHP. Ele inclui:

Guias Não Oficiais

Embora esses guias não sejam mantidos oficialmente pela equipe do Flight, eles são recursos valiosos criados pela comunidade. Eles cobrem vários tópicos e casos de uso, fornecendo insights adicionais sobre o uso do Flight PHP.

Creating a RESTful API with Flight Framework

Este guia o leva pela criação de uma API RESTful usando o framework Flight PHP. Ele cobre os básicos de configurar uma API, definir rotas e retornar respostas em JSON.

Building a Simple Blog

Este guia o leva pela criação de um blog básico usando o framework Flight PHP. Na verdade, ele tem 2 partes: uma para cobrir os básicos e a outra para cobrir tópicos mais avançados e refinamentos para um blog pronto para produção.

Building a Pokémon API in PHP: A Beginner's Guide

Este guia divertido o leva pela criação de uma simples API de Pokémon usando Flight PHP. Ele cobre os básicos de configurar uma API, definir rotas e retornar respostas em JSON.

Contribuindo

Tem uma ideia para um guia? Encontrou um erro? Nós欢迎 contribuições! Nossos guias são mantidos no repositório de documentação do FlightPHP.

Se você construiu algo interessante com Flight e quer compartilhar como um guia, por favor, envie um pull request. Compartilhar seu conhecimento ajuda a comunidade do Flight a crescer.

Procurando por Documentação da API?

Se você está procurando informações específicas sobre os recursos e métodos principais do Flight, consulte a seção Aprenda de nossa documentação.