Criando e executando um projeto FuelPHP no ambiente local ServBay

O que é FuelPHP?

FuelPHP é um framework PHP flexível e modular, projetado para construir aplicações web modernas. Ele adota o padrão de arquitetura Model-View-Controller Hierárquico (HMVC), oferecendo diversas funcionalidades e ferramentas pensadas para ajudar desenvolvedores a criar aplicativos web de alta qualidade de forma rápida e eficiente. Por sua flexibilidade, desempenho superior e facilidade de expansão, FuelPHP é a escolha preferida de muitos desenvolvedores PHP.

Principais recursos e benefícios do FuelPHP

• Arquitetura HMVC: Suporta design em camadas segundo o padrão MVC hierárquico, facilitando a organização do código, reutilização e desenvolvimento modular—ideal para projetos grandes ou complexos.
• Alto desempenho: Projetado para otimizar recursos e velocidade, FuelPHP pode lidar eficientemente com um grande volume de requisições.
• Fácil de estender: O framework possui um sistema robusto de extensões, permitindo integrar facilmente bibliotecas de terceiros ou adicionar funcionalidades customizadas conforme necessidades específicas do projeto.
• Segurança: Inclui vários recursos embutidos contra vulnerabilidades, como validação automática de entrada, filtragem contra XSS, proteção contra CSRF e prevenção de injeção de SQL, auxiliando desenvolvedores a criar aplicativos mais seguros.
• Forte comunidade: FuelPHP conta com uma comunidade ativa de desenvolvedores, oferecendo suporte rápido e diversos recursos de terceiros.

Com todas essas funcionalidades, o FuelPHP ajuda você a construir aplicações web de alto desempenho, seguras e fáceis de manter, servindo desde pequenos projetos até aplicações corporativas de grande porte.

Montando o ambiente de desenvolvimento FuelPHP com ServBay

O ServBay é um ambiente de desenvolvimento web local pensado para desenvolvedores, já equipado com PHP, servidores web (Caddy/Nginx/Apache), bancos de dados (MySQL/PostgreSQL/MongoDB), Redis e outros serviços essenciais. Com ServBay você instala e executa todos os componentes necessários para o projeto FuelPHP sem precisar configurar dependências manualmente.

Neste guia você aprende passo a passo como utilizar o PHP, server web (Caddy) e serviços de banco e cache do ServBay para criar e rodar um projeto FuelPHP. Aproveitaremos o recurso de Sites do ServBay para configurar o servidor web e acessar/testar o projeto rapidamente.

Pré-requisitos

Antes de começar, certifique-se de:

• Você já instalou e está executando o ServBay no macOS.
• O ambiente PHP no ServBay está ativado (por padrão já vem ativo).
• O serviço de banco de dados que deseja usar (Ex.: MySQL) e de cache (Ex.: Redis, Memcached) estão ativos e funcionando normalmente.
• O ServBay já traz o Composer instalado, não sendo necessária instalação adicional.

Criando um projeto FuelPHP

Caminho sugerido para projetos

O ServBay recomenda concentrar seus projetos de sites no diretório /Applications/ServBay/www para facilitar gerenciamento e configuração. Usaremos este diretório nos exemplos abaixo.

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

   Abra o Terminal e mude para a pasta recomendada pelo ServBay:

   cd /Applications/ServBay/www

2. Crie um diretório para o projeto

   Crie a pasta do seu projeto FuelPHP e acesse-a:

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

3. Crie o projeto FuelPHP usando Composer

   Dentro do diretório do projeto, utilize o Composer para baixar e inicializar o FuelPHP. O ponto . indica o diretório atual:

   composer create-project fuel/fuel .

   O Composer irá baixar o FuelPHP e todas as dependências para dentro de servbay-fuelphp-app.

Configurando o servidor web (usando Sites do ServBay)

Para acessar seu projeto FuelPHP pelo navegador, configure um host virtual usando o recurso de Sites do ServBay.

