Criando e Executando Projetos CakePHP com o ServBay

O ServBay é um ambiente de desenvolvimento web local para macOS e Windows, com suporte integrado para várias linguagens como PHP, Node.js, Python, Go, Java, além dos bancos de dados MySQL, PostgreSQL, MongoDB, Redis e outros, utilizando os servidores web Caddy ou Nginx. Ele oferece uma plataforma prática e eficiente para desenvolvedores iniciarem e gerenciarem seus projetos locais com facilidade.

Neste artigo, você aprenderá como criar, configurar e executar um projeto CakePHP utilizando o ServBay. O CakePHP é um framework popular de desenvolvimento web em PHP, baseado no padrão MVC (Model-View-Controller), conhecido por sua rapidez no desenvolvimento, ORM poderoso e recursos de segurança integrados. Com a praticidade do ServBay, você pode começar a desenvolver com CakePHP de forma rápida e eficiente.

O Que é CakePHP?

CakePHP é um framework open source para o desenvolvimento de aplicações web em PHP. Ele oferece uma estrutura básica para criar aplicações de forma rápida e organizada, sem abrir mão da flexibilidade. Seguindo o princípio de que “convenção é melhor que configuração”, o CakePHP simplifica diversas tarefas comuns do desenvolvimento.

Principais Características e Vantagens do CakePHP

• Baseado no padrão MVC: Estrutura clara de organização de código, fácil de manter e expandir.
• Desenvolvimento rápido: Ferramenta de linha de comando (Bake) para geração automática de código e agilidade no fluxo de desenvolvimento.
• ORM poderoso (mapeamento objeto-relacional): Facilita a interação com bancos de dados, suportando vários sistemas.
• Recursos de segurança integrados: Proteção contra CSRF, injeção de SQL, validação de entrada e muito mais.
• Template Engine flexível: Compatível com diferentes tecnologias de camada de visualização.
• Comunidade ativa e muitos plugins: Suporte facilitado e possibilidade de expansão das funcionalidades.
• Documentação abrangente: Guias completos e referência de API disponíveis.

CakePHP é indicado para a construção de aplicações web de todos os portes, desde APIs simples até sistemas empresariais robustos.

Montando o Ambiente de Desenvolvimento CakePHP com ServBay

O ServBay oferece uma estrutura integrada para desenvolvimento CakePHP, incluindo:

• Interpretador PHP pré-instalado, com extensões usadas frequentemente.
• Gerenciador de pacotes Composer já instalado.
• Servidor web fácil de configurar (Caddy/Nginx).
• Serviços integrados de banco de dados (MySQL, PostgreSQL, Redis etc.).

Com o ServBay, você evita o processo manual e demorado de instalação e configuração desses componentes.

Pré-requisitos

Antes de começar, certifique-se de ter feito o seguinte:

1. Instalar o ServBay: Baixe e instale o ServBay em seu computador com macOS.
2. Inicializar os serviços do ServBay: Abra o ServBay e garanta que os pacotes necessários (como PHP, o banco de dados que deseja usar, e serviços de cache como Redis ou Memcached) estejam rodando. Você pode gerenciar estes serviços no menu “Pacotes” do painel de controle do ServBay.
3. Dominar operações básicas do ServBay: Saiba como adicionar e configurar sites dentro do ServBay. Se não estiver familiarizado, recomendamos ler o Guia básico de uso do ServBay primeiro.

Criando um Projeto CakePHP

O ServBay recomenda armazenar seus projetos web no diretório /Applications/ServBay/www, facilitando o reconhecimento e gestão automática dos sites pelo ServBay.

1. Abra o Terminal

   Acesse o app Terminal do macOS.

2. Navegue até a pasta raiz de sites do ServBay

   Entre no diretório padrão sugerido pelo ServBay:

   cd /Applications/ServBay/www

3. Crie o diretório do projeto

   Crie uma subpasta para o seu projeto CakePHP. Usaremos servbay-cakephp-app como exemplo:

   mkdir servbay-cakephp-app
   cd servbay-cakephp-app

4. Crie o projeto CakePHP com Composer

   O Composer já vem pré-instalado no ServBay. Dentro da pasta do projeto, execute:

   composer create-project --prefer-dist cakephp/app .

   Este comando irá baixar a versão estável mais recente do CakePHP com todas as dependências, instalando-as na pasta corrente (.).

5. Instale o driver ORM para PostgreSQL (caso necessário)

   Se for utilizar PostgreSQL como banco de dados, instale o driver ORM adicional:

   composer require cakephp/orm-pgsql

   Usuários de MySQL normalmente não precisam instalar drivers extras, pois já estão incluídos.

Configuração Inicial

Após criar o projeto, é preciso realizar configurações básicas, especialmente dos dados de conexão com o banco de dados.

