Criando e executando um projeto FuelPHP no ambiente de desenvolvimento ServBay

O que é FuelPHP?

O FuelPHP é um framework PHP flexível e modular, projetado para construir aplicações web modernas. Ele segue o padrão HMVC (Hierarchical Model-View-Controller — Modelo-Visão-Controlador Hierárquico), e oferece um conjunto completo de funcionalidades e ferramentas para ajudar desenvolvedores a criarem aplicações web de alta qualidade de forma rápida e eficiente. Graças à sua flexibilidade, alta performance e facilidade de extensão, o FuelPHP é a escolha preferida de muitos desenvolvedores PHP.

Principais características e vantagens do FuelPHP

Arquitetura HMVC: Suporta o padrão HMVC, o que favorece a organização, reutilização e desenvolvimento modular do código — especialmente adequado para projetos grandes ou complexos.
Alta performance: O FuelPHP é projetado com foco em otimização de desempenho, sendo conhecido por sua velocidade e uso eficiente dos recursos, capaz de lidar com altas demandas de requisições.
Fácil de estender: Fornece mecanismos robustos de extensão, permitindo que desenvolvedores integrem facilmente bibliotecas de terceiros ou funcionalidades personalizadas para necessidades específicas.
Segurança: Inclui diversas funcionalidades de segurança, como validação automática de dados, filtragem de saída (prevenção de XSS), proteção CSRF, prevenção contra SQL Injection, entre outros, ajudando a construir aplicações mais seguras.
Forte suporte comunitário: O FuelPHP possui uma comunidade ativa, proporcionando suporte rápido e uma variedade de recursos de terceiros.

Com essas características, o FuelPHP permite aos desenvolvedores construir aplicações web de alta performance, seguras e fáceis de manter, adequadas desde pequenos projetos até aplicações corporativas de grande escala.

Preparando o ambiente de desenvolvimento FuelPHP com ServBay

O ServBay é um ambiente de desenvolvimento web local projetado para desenvolvedores, pré-instalando PHP, Caddy/Nginx/Apache, MySQL/PostgreSQL/MongoDB, Redis e vários outros serviços e ferramentas essenciais. Com o ServBay, você pode facilmente preparar o ambiente necessário para projetos FuelPHP sem precisar instalar e configurar dependências manualmente.

Este guia mostra passo a passo como utilizar o ambiente PHP do ServBay, o servidor web (Caddy) e bancos de dados e serviços de cache para criar e rodar um projeto FuelPHP. Utilizaremos o recurso de Sites do ServBay para configurar o servidor web e tornar acessível e testável o projeto com facilidade.

Pré-requisitos

Antes de começar, assegure-se de:

Ter o ServBay instalado e em execução no macOS.
O ambiente PHP do ServBay esteja ativado (por padrão, já vem ativado).
Os serviços de banco de dados (por exemplo, MySQL) e cache (Redis, Memcached) que você planeja usar estejam em funcionamento no ServBay.
O ServBay já inclui o Composer, então não é preciso instalar separadamente.

Criando um projeto FuelPHP

Caminho recomendado para armazenamento do projeto

O ServBay recomenda que os projetos de sites sejam localizados em /Applications/ServBay/www, facilitando o gerenciamento e a configuração. Esse diretório será usado como exemplo aqui.

Navegue até o diretório raiz dos sites
Abra o Terminal e vá até o diretório recomendado:
bash
```
cd /Applications/ServBay/www
```
1
Crie o diretório do projeto
Crie um novo diretório para seu projeto FuelPHP e acesse-o:
bash
```
mkdir servbay-fuelphp-app
cd servbay-fuelphp-app
```
1
2
Crie o projeto FuelPHP usando o Composer
No diretório do projeto, use o Composer para baixar e inicializar o FuelPHP. O . indica que será criado no diretório atual:
bash
```
composer create-project fuel/fuel .
```
1
O Composer fará o download do FuelPHP e suas dependências no diretório servbay-fuelphp-app.

Configurando o servidor web (usando o recurso Sites do ServBay)

