Criando e Executando Projetos Phalcon

O que é o Phalcon?

Phalcon é um framework web open source de alto desempenho para PHP, implementado como uma extensão em C. Por ser construído dessa maneira, Phalcon oferece consumo mínimo de recursos e velocidade de execução extraordinária, superando a maioria dos frameworks PHP convencionais. Utilizando a arquitetura MVC (Model-View-Controller), o Phalcon fornece um conjunto robusto de componentes, incluindo ORM (Mapeamento Objeto-Relacional), motor de templates, roteamento, cache, gerenciador de eventos e muito mais, permitindo que os desenvolvedores criem rapidamente aplicações web e APIs poderosas e performáticas.

Principais Características e Vantagens do Phalcon

• Performance excepcional: Sendo uma extensão C, Phalcon elimina os custos de análise e carregamento de scripts PHP, gerando desempenho nativo.
• Eficiência de recursos: O uso de memória é extremamente baixo, tornando-o ideal para aplicações que demandam alta performance e escalabilidade.
• Funcionalidade completa: Oferece quase todos os componentes essenciais para desenvolvimento web integrados, reduzindo a dependência de bibliotecas externas.
• Facilidade de uso: Possui uma API clara e consistente com documentação detalhada, facilitando o aprendizado mesmo para iniciantes.
• Alta modularidade: Os componentes são desacoplados, permitindo ao desenvolvedor escolher ou substituir módulos conforme as necessidades do projeto.
• Segurança: Inclui diversos recursos de segurança, como filtros de entrada, proteção contra CSRF, entre outros.

Phalcon é a escolha ideal para quem busca construir aplicações web e APIs escaláveis e super rápidas, principalmente quando há exigências rigorosas de desempenho e eficiência.

Criando e Executando um Projeto Phalcon com ServBay

ServBay é um ambiente de desenvolvimento web local feito para macOS, integrando múltiplas versões de PHP, bancos de dados (MySQL, PostgreSQL, MongoDB, Redis), servidores web (Caddy, Nginx, Apache) e outras ferramentas para desenvolvedores. Com ServBay, você prepara facilmente o ambiente necessário para seu projeto Phalcon.

Este guia irá mostrar como criar um projeto básico Phalcon com o ambiente PHP do ServBay, configurar o servidor web para acesso externo, e como integrar bancos de dados relacionais (MySQL) e NoSQL (Redis).

Pré-requisitos

Antes de começar, certifique-se de:

1. ServBay instalado e em execução: O ServBay deve estar corretamente instalado e ativo no macOS.
2. PHP habilitado: Garanta que a versão do PHP desejada está habilitada no ServBay.
3. Módulo Phalcon habilitado: O ServBay possui o módulo Phalcon pré-instalado, mas ele pode estar desativado por padrão. Siga as instruções do documento Como habilitar o módulo Phalcon do ServBay para habilitar a extensão do Phalcon na versão de PHP desejada e reinicie o serviço PHP.
4. Composer disponível: O ServBay já inclui o Composer, então não é necessário instalação extra. Confirme que pode executar o comando composer no terminal.

Diferentes Versões do Phalcon e DevTools

O framework Phalcon e suas DevTools precisam ser compatíveis com a sua versão de PHP. Veja abaixo uma tabela com as versões de PHP e suas recomendações de Phalcon e DevTools:

Versão do PHP	Versão Recomendada Phalcon	Versão Recomendada Phalcon DevTools	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)	DevTools oficial pode apresentar incompatibilidades com PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (versão corrigida da comunidade)	Use um repositório alternativo para melhor compatibilidade.

Importante: DevTools oficial pode não funcionar bem com PHP 8.x ou superior. Recomenda-se usar versões corrigidas mantidas pela comunidade. Os próximos passos mostrarão como instalar estas versões via Composer.

Criando um Projeto Phalcon

Caminho sugerido para sites

Por organização, ServBay recomenda que seus sites fiquem dentro do diretório padrão /Applications/ServBay/www. Este exemplo usa esse caminho.

1. Entre no diretório raiz do site e crie a pasta do projeto

   Abra o terminal, acesse o diretório do ServBay para sites e crie uma pasta para o projeto (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 é um conjunto de ferramentas CLI para gerar código, scaffolding, migrações e mais. Instale com Composer conforme a versão do PHP utilizada:

   • 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 corrigido): Como o DevTools oficial possui problemas com PHP 8.x, utilize um repositório da comunidade. Crie ou edite o composer.json no diretório raiz 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
     }

     Após isso, rode o comando para instalar o DevTools:

     composer update

   O Composer criará o diretório vendor e o executável do DevTools ficará em vendor/bin/phalcon.