1. Abra a interface principal do ServBay.
2. Clique no menu Sites na barra lateral.
3. Clique em Adicionar Site no canto superior direito.
4. No painel de configuração, preencha:
   • Nome: Escolha um nome fácil de identificar, ex.: Meu Primeiro Site Dev FuelPHP.
   • Domínio: Defina um domínio local, ex.: servbay-fuelphp-test.local. O ServBay resolve esse domínio localmente automaticamente.
   • Tipo de site: Selecione PHP.
   • Versão do PHP: Escolha a versão desejada, por exemplo, 8.3.
   • Diretório raiz do site: Indique o subdiretório de entrada do FuelPHP. O arquivo principal está em public/index.php, então defina o diretório raiz como /Applications/ServBay/www/servbay-fuelphp-app/public.
5. Clique em Adicionar para salvar a configuração.

O ServBay atualiza a configuração do Caddy automaticamente e reinicia o serviço, tornando o novo domínio acessível.

Veja o passo a passo detalhado na documentação do ServBay para adicionar o primeiro site.

Configurando conexões de serviços no projeto FuelPHP

O FuelPHP geralmente demanda configuração manual das conexões para banco de dados e cache.

Configuração do banco de dados

No FuelPHP, a configuração fica em fuel/app/config/development/db.php. Edite este arquivo para inserir as informações do banco. Caso esteja usando o MySQL padrão do ServBay:

<?php
/**
 * Configuração de banco de dados para ambiente de desenvolvimento. Será mesclada com as configurações globais.
 */
return [
    'default' => [
        'connection' => [
            'dsn'      => 'mysql:host=localhost;dbname=fuel_dev', // Certifique-se de que o banco fuel_dev existe
            'username' => 'root', // Usuário padrão do MySQL no ServBay
            'password' => 'root', // Senha padrão do MySQL no ServBay (apenas para desenvolvimento local!)
        ],
        'identifier' => '`', // No MySQL use crases para identificadores
    ],
];

Atenção:

• Crie manualmente o banco de dados fuel_dev usando uma ferramenta como phpMyAdmin ou Adminer no ServBay. O usuário padrão do MySQL é root com senha root, configuração recomendada apenas para desenvolvimento local.
• 'identifier' => ''` é obrigatório para o MySQL, garantindo referências corretas para nomes de tabelas e campos.

Configuração de cache (Memcached e Redis)

O FuelPHP suporta múltiplos drivers de cache. Ajuste o arquivo fuel/app/config/cache.php para o driver e conexão desejados. Verifique se o Memcached e/ou Redis estão ativos no ServBay.

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

Se quiser usar Memcached como driver padrão:

<?php
return [
    'driver' => 'memcached', // Define Memcached como 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, // Compressão ativada ou não
    ],
    // ... outras configurações de cache
];

As versões do PHP fornecidas pelo ServBay geralmente já incluem a extensão do Memcached.

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

Para usar Redis, insira os dados da conexão em 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 de dados Redis
    ],
    // Você pode configurar várias conexões Redis
];

O Redis também já está disponível por padrão nas releases do PHP do ServBay.

Exemplos de uso: banco de dados e cache

Aqui estão exemplos práticos para demonstrar a interação do FuelPHP com banco de dados e serviços de cache.

Preparando tabela no banco de dados (usando Migrations do FuelPHP)

O FuelPHP conta com o Oil para gerenciar migrações, facilitando o controle de versões do banco.

1. Crie um arquivo de migração

   No diretório do projeto (servbay-fuelphp-app), gere uma migração para criar a tabela users:

   php oil generate migration create_users_table

   Um novo arquivo será criado em fuel/app/migrations, nomeado com data e hora.

2. Edite o arquivo de migração

   Abra o novo arquivo (fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php). Edite o método up() para definir a estrutura; use o down() para a reversão:

   <?php
   namespace Fuel\Migrations;
   
   use Fuel\Core\DBUtil;
   
   class Create_users_table
   {
       public function up()
       {
           // Cria 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 chave primária, índice, engine e charset
       }
   
       public function down()
       {
           // Remove tabela users (reversão)
           DBUtil::drop_table('users');
       }
   }

3. Execute a migração

   Na raíz do projeto (servbay-fuelphp-app), execute a migração para criar a tabela:

   php oil refine migrate

   Se tudo estiver ok, a tabela users será criada dentro de fuel_dev.

Adicionando código de exemplo ao controller

Edite o arquivo fuel/app/classes/controller/welcome.php para incluir métodos de exemplo para banco de dados e cache:

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // Importa facade DB
use Fuel\Core\Redis; // Importa 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()
    {
        // Tenta recuperar dados do cache
        $value = Cache::get('servbay_memcached_key');

        if ($value === false) {
            // Não está em cache, então grava
            $value = 'Hello Memcached from ServBay!';
            Cache::set('servbay_memcached_key', $value, 60); // Cache por 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 default do Redis
        $redis = \Redis_Db::instance(); // Para FuelPHP 1.x utilize Redis_Db::instance()
        // Para múltiplas conexões use: \Redis_Db::instance('nome_da_conexao')

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

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

        return Response::forge($value);
    }

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

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

    // Action de exemplo para ler do MySQL
    public function action_mysql()
    {
        // Consulta todos registros da tabela users
        $users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();

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

Observações:

• DB e Redis são usados através dos facades (use Fuel\Core\DB;, use Fuel\Core\Redis;).
• Chaves de cache usam prefixo servbay_ para evitar conflitos.
• A inserção no MySQL usa timestamp e tratamento simples de erros.
• No FuelPHP 1.x acesse Redis com \Redis_Db::instance().

Configurando rotas

Para acessar as novas actions pelo navegador, edite fuel/app/config/routes.php adicionando:

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

    // Rotas para os exemplos adicionados
    'memcached'   => 'welcome/memcached',
    'redis'       => 'welcome/redis',
    'mysql_add'   => 'welcome/mysql_add',
    'mysql'       => 'welcome/mysql',

    // ... outras rotas
);

Acessando e testando o site

Acesse o domínio configurado no ServBay, por exemplo https://servbay-fuelphp-test.local, e teste o projeto e as conexões:

• Página inicial: https://servbay-fuelphp-test.local
  • Saída esperada: Hello ServBay!
• Testando Memcached: https://servbay-fuelphp-test.local/memcached
  • Primeira visita: Hello Memcached from ServBay! (from cache) (se Memcached está ok)
  • Visitas seguintes: Hello Memcached from ServBay! (cached) (se cache ativo e não expirado)
• Testando Redis: https://servbay-fuelphp-test.local/redis
  • Saída esperada: Hello Redis from ServBay! (se Redis ok)
• Inserindo usuário no MySQL: https://servbay-fuelphp-test.local/mysql_add
  • Saída esperada: User added with ID: [ID gerado] (se MySQL e tabela ok)
• Listando usuários do MySQL: https://servbay-fuelphp-test.local/mysql
  • Saída esperada: array JSON com registros da tabela users (se houver dados)

Sobre HTTPS: O ServBay configura SSL automaticamente usando CA interna. Se o navegador alertar sobre certificado não confiável, adicione e confie na CA do ServBay no seu sistema.

Considerações finais

• Confirme que todas as versões e serviços necessários (PHP, Caddy/Nginx/Apache, MySQL, Redis, Memcached) estão rodando no ServBay.
• Crie manualmente o banco fuel_dev usando as ferramentas do ServBay; a migração só cria tabelas, não o banco.
• O arquivo principal do FuelPHP está em public/index.php, por isso o diretório raiz no ServBay deve ser apontado para o subdiretório public do projeto.

Resumo

Com o ServBay, montar um ambiente completo para projetos FuelPHP no macOS fica rápido e prático. Explicamos desde a criação do projeto, configuração dos Sites, integração com banco e cache, até exemplos práticos para testar serviços. Os diversos componentes já integrados e configurações simplificadas do ServBay aceleram o desenvolvimento e reduzem erros de configuração.

Esperamos que este guia ajude você a iniciar rapidamente sua jornada de desenvolvimento FuelPHP no ServBay!