Para acessar seu projeto FuelPHP pelo navegador, utilize o recurso Sites do ServBay para configurar um host virtual.

Abra a interface principal do ServBay.
Clique no menu Sites na barra lateral.
Clique no botão Adicionar Site no canto superior direito.
Na janela de configuração que abrir, preencha os seguintes dados:
- Nome: Escolha um nome fácil de identificar, por exemplo, Meu Primeiro Site FuelPHP Dev.
- Domínio: Defina um domínio local, como servbay-fuelphp-test.local. O ServBay fará a resolução automática deste domínio para o ambiente local.
- Tipo de site: Selecione PHP.
- Versão do PHP: Escolha a versão de PHP desejada, como 8.3.
- Diretório raiz do site: O arquivo de entrada do FuelPHP é public/index.php, portanto, o diretório raiz deve ser definido como o subdiretório public do projeto: /Applications/ServBay/www/servbay-fuelphp-app/public.
Clique em Adicionar para salvar a configuração.

O ServBay irá atualizar automaticamente a configuração do Caddy e recarregar o serviço, tornando o novo domínio acessível.

Para detalhes do passo a passo de adição de sites, consulte Adicionando o primeiro site na documentação do ServBay.

Configurando conexões de serviços no projeto FuelPHP

Projetos FuelPHP geralmente precisam de configurações para banco de dados, cache e outros serviços.

Configuração do banco de dados

A configuração do banco de dados do FuelPHP está em fuel/app/config/development/db.php. Edite esse arquivo para inserir seu acesso ao banco. Supondo uso do MySQL padrão do ServBay:

php

<?php
/**
 * As configurações do banco de dados de desenvolvimento. São mescladas às configurações globais.
 */
return [
    'default' => [
        'connection' => [
            'dsn'      => 'mysql:host=localhost;dbname=fuel_dev', // Certifique-se de que o banco fuel_dev já existe
            'username' => 'root', // Usuário padrão do MySQL no ServBay
            'password' => 'root', // Senha padrão do MySQL no ServBay (recomendado apenas para desenvolvimento local!)
        ],
        'identifier' => '`', // MySQL exige crase como identificador
    ],
];

Atenção:

Crie o banco fuel_dev manualmente usando uma ferramenta do ServBay, como phpMyAdmin ou Adminer. O usuário padrão root com senha root é recomendado apenas para ambientes locais.
'identifier' => ''` é obrigatório no MySQL para garantir aspas corretas em nomes de tabelas e campos.

Configuração de cache (Memcached e Redis)

O FuelPHP suporta múltiplos drivers de cache. Configure o driver e a conexão em fuel/app/config/cache.php. Assegure-se de que os serviços Memcached e/ou Redis estão ativos no ServBay.

Configuração do Memcached (fuel/app/config/cache.php):

Se for usar Memcached como cache padrão:

php

<?php
return [
    'driver' => 'memcached', // Define memcached como driver padrão
    'memcached' => [
        'cache_id' => 'fuel', // ID do cache
        'servers' => [
             'default' => [
                'host'   => '127.0.0.1', // Endereço padrão do Memcached
                'port'   => 11211,      // Porta padrão do Memcached
                'weight' => 100,
            ],
        ],
        'compression' => false, // Ativa/desativa compressão
    ],
    // ... Outras configurações de cache
];

O PHP incluído pelo ServBay geralmente já traz instalado o driver Memcached.

Configuração do Redis (fuel/app/config/redis.php):

Se quiser usar o Redis, configure da seguinte forma (geralmente no arquivo dedicado redis.php):

php

<?php
return [
    'default' => [
        'hostname' => '127.0.0.1', // Endereço padrão do Redis
        'port'     => 6379,      // Porta padrão do Redis
        'database' => 0,         // Índice do banco Redis
    ],
    // Caso precise, pode configurar várias conexões Redis
];

O PHP fornecido pelo ServBay normalmente já possui extensão Redis instalada.

Exemplos de uso de banco de dados e cache

Para demonstrar a integração do FuelPHP com banco e cache, apresentamos alguns exemplos de código.

Preparando a tabela de banco (usando migrações do FuelPHP)

O FuelPHP oferece a ferramenta Oil para gerenciamento de migrações de banco de dados — controle de versão das estruturas de tabelas.

Gerar arquivo de migração
No diretório raiz do projeto (servbay-fuelphp-app), execute o comando Oil para criar um novo arquivo de migração para a tabela users:
bash
```
php oil generate migration create_users_table
```
1
Isso criará um novo arquivo em fuel/app/migrations, com timestamp no nome.

Edite o arquivo de migração

Abra o novo arquivo de migração (fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php), edite o método up() para definir a tabela, e down() para desfazer:

php

<?php
namespace Fuel\Migrations;

use Fuel\Core\DBUtil;

class Create_users_table
{
    public function up()
    {
        // Cria a tabela users
        DBUtil::create_table('users', [
            'id'          => ['type' => 'int', 'constraint' => 11, 'auto_increment' => true],
            'name'        => ['type' => 'varchar', 'constraint' => 100],
            'email'       => ['type' => 'varchar', 'constraint' => 100, 'unique' => true],
        ], ['id'], true, 'InnoDB', 'utf8mb4_unicode_ci'); // Define PK, ativa índice, engine e charset
    }

    public function down()
    {
        // Remove a tabela users (rollback)
        DBUtil::drop_table('users');
    }
}

Execute a migração
Na raiz do projeto, execute para criar a tabela:
bash
```
php oil refine migrate
```
1
Se tudo estiver correto, a tabela users será criada no banco fuel_dev.

Adicionando um controlador de exemplo

Edite o arquivo fuel/app/classes/controller/welcome.php para incluir métodos demonstrando operações de banco e cache:

php

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // Inclui facade DB
use Fuel\Core\Redis; // Inclui facade Redis

class Controller_Welcome extends Controller
{
    // Action padrão da home
    public function action_index()
    {
        return Response::forge('Hello ServBay!');
    }

    // Action de exemplo com Memcached
    public function action_memcached()
    {
        // Busca no cache
        $value = Cache::get('servbay_memcached_key');

        if ($value === false) {
            // Caso não haja no cache, define o valor
            $value = 'Hello Memcached from ServBay!';
            Cache::set('servbay_memcached_key', $value, 60); // Cache 60 segundos
            $value .= ' (from cache)';
        } else {
            $value .= ' (cached)';
        }

        return Response::forge($value);
    }

    // Action de exemplo com Redis
    public function action_redis()
    {
        // Obtém instância Redis (conexão padrão)
        $redis = \Redis_Db::instance(); // FuelPHP 1.x usa Redis_Db::instance()
        // Se houver múltiplas conexões: \Redis_Db::instance('connection_name')

        // Seta valor no Redis
        $redis->set('servbay_redis_key', 'Hello Redis from ServBay!');

        // Busca valor do Redis
        $value = $redis->get('servbay_redis_key');

        return Response::forge($value);
    }

    // Action para inserir no MySQL
    public function action_mysql_add()
    {
        try {
            // Insere registro na tabela users
            $result = DB::insert('users')->set([
                'name' => 'ServBay Demo User ' . time(), // Usa timestamp para ser único
                'email' => 'demo_user_' . time() . '@servbay.test',
            ])->execute(); // Retorna array com o ID inserido

            return Response::forge('User added with ID: ' . $result[0]);
        } catch (\Database_Exception $e) {
            // Trata exceções do banco, exemplo: email duplicado
            return Response::forge('Error adding user: ' . $e->getMessage(), 500);
        }
    }

    // Action para consultar usuários no MySQL
    public function action_mysql()
    {
        // Seleciona todos registros da tabela users
        $users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();

        // Retorna lista de usuários em JSON
        return Response::forge(json_encode($users, JSON_PRETTY_PRINT));
    }
}

Observações:

Aqui são importados DB e Redis (usando use Fuel\Core\DB;, use Fuel\Core\Redis;).
As chaves em Memcached e Redis usam prefixo servbay_ para evitar conflitos.
O exemplo de escrita no MySQL adiciona timestamp e um tratamento simples de erro.
No FuelPHP 1.x, Redis utiliza \Redis_Db::instance().

Configurando rotas

Para acessar esses métodos pelo navegador, adicione as rotas apropriadas em fuel/app/config/routes.php. Por padrão, o Controller_Welcome já possui rota para o index, mas precisamos adicionar para memcached, redis, mysql_add e mysql:

php

<?php
return array(
    '_root_'  => 'welcome/index',  // Rota padrão aponta para index do controlador welcome
    '_404_'   => 'welcome/404',    // Rota para página 404

    // Rotas para actions de exemplo
    'memcached'   => 'welcome/memcached',
    'redis'       => 'welcome/redis',
    'mysql_add'   => 'welcome/mysql_add',
    'mysql'       => 'welcome/mysql',

    // ... Outras rotas
);

Acessando e testando seu site

Agora, abra o navegador e acesse o domínio configurado no ServBay, por exemplo: https://servbay-fuelphp-test.local, para testar sua aplicação FuelPHP e as conexões com serviços.

Página padrão: https://servbay-fuelphp-test.local
- Saída esperada: Hello ServBay!
Teste com Memcached: https://servbay-fuelphp-test.local/memcached
- Primeira visita: Hello Memcached from ServBay! (from cache) (caso o serviço de cache esteja ativo)
- Visitas seguintes: Hello Memcached from ServBay! (cached) (com cache ativo e não expirado)
Teste com Redis: https://servbay-fuelphp-test.local/redis
- Saída esperada: Hello Redis from ServBay! (se Redis ativa)
Adicionar usuário ao MySQL: https://servbay-fuelphp-test.local/mysql_add
- Saída esperada: User added with ID: [ID inserido] (se MySQL/DB/tabela ok)
Consultar lista de usuários no MySQL: https://servbay-fuelphp-test.local/mysql
- Saída esperada: Um array JSON contendo registros da tabela users (caso existam dados)

Sobre HTTPS: O ServBay, por padrão, configura certificados SSL automáticos para sites locais (usando ServBay User CA ou Public CA). Caso o navegador acuse certificado não confiável, certifique-se de que o CA do ServBay está adicionado nas autoridades confiáveis do sistema.

Observações Importantes

Certifique-se de que, na interface do ServBay, os serviços PHP, Caddy (ou Nginx/Apache), MySQL (caso use banco), Redis, Memcached, etc, estão ativos.
Crie manualmente o banco fuel_dev via a ferramenta de gerenciamento do banco escolhida, ou defina outro banco já existente em db.php. A ferramenta de migração do FuelPHP (oil refine migrate) cria tabelas, mas não cria bancos automaticamente.
O arquivo de entrada pública do FuelPHP é public/index.php; por isso, a pasta raiz do site no ServBay deve sempre apontar para o subdiretório public do projeto.

Resumo

Com o ServBay, é muito fácil configurar um ambiente de desenvolvimento local completo para projetos FuelPHP no macOS. Este guia abordou a criação do projeto, configuração do recurso Sites no ServBay, conexões de banco e cache, e exemplos de código para testar os recursos. Serviços pré-integrados e uma configuração simplificada do ServBay aumentam consideravelmente sua produtividade.

Esperamos que esse guia ajude você a começar com sucesso sua jornada de desenvolvimento FuelPHP utilizando o ServBay!

Criando e executando um projeto FuelPHP no ambiente de desenvolvimento ServBay ​

O que é FuelPHP? ​

Principais características e vantagens do FuelPHP ​

Preparando o ambiente de desenvolvimento FuelPHP com ServBay ​

Pré-requisitos ​

Criando um projeto FuelPHP ​

Configurando o servidor web (usando o recurso Sites do ServBay) ​

Configurando conexões de serviços no projeto FuelPHP ​

Configuração do banco de dados ​

Configuração de cache (Memcached e Redis) ​

Exemplos de uso de banco de dados e cache ​

Preparando a tabela de banco (usando migrações do FuelPHP) ​

Adicionando um controlador de exemplo ​

Configurando rotas ​

Acessando e testando seu site ​

Observações Importantes ​

Resumo ​