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.

1. Navegue até o diretório raiz dos sites

   Abra o Terminal e vá até o diretório recomendado:

   cd /Applications/ServBay/www

2. Crie o diretório do projeto

   Crie um novo diretório para seu projeto FuelPHP e acesse-o:

   mkdir servbay-fuelphp-app
   cd servbay-fuelphp-app

3. 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:

   composer create-project fuel/fuel .

   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.

1. Abra a interface principal do ServBay.
2. Clique no menu Sites na barra lateral.
3. Clique no botão Adicionar Site no canto superior direito.
4. 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.
5. 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
/**
 * 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
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
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.

1. 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:

   php oil generate migration create_users_table

   Isso criará um novo arquivo em fuel/app/migrations, com timestamp no nome.

2. 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
   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');
       }
   }

3. Execute a migração

   Na raiz do projeto, execute para criar a tabela:

   php oil refine migrate

   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
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
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!