Criando e Executando um Projeto Phalcon

O que é Phalcon?

Phalcon é um framework Web PHP open source de alta performance, implementado como uma extensão em C. Essa implementação única garante um consumo de recursos extremamente baixo e altíssima velocidade de execução, superando significativamente a maioria dos frameworks PHP tradicionais. O Phalcon segue o padrão de arquitetura MVC (Model-View-Controller) e oferece um conjunto completo de componentes sofisticados, incluindo ORM (Mapeamento Objeto-Relacional), motor de templates, roteamento, cache, gerenciador de eventos e muito mais. O objetivo é permitir que os desenvolvedores criem aplicações Web e APIs robustas e rápidas com produtividade máxima.

Principais Características e Vantagens do Phalcon

• Performance superior: Como é executado como uma extensão C, o Phalcon evita o overhead de parsing e carregamento de scripts PHP, atingindo performance perto do nível nativo.
• Eficiência de recursos: O consumo de memória é mínimo, tornando-o ideal para aplicações que exigem alta performance e escalabilidade.
• Funcionalidade abrangente: Inclui a maioria dos componentes essenciais para desenvolvimento Web, reduzindo a necessidade de bibliotecas de terceiros.
• Fácil de usar: API clara e consistente, além de documentação detalhada, permitindo fácil adoção mesmo para iniciantes.
• Alto desacoplamento: Os componentes podem ser usados de forma independente; você escolhe o que precisa para cada projeto.
• Segurança: Recursos internos para segurança, como filtragem de entrada, proteção CSRF e outros.

O Phalcon é especialmente recomendado para projetos que exigem máxima velocidade e eficiência de recursos, tornando-se uma escolha ideal para criar aplicações Web e APIs escaláveis e de alta performance.

Criando e Executando um Projeto Phalcon com ServBay

O ServBay é um ambiente de desenvolvimento Web local projetado para macOS, integrando várias versões do PHP, bancos de dados (MySQL, PostgreSQL, MongoDB, Redis) e servidores Web (Caddy, Nginx, Apache), além de diversas ferramentas para desenvolvedores. Com o ServBay, você cria e gerencia ambientes para projetos Phalcon facilmente.

Este guia mostra como criar um projeto básico Phalcon usando o PHP do ServBay, configurar o servidor Web, e demonstrar a integração com bancos de dados relacionais (MySQL) e NoSQL (Redis).

Pré-requisitos

Antes de começar, verifique se:

1. ServBay está instalado e em execução: Confirme que instalou e iniciou o ServBay no seu macOS.
2. A versão PHP desejada está habilitada: Certifique-se de marcar e ativar a versão do PHP que pretende usar no ServBay.
3. O módulo Phalcon está habilitado: O ServBay já inclui o módulo Phalcon, mas pode estar desativado por padrão. Ative a extensão Phalcon correspondente à sua versão PHP conforme as orientações do documento Como habilitar o módulo Phalcon do ServBay e reinicie o serviço PHP.
4. Composer disponível: O ServBay já inclui o Composer. Você pode rodar o comando composer diretamente no terminal.

Versões do Phalcon e DevTools

O framework Phalcon e o DevTools precisam ser compatíveis com a versão PHP utilizada. Veja abaixo a tabela de compatibilidade recomendada:

Versão PHP	Versão Phalcon recomendada	Versão DevTools recomendada	Observações
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1 (ou 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (oficial)	O DevTools oficial pode apresentar problemas de compatibilidade no PHP 8.x
PHP 8.3, 8.4	Phalcon 5.x	dev-master (repositório com correções)	Recomendado usar a versão corrigida pela comunidade para melhor compatibilidade

Atenção: Para PHP 8.x e superiores, o DevTools oficial pode não ser totalmente compatível. Prefira uma versão corrigida pela comunidade (apresentada a seguir).

Criando um Projeto Phalcon

Caminho sugerido para os sites

Para facilitar a organização, o ServBay sugere que todos os projetos Web fiquem na pasta padrão /Applications/ServBay/www. Usaremos essa pasta no exemplo.

1. Acesse a pasta raiz e crie o diretório do projeto

   No terminal, vá até a raiz de sites do ServBay e crie uma pasta para seu projeto Phalcon (por exemplo, servbay-phalcon-app):

   cd /Applications/ServBay/www
   mkdir servbay-phalcon-app
   cd servbay-phalcon-app

2. Instale o Phalcon DevTools

   O Phalcon DevTools é uma coleção de utilitários de linha de comando para gerar código, estruturar projetos e gerenciar migrações. A instalação é feita via Composer, variando conforme a versão PHP:

   • Para PHP 5.6, 7.0, 7.1 (DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • Para PHP 7.2, 7.3, 7.4 (DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • Para PHP 8.0, 8.1, 8.2, 8.3, 8.4 (DevTools dev-master com correções):

     Por possíveis problemas com o DevTools oficial em PHP 8.x, configure o Composer para usar o repositório corrigido. Crie ou edite o composer.json na pasta do projeto (/Applications/ServBay/www/servbay-phalcon-app):

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     Instale o DevTools rodando:

     composer update

   O Composer criará a pasta vendor e o DevTools ficará disponível em vendor/bin/phalcon.

3. Crie a estrutura do projeto usando DevTools

   Use o comando do DevTools para gerar a estrutura básica do projeto Phalcon. O código ficará em um subdiretório, por padrão com o mesmo nome do projeto:

   vendor/bin/phalcon project servbay-phalcon-app

   Este comando criará uma subpasta /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app com toda a estrutura do projeto Phalcon.

4. Acesse o diretório do código

   Entre na pasta de código criada. Os próximos passos são realizados nela:

   cd servbay-phalcon-app

   Agora você está em /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configuração do Projeto

A maior parte das configurações ficam em app/config/config.php. Defina nesse arquivo as informações do banco, caminhos das aplicações etc.

1. Edite o arquivo de configuração

   Abra /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php no seu editor preferido. Encontre ou adicione a seção de configuração do banco. O MySQL/MariaDB do ServBay usa root como usuário e senha em branco por padrão — para segurança, altere para uma senha forte. Use password apenas como exemplo e ajuste conforme sua configuração. O nome do banco servbay_phalcon_app é para o exemplo (crie-o manualmente).

   return new \Phalcon\Config([
       // ... outr as configurações ...
       'database' => [
           'adapter' => 'Mysql', // Ou 'Postgres'
           'host' => '127.0.0.1',
           'username' => 'root', // Usuário padrão do ServBay
           'password' => 'password', // <-- Altere para sua senha real
           'dbname' => 'servbay_phalcon_app', // <-- Altere para o nome do seu banco
       ],
       // ... outras configurações ...
   ]);

   Importante: Garanta que o serviço de banco (MySQL ou MariaDB) está rodando no ServBay e que o usuário/senha e o banco existem. Use as ferramentas Adminer ou phpMyAdmin do ServBay para gerir bancos e usuários.

Configurando o Servidor Web (Função "Sites" do ServBay)

Para acessar seu projeto Phalcon pelo navegador, use a função Sites do ServBay para criar um host virtual apontando para o diretório acessível pelo Web.

1. Abra o aplicativo ServBay
2. Acesse as configurações de "Sites": Clique em "Sites" na tela principal.
3. Adicione um novo site:
   • Nome: Algo identificável, ex: Meu Primeiro Site Phalcon.
   • Domínio: Exemplo: servbay-phalcon-test.local (o ServBay resolve automaticamente domínios .local).
   • Tipo de site: Selecione PHP.
   • Versão PHP: A que você ativou o Phalcon.
   • Diretório raiz: Aponte para a pasta public do projeto: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Salve: O ServBay aplica as mudanças. Pode ser necessário reiniciar o servidor Web (Caddy ou Nginx).

Veja o passo a passo detalhado em Adicionando o primeiro site. O ServBay cuida automaticamente do DNS local e da configuração do servidor Web.

Adicionando Código de Exemplo

Vamos adicionar um código simples para verificar se tudo está funcionando.

1. Configuração de rotas

   Edite /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php para criar uma rota que atenda ao /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Rota padrão: '/' mapeia para IndexController@indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... outras rotas ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Crie o controlador

   Edite (ou crie) /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php:

   <?php
   namespace App\Controllers; // Certifique-se do namespace correto
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Atende a rota '/':
       public function indexAction()
       {
           // Retorna uma string simples como resposta
           return 'Hello ServBay!';
       }
   }

Acessando o Site

Com tudo salvo e o ServBay rodando, abra o navegador e acesse o domínio configurado:

https://servbay-phalcon-test.local

Se estiver tudo certo, verá Hello ServBay! na tela.

Integração com Banco de Dados

O Phalcon conta com uma poderosa camada de abstração de banco e ORM. O ServBay integra vários bancos, como veremos com MySQL e Redis.

Exemplo Relacional: MySQL

Veja como conectar ao MySQL do ServBay com o Phalcon e executar inserção e consulta.

1. Criando tabela via migração

   O Phalcon DevTools oferece suporte a migrações para controle de versão dos schemas do banco.

   • Gerar arquivo de migração: Na pasta do projeto, rode:

     vendor/bin/phalcon migration generate

     Será criado um arquivo novo em migrations com nome parecido com YYYYMMDDHHMMSS_MigrationName.php.

   • Edite a migração: No método morph, crie a tabela users:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Ajuste o nome de acordo com seu arquivo
     {
         /**
          * Run the migrations
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * Reverse the migrations
          *
          * @return void
          */
         public function down()
         {
             // Opcional: lógica de rollback, por exemplo deletar tabela
             // $this->getConnection()->dropTable('users');
         }
     }

     Atenção: Certifique-se de que o nome da classe (UsersMigration_100) corresponde ao do arquivo.

   • Rode a migração: Execute para criar a tabela no banco:

     vendor/bin/phalcon migration run

     Se ocorrer erro de conexão, confira as configurações do banco em config.php e se o serviço está ativo.

2. Configuração da conexão (já feita anteriormente)

   Confira que a configuração do bloco 'database' em app/config/config.php está correta.

3. Crie rotas de exemplo

   Em app/config/routes.php, adicione para inserir e consultar usuários:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Rota para inserir usuário
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Rota para consultar usuários
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implemente as ações no controlador

   No app/controllers/IndexController.php, adicione os métodos para inserir e listar usuários:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Importa adapter MySQL
   use Phalcon\Db\Enum; // Para fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Exemplo de inserção de usuário
       public function mysqlAddAction()
       {
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Altere conforme seu ambiente
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Insere um usuário de exemplo
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', '[email protected]'],
               ['name', 'email']
           );
   
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Exemplo de consulta de usuários
       public function mysqlAction()
       {
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Modifique para sua senha
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Nota: No desenvolvimento real, use a injeção de dependência para gerenciar a conexão, evitando criá-la manualmente a cada action.

5. Acessando o exemplo

   • Acesse https://servbay-phalcon-test.local/mysql-add – deve ver "User added successfully."
   • Vá em https://servbay-phalcon-test.local/mysql – deve receber os dados (em JSON) da tabela users.

Exemplo NoSQL: Redis

Exemplo de uso do Redis do ServBay como cache no Phalcon.

1. Habilite a extensão Redis

   O Redis já vem incluso no PHP do ServBay. Apenas ative a extensão Redis para a versão PHP do seu projeto.

2. Configuração da conexão Redis

   Adicione no app/config/config.php:

   return new \Phalcon\Config([
       // ... outras configurações ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Padrão é 0
           'persistent' => false,
           'auth' => null, // Adicione a senha se necessário
       ],
       // ... outras configurações ...
   ]);

3. Adicione rota de exemplo

   Abra app/config/routes.php e inclua:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // Rota para teste do cache Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implementação do uso do cache Redis

   No app/controllers/IndexController.php, adicione o método de exemplo para Redis:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Importa cache Redis
   use Phalcon\Storage\SerializerFactory; // Importa serializador
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Exemplo de cache Redis
       public function redisAction()
       {
           // Cria instância do serializador
           $serializerFactory = new SerializerFactory();
   
           // Configuração do Redis (igual ao config.php)
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'sua_senha_redis',
           ];
   
           // Instancia o cache Redis
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Data stored in cache.";
           } else {
               echo "Data found in cache: ";
           }
   
           return $cachedData;
       }
   }

   Nota: Em produção, o cache normalmente é definido como um serviço compartilhado.