1. Configurar variáveis de ambiente e conexão com o banco

   A configuração do ambiente local do CakePHP está, principalmente, no arquivo config/app_local.php. Edite este arquivo e, na seção Datasources, configure os dados de acesso do banco. Normalmente, o usuário padrão do ServBay é root e a senha é password.

   Exemplo de configuração para MySQL:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // Ou \Cake\Database\Driver\Postgres::class para PostgreSQL
           'persistent' => false,
           'host' => '127.0.0.1', // Endereço do servidor de banco, padrão local no ServBay
           //'port' => '3306', // Porta padrão MySQL 3306, PostgreSQL 5432
           'username' => 'root', // Usuário padrão do ServBay
           'password' => 'password', // Senha padrão do ServBay
           'database' => 'servbay_cakephp_app', // Nome do banco a ser criado
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Marque quoteIdentifiers como true se for usar nomes reservados, como "user", nas tabelas.
            * Para nomes comuns, pode deixar como false.
            * Se não souber, use true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Limitações atuais:
            * - A maioria dos drivers não suporta configuração de níveis de isolamento via PDO options, o que pode gerar erros.
            * - Nem todos os drivers suportam configuração de charset via PDO options.
            * - Opções PDO não são suportadas para drivers empacotados como o Postgres do CakePHP (basta definir o encoding).
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Caso utilize a variável DATABASE_URL, ative esta linha
       ],
   ],

   Ajuste o tipo do driver e porta conforme estiver usando MySQL ou PostgreSQL, e certifique-se que o nome do banco coincide com o que irá criar.

Configurando o Servidor Web (Criando o site no ServBay)

Para acessar o projeto CakePHP pelo navegador, você precisa configurar um site no ServBay apontando para o diretório do projeto.

1. Abra o painel de controle do ServBay

   Clique no ícone do ServBay para abrir o painel.

2. Acesse a aba “Sites”

   No painel, selecione “Sites” (antes chamado de “Hosts”) no menu lateral.

3. Adicione novo site

   Clique no botão + no rodapé para adicionar um site. Preencha os campos:

   • Nome (Name): Um nome de fácil identificação, ex: Meu Site CakePHP Dev.
   • Domínio (Domain): Defina um domínio local para desenvolvimento, ex: servbay-cakephp-test.local (ServBay fará o apontamento automaticamente).
   • Tipo de Site (Site Type): Escolha PHP.
   • Versão do PHP (PHP Version): Para CakePHP 4+, PHP 7.4+; para CakePHP 5+ normalmente PHP 8.1+ (exemplo: 8.3).
   • Raiz do site (Document Root): Importante! O diretório raiz do servidor web para CakePHP é o webroot dentro do projeto, e não o diretório principal. Defina como /Applications/ServBay/www/servbay-cakephp-app/webroot (substitua pelo nome real da pasta do seu projeto).

4. Salve e aplique as mudanças

   Clique em “Salvar” e confirme. O ServBay irá configurar automaticamente o servidor web (Caddy/Nginx), respondendo ao domínio servbay-cakephp-test.local e direcionando requisições para a pasta webroot do seu projeto.

Veja passo a passo detalhado em Adicionando o primeiro site.

Verificando as Configurações Básicas

Agora, você já deve conseguir acessar o novo site pelo navegador.

Abra o navegador e visite o domínio que configurou, por exemplo: https://servbay-cakephp-test.local.

Se tudo estiver correto, verá a página padrão de boas-vindas do CakePHP, indicando que o ambiente PHP, o servidor web e o ServBay estão funcionando corretamente.

Integrando Banco de Dados e Serviços de Cache

O CakePHP possui um ORM e abstração de cache robustos, facilitando a integração com bancos de dados e serviços como os oferecidos pelo ServBay.

Exemplo de Banco Relacional (MySQL / PostgreSQL)

Veja como conectar o CakePHP ao MySQL ou PostgreSQL do ServBay, criar uma tabela simples users e realizar operações básicas de CRUD.

1. Crie o banco de dados no ServBay

   Antes de migrar tabelas, crie o banco usando ferramentas do ServBay (phpMyAdmin para MySQL/MariaDB, pgAdmin para PostgreSQL ou softwares como Navicat/DBeaver). Conecte usando 127.0.0.1, usuário root e senha password. Crie o banco como servbay_cakephp_app.