3. Crie a estrutura básica do projeto com DevTools

   Use a ferramenta instalada para gerar a base de arquivos do projeto Phalcon. O código do projeto ficará em um subdiretório (normalmente nomeado igual ao diretório principal):

   vendor/bin/phalcon project servbay-phalcon-app

   O comando irá criar /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app contendo a estrutura padrão Phalcon.

4. Acesse o diretório de código do projeto

   Entre no subdiretório recém-criado, pois os próximos passos serão realizados nele:

   cd servbay-phalcon-app

   Agora o terminal estará em /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configurando o Ambiente do Projeto

A configuração do Phalcon geralmente é feita no arquivo app/config/config.php. É lá que você define detalhes dos bancos de dados, caminhos e outras opções essenciais.

1. Edite o arquivo de configuração

   Abra /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php com seu editor preferido. Adicione ou ajuste a seção de banco de dados. Por padrão, o usuário do MySQL/MariaDB no ServBay é root e a senha pode estar vazia, mas é altamente recomendado definir uma senha forte. No exemplo, usamos password como modelo — ajuste conforme sua configuração. O nome do banco servbay_phalcon_app é para o exemplo (crie-o manualmente se necessário).

   return new \Phalcon\Config([
       // ... outras configurações ...
       'database' => [
           'adapter' => 'Mysql', // Ou 'Postgres' etc
           'host' => '127.0.0.1',
           'username' => 'root', // Usuário padrão do ServBay
           'password' => 'password', // <-- Troque pela senha desejada
           'dbname' => 'servbay_phalcon_app', // <-- Troque pelo seu banco
       ],
       // ... outras configurações ...
   ]);

   Importante: Garanta que o serviço de banco de dados (MySQL/MariaDB) esteja ativo no ServBay e que usuário/senha estejam corretos. Crie o banco com o nome definido usando o phpMyAdmin ou Adminer incluído no ServBay.

Configurando o Servidor Web (Pelo recurso de Sites do ServBay)

Para acessar o projeto via navegador, utilize a função Sites do ServBay e crie uma hospedagem virtual apontando para o diretório público do projeto.

1. Abra o aplicativo ServBay
2. Acesse as configurações de 'Sites' no menu principal.
3. Adicione um novo site:
   • Nome: Exemplo, Meu Primeiro Site Phalcon.
   • Domínio: Exemplo, servbay-phalcon-test.local. O ServBay resolve .local para seu computador.
   • Tipo de site: Selecione PHP.
   • Versão do PHP: Escolha a versão utilizada/encontrada com Phalcon habilitado.
   • Diretório raiz do site: Use o diretório público do projeto, normalmente /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Salve as configurações: O ServBay aplicará as mudanças e pode exigir o restart do servidor web (Caddy ou Nginx).

Veja o passo a passo em Adicionando o primeiro site. O ServBay cuida do DNS local e das configurações dos servidores web automaticamente.

Adicionando Código de Exemplo

Vamos incluir um código simples para teste do funcionamento do projeto.

1. Configuração de rotas

   Edite /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php para inserir uma rota básica:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Defina uma rota padrão: '/' indica o controller IndexController e método indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Outras rotas podem ser adicionadas ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Crie o controller

   Crie ou edite /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php com um método simples indexAction:

   <?php
   namespace App\Controllers; // Verifique o namespace
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Manipula solicitações à rota '/'
       public function indexAction()
       {
           // Retorna uma string simples como resposta
           return 'Hello ServBay!';
       }
   }

Acessando o Site

Salve os arquivos, garanta que o ServBay está rodando, e abra seu navegador no domínio configurado:

https://servbay-phalcon-test.local

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

Integração com Banco de Dados

Phalcon oferece camadas avançadas de abstração para bancos e ORM. O ServBay possui suporte nativo para vários tipos. A seguir mostramos exemplos para MySQL e Redis.

Exemplo RDB: MySQL

Aqui mostramos como conectar no MySQL do ServBay via Phalcon e executar inserções/consultas simples.

1. Estrutura do banco (migrações)

   As DevTools do Phalcon permitem gerenciar migrações facilmente.

   • Crie arquivo de migração no diretório do projeto com:

     vendor/bin/phalcon migration generate

     Isso cria um arquivo na pasta migrations, com nome semelhante a YYYYMMDDHHMMSS_MigrationName.php.

   • Edite a migração, definindo 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 // Certifique-se de alinhar nome da classe com o arquivo
     {
         /**
          * Executa a migração
          *
          * @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',
                 ],
             ]);
         }
     
         /**
          * Reverte a migração
          *
          * @return void
          */
         public function down()
         {
             // Opcional: lógica de rollback, como remoção de tabela
             // $this->getConnection()->dropTable('users');
         }
     }

     Observação: O nome da classe no arquivo (UsersMigration_100) deve coincidir com o nome do arquivo gerado.

   • Execute a migração para criar a tabela:

     vendor/bin/phalcon migration run

     Se houver erro de conexão, verifique configuração do banco em app/config/config.php e se serviço MySQL/MariaDB está ativo.