5. Testando

   Abra o navegador em https://servbay-phalcon-test.local/redis.

   • Na primeira visita verá "Data not found in cache, fetching from source...Data stored in cache." seguido de "Data fetched from source: Hello Redis from ServBay!".
   • Nas próximas visitas durante o período de validade do cache, verá "Data found in cache: " e a mensagem de dados vinda diretamente do Redis.

Perguntas Frequentes (FAQ)

• Q: Estou recebendo erro 404 Not Found ao acessar o site. O que fazer?
  • A: Certifique-se de que o "diretório raiz" na configuração do site aponta para a pasta public do seu projeto (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Verifique se o servidor Web do ServBay está ativo e o domínio .local está resolvendo.
• Q: Erro "Phalcon module not found" ou "Class 'Phalcon\Mvc\Application' not found". Como resolver?
  • A: Isso significa que a extensão Phalcon não está habilitada na versão do PHP escolhida. Habilite pelo painel do ServBay e reinicie o serviço PHP. Veja o guia Como habilitar o módulo Phalcon do ServBay.
• Q: Falha na conexão do banco de dados. O que verificar?
  • A: Confira as configurações do banco (host, username, password, dbname). Confirme que o serviço MySQL/MariaDB do ServBay está em execução. Verifique se o usuário tem permissão e se o banco existe.

Resumo

Com o ServBay, você rapidamente monta um ambiente local de alta performance para desenvolvimento usando Phalcon. Este guia demonstrou desde a criação da estrutura do projeto e configuração do servidor Web até integração com MySQL e Redis. Os pacotes integrados e a interface amigável do ServBay facilitam a configuração e a administração do ambiente, permitindo que você se foque no desenvolvimento do seu aplicativo Phalcon. Esperamos que este tutorial ajude você a começar rapidamente e a desenvolver projetos Web eficientes com ServBay e Phalcon!