2. Crie a Model ORM

   O CakePHP ORM utiliza um arquivo Model para representar cada tabela. Crie um arquivo UsersTable.php para a tabela users.

   Salve este código em src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Se necessário, para regras de validação
   
   class UsersTable extends Table
   {
       /**
        * Método de inicialização
        *
        * @param array $config Configurações da tabela.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Define o nome da tabela
           $this->setDisplayField('name'); // Campo padrão para exibições
           $this->setPrimaryKey('id'); // Define a chave primária
   
           // Caso queira marcação automática de datas
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Regras de validação padrão.
        *
        * @param \Cake\Validation\Validator $validator Instância do validador.
        * @return \Cake\Validation\Validator
        */
       public function validationDefault(Validator $validator): Validator
       {
           $validator
               ->scalar('name')
               ->maxLength('name', 255)
               ->requirePresence('name', 'create')
               ->notEmptyString('name');
   
           $validator
               ->email('email')
               ->requirePresence('email', 'create')
               ->notEmptyString('email')
               ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // Garante unicidade do email
   
           return $validator;
       }
   }

3. Crie o arquivo de migração com a ferramenta Bake

   O CakePHP recomenda o uso de migração para o controle da estrutura de banco de dados. Na raiz do projeto (/Applications/ServBay/www/servbay-cakephp-app), execute:

   bin/cake bake migration CreateUsers name:string email:string:unique

   Este comando cria o arquivo de migração para a tabela users, com os campos name (string) e email (string e único).

4. Execute a migração do banco

   Para criar a tabela no banco previamente criado:

   bin/cake migrations migrate

   Se tudo ocorrer bem, a tabela users aparecerá no banco.

5. Configure a conexão ao banco (caso ainda não tenha feito)

   Verifique se o config/app_local.php está correto para o banco e credenciais que escolheu.

   • Exemplo para MySQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Mysql::class,
             'host' => '127.0.0.1',
             'username' => 'root',
             'password' => 'password',
             'database' => 'servbay_cakephp_app',
             // ... demais configurações
         ],
     ],

   • Exemplo para PostgreSQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // Porta padrão
             'username' => 'root', // Padrão ServBay
             'password' => 'password', // Padrão ServBay
             'database' => 'servbay_cakephp_app',
             // ... demais configurações
         ],
     ],