2. Configuração de conexão (ajustada anteriormente)

   Confirme que as configurações do banco no arquivo de configuração apontam para o MySQL/MariaDB correto: host 127.0.0.1, porta 3306, usuário/senha adequados.

3. Roteiros de exemplo

   Acrescente rotas para inserir e consultar usuários em app/config/routes.php:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Rota para adicionar 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. Implementando operações no controller

   Em app/controllers/IndexController.php, insira os métodos para interagir com o banco:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Importa adaptador MySQL
   use Phalcon\Db\Enum; // Constantes de modo para fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Adiciona usuário exemplo
       public function mysqlAddAction()
       {
           // Cria conexão com banco (no exemplo, direto; no mundo real, use serviço DI)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Ajuste aqui sua senha
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Insere novo usuário
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', 'demo@servbay.test'],
               ['name', 'email']
           );
   
           // Exibe resultado
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Consulta e exibe usuários
       public function mysqlAction()
       {
            $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Ajuste aqui sua senha
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // JSON para o navegador
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Observação: Idealmente, registre a conexão no container de serviços (DI) e injete no controller, não instancie em cada action.

5. Testando

   • Visite https://servbay-phalcon-test.local/mysql-add — verá "User added successfully."
   • Visite https://servbay-phalcon-test.local/mysql — verá dados do banco em JSON, incluindo o registro recém criado.

Exemplo NoSQL: Redis

Veja como usar o Redis do ServBay como cache no projeto Phalcon.

1. Habilite a extensão Redis

   A versão do PHP disponibilizada pelo ServBay já inclui a extensão Redis na maioria dos casos. Basta garantir que ela está ativada no ServBay conforme a versão utilizada.

2. Configuração de conexão Redis

   Em app/config/config.php, adicione:

   return new \Phalcon\Config([
       // ... outras configurações ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Database Redis, geralmente 0
           'persistent' => false, // Conexão persistente (opcional)
           'auth' => null, // Adicione senha aqui se for o caso
       ],
       // ... outras configurações ...
   ]);

3. Roteamento para cache Redis

   Adicione rota para demo em app/config/routes.php:

   <?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 exemplo Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Utilizando Redis no controller

   Implemente a action de exemplo Redis em app/controllers/IndexController.php:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Importa adapter Redis
   use Phalcon\Storage\SerializerFactory; // Serialização
   
   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()
       {
           // Instancia serializador
           $serializerFactory = new SerializerFactory();
   
           // Configurações Redis — alinhe com config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600, // Tempo de vida do cache (s)
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'sua_senha_redis', // Caso necessário
           ];
   
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               // Não há dados no cache
               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 {
               // Dados já em cache
               echo "Data found in cache: ";
           }
   
           // Exibe o valor (cached ou recém setado)
           return $cachedData;
       }
   }

   Observação: Recomenda-se, para produção, configurar a instancia do cache como serviço DI.

5. Testando

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

   • Na primeira vez, aparecerá "Data not found in cache, fetching from source...Data stored in cache." e "Data fetched from source: Hello Redis from ServBay!"
   • Nas demais, dentro do tempo de cache, verá "Data found in cache: " e "Data fetched from source: Hello Redis from ServBay!", indicando que o dado veio do Redis.

Perguntas Frequentes (FAQ)

• P: Recebo erro 404 Not Found?
  • R: Garanta que o diretório raiz do site no ServBay aponta para public do seu projeto (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public), que o servidor web (Caddy/Nginx) está rodando e que o domínio funciona localmente.
• P: Erro 'Phalcon module not found'? (Class 'Phalcon\Mvc\Application' not found)
  • R: O módulo Phalcon não está ativado na versão do PHP atual. Volte ao ServBay, habilite Phalcon para o PHP do projeto e reinicie o serviço conforme o guia Como habilitar o módulo Phalcon do ServBay.
• P: Falha de conexão com o banco?
  • R: Verifique as configurações de conexão no app/config/config.php (host/usuário/senha/banco). Certifique-se que o serviço está ativo no ServBay e que o usuário tem permissão para acessar o banco, e que o banco existe.

Conclusão

Usando o ServBay, você constrói facilmente ambientes de desenvolvimento Phalcon de alta performance. Este tutorial mostrou desde a criação do projeto, configuração do servidor web, integração com MySQL e Redis, até testes de funcionamento. Os pacotes integrados e a interface amigável do ServBay simplificam a preparação e manutenção do ambiente local, permitindo que você foque na criação e evolução do seu aplicativo Phalcon. Esperamos que este guia ajude você a começar rapidamente com ServBay e Phalcon para desenvolvimento web eficiente!