6. Adicione rotas e métodos no Controller de exemplo

   Edite o arquivo config/routes.php, criando rotas para adicionar e listar usuários:

   // config/routes.php
   use Cake\Routing\RouteBuilder;
   use Cake\Routing\Router;
   use Cake\Routing\Route\DashedRoute;
   
   Router::defaultRouteClass(DashedRoute::class);
   
   Router::scope('/', function (RouteBuilder $routes) {
       // ... outras rotas
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Rotas de exemplo para banco de dados
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... outras rotas
       $routes->fallbacks(DashedRoute::class);
   });

   Modifique o arquivo src/Controller/PagesController.php com os métodos de manipulação de dados:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Para tratamento de exceção de registro não encontrado
   
   class PagesController extends AppController
   {
       /**
        * Exibe uma página
        *
        * @param array ...$path Segmentos do caminho.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // ... método padrão
           return new Response(['body' => 'Olá ServBay! Esta é a página padrão.']);
       }
   
       /**
        * Exemplo de banco: adiciona usuário
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Instância da tabela Users
   
           // Cria novo usuário
           $user = $usersTable->newEntity([
               'name' => 'Usuário Demo ServBay',
               'email' => 'servbay-demo@servbay.test' // Email de exemplo da marca ServBay
           ]);
   
           // Tenta salvar no banco
           if ($usersTable->save($user)) {
               return new Response(['body' => 'Usuário adicionado com sucesso! ID do usuário: ' . $user->id]);
           } else {
               // Se falhar, pode ser erro de validação ou outro
               $errors = $user->getErrors();
               return new Response(['body' => 'Falha ao adicionar usuário. Erros: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Exemplo de banco: lista usuários
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Instância da tabela
   
           // Busca todos usuários
           $users = $usersTable->find()->all();
   
           // Retorna em JSON
           return new Response(['body' => json_encode($users->toArray())]);
       }
   }

7. Acesse os exemplos do banco

   No navegador:

   • Use https://servbay-cakephp-test.local/db-add-user para adicionar um usuário. Uma mensagem de sucesso será exibida.
   • Vá em https://servbay-cakephp-test.local/db-list-users para listar todos os usuários (incluindo o recém-adicionado).

Dessa forma, seu projeto CakePHP estará conectado ao banco de dados relacional do ServBay, pronto para operações ORM básicas.

Exemplo de Serviço de Cache (Memcached / Redis)

O CakePHP possui API unificada para cache, permitindo alternar facilmente entre engines como Memcached ou Redis. O ServBay tem as extensões PHP para Memcached e Redis instaladas, e oferece os respectivos serviços prontos para uso.

Antes de iniciar, verifique se, no painel “Pacotes” do ServBay, os serviços Memcached ou Redis estão rodando.

1. Configure a conexão de cache

   Edite config/app_local.php, na seção Cache, conforme o serviço que escolheu.

   • Exemplo Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // Endereço padrão ServBay
             'prefix' => 'servbay_cakephp_', // Prefixo das chaves de cache
         ],
         // ... outras configurações
     ],

   • Exemplo Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // Endereço padrão ServBay
             'port' => 6379, // Porta padrão ServBay
             'password' => null, // Preencha se houver senha
             'database' => 0, // Índice do banco Redis
             'prefix' => 'servbay_cakephp_', // Prefixo das chaves de cache
         ],
         // ... outras configurações
     ],

   Escolha a configuração correspondente ao serviço que irá usar.

2. Adicione rotas e métodos de exemplo ao Controller

   No arquivo config/routes.php, crie rotas específicas para exemplos de cache:

   // config/routes.php
   // ... outras rotas
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // ... outras rotas

   E no src/Controller/PagesController.php:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache; // Importa Cache
   // ... outros use
   
   class PagesController extends AppController
   {
       // ... outros métodos (display, dbAddUser, dbListUsers)
   
       /**
        * Exemplo de cache: utilizando Memcached
        */
       public function cacheMemcached(): Response
       {
           // Garanta que 'default' está configurado com MemcachedEngine
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Cache não encontrado
               $responseBody = 'Cache não encontrado! Gravando "Olá Memcached!" no cache.';
               $dataToCache = 'Olá Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Cache encontrado
               $responseBody = 'Cache encontrado! Dados do cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Exemplo de cache: utilizando Redis
        */
       public function cacheRedis(): Response
       {
            // Certifique-se que 'default' está configurado com RedisEngine
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Cache não encontrado
               $responseBody = 'Cache não encontrado! Gravando "Olá Redis!" no cache.';
               $dataToCache = 'Olá Redis!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Cache encontrado
               $responseBody = 'Cache encontrado! Dados do cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Acesse os exemplos de cache

   No navegador:

   • Se configurar Memcached, visite https://servbay-cakephp-test.local/cache-memcached. No primeiro acesso verá “Cache não encontrado”, e ao recarregar a página verá “Cache encontrado”.
   • Para Redis, acesse https://servbay-cakephp-test.local/cache-redis. O funcionamento é similar.

Esses testes indicam que seu projeto CakePHP já consegue se comunicar e utilizar os serviços de cache do ServBay.

Dicas e Cuidados

• Credenciais de banco: Os padrões (root/password) do ServBay são apenas para desenvolvimento local. Em produção, use senhas fortes e seguras.
• Raiz do site: O “Document Root” deve apontar para o diretório webroot do projeto, e não para a pasta raiz do CakePHP.
• Compatibilidade de versão PHP: Cheque se a versão do PHP no ServBay é compatível com a do CakePHP usado (veja na documentação oficial).
• Portas do ServBay: Se as portas padrão (80/443) já estão sendo usadas por outro programa, modifique as portas nas configurações do ServBay e acesse pelo novo número de porta ou ajuste o arquivo hosts.

Perguntas Frequentes (FAQ)

• Q: Ao acessar servbay-cakephp-test.local aparece erro de “Página não encontrada”?
  • A: Verifique se o “Document Root” no ServBay está realmente em /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Confirme se o servidor Caddy/Nginx está rodando.
  • Cheque se o domínio servbay-cakephp-test.local está resolvendo para 127.0.0.1 (ServBay costuma automatizar isso, mas pode ser necessário conferir).
  • Veja se o arquivo .htaccess do projeto ou as configs do servidor web estão corretas (webroot/.htaccess geralmente já está certo).
• Q: Falha na conexão com o banco?
  • A: Confirme se o serviço do banco no ServBay (MySQL/PostgreSQL) está ativo.
  • Confira se as informações de conexão (host, porta, usuário, senha, banco) estão corretas em config/app_local.php.
  • Certifique-se de que o banco de dados servbay_cakephp_app foi criado no servidor.
• Q: Não consigo executar comandos Composer (bin/cake)?
  • A: Garanta que está no diretório do projeto no Terminal (/Applications/ServBay/www/servbay-cakephp-app).
  • Certifique-se de que os pacotes PHP e Composer estejam ativos no ServBay.
  • Confira se o terminal reconhece o comando php (ServBay fornece isso pela variável PATH). Se precisar, utilize o terminal integrado do ServBay ou ajuste o PATH manualmente.

Conclusão

Usando o ServBay, você pode montar o ambiente de desenvolvimento do CakePHP de forma prática e eficiente. O PHP, Composer, servidores web e bancos de dados já vêm prontos, simplificando a configuração. Este artigo guiou você pelo processo de criação, configuração, integração com banco de dados e cache, e resolução dos principais problemas, permitindo que foque no desenvolvimento ao invés de questões de infraestrutura. Com a praticidade do ServBay, seu caminho para criar aplicações CakePHP ficou muito mais simples!