Criando e Executando um Projeto CakePHP com o ServBay

O ServBay é um ambiente de desenvolvimento web local criado especialmente para o macOS, oferecendo suporte integrado a diversas linguagens como PHP, Node.js, Python, Go e Java, além de serviços de banco de dados como MySQL, PostgreSQL, MongoDB e Redis, com servidores web Caddy ou Nginx. Ele proporciona uma plataforma prática e eficiente para desenvolvedores configurarem e gerenciarem projetos locais com facilidade.

Neste guia, você aprenderá a criar, configurar e executar um projeto CakePHP usando o ambiente ServBay. O CakePHP é um dos frameworks PHP mais populares, seguindo o padrão MVC (Model-View-Controller), famoso pela rapidez no desenvolvimento, poderoso ORM e ótimos recursos de segurança. Com a praticidade do ServBay, você pode iniciar seu desenvolvimento CakePHP em poucos minutos.

O que é o CakePHP?

O CakePHP é um framework open source para desenvolvimento de aplicações web em PHP. Ele oferece uma estrutura robusta para criar projetos web de maneira rápida e organizada, sem perder a flexibilidade. Baseia-se no princípio de “convenção acima da configuração”, facilitando várias tarefas comuns do desenvolvimento.

Principais Recursos e Vantagens do CakePHP

• Baseado no padrão MVC: Organização de código clara, facilitando manutenção e expansão.
• Desenvolvimento rápido: Ferramenta de linha de comando (Bake) para geração de código e agilidade nas entregas.
• ORM poderoso: Simplifica a interação com bancos de dados, com suporte a múltiplos sistemas.
• Segurança integrada: Proteção CSRF, contra injeção de SQL, validação de entradas e outros recursos.
• Motor de templates flexível: Suporte a diferentes tecnologias na camada de visualização.
• Comunidade ativa e muitos plugins: Facilidade para encontrar suporte e estender funcionalidades.
• Documentação completa: Guias detalhados e referência de APIs.

O CakePHP é ideal tanto para APIs simples quanto para sistemas corporativos complexos.

Preparando o Ambiente CakePHP no ServBay

O ServBay fornece um ambiente pronto para desenvolvimento CakePHP, incluindo:

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

Assim, você evita a complexidade da instalação e ajuste manual destes componentes.

Pré-requisitos

Antes de começar, verifique se atendeu aos seguintes passos:

1. Instale o ServBay: Baixe e instale o ServBay no seu macOS.
2. Inicie os serviços do ServBay: Abra o aplicativo e certifique-se de que os pacotes necessários (PHP, banco de dados desejado como MySQL ou PostgreSQL, e serviços de cache como Redis ou Memcached) estejam ativos. No painel do ServBay, gerencie isso pela aba “Pacotes”.
3. Familiarize-se com as operações básicas do ServBay: Entenda como adicionar e configurar sites no ServBay. Se necessário, consulte o Guia Básico do ServBay.

Criando um Projeto CakePHP

O ServBay recomenda armazenar seus projetos web em /Applications/ServBay/www, facilitando a detecção e gestão automática dos sites.

1. Abra o Terminal

   Execute o Terminal no macOS.

2. Navegue até o diretório raiz dos sites do ServBay

   Altere para o diretório recomendado do ServBay:

   cd /Applications/ServBay/www

3. Crie o diretório do projeto

   Crie uma pasta para seu projeto CakePHP. No exemplo, usamos servbay-cakephp-app:

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

4. Crie o projeto CakePHP com o Composer

   O Composer já vem instalado no ServBay. Crie a estrutura do projeto usando:

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

   Este comando baixa a versão estável mais recente do CakePHP com todas as dependências, instalando-as no diretório atual (.).

5. Instale driver ORM (caso use PostgreSQL)

   Se usar PostgreSQL como banco de dados, será necessário instalar o driver correspondente:

   composer require cakephp/orm-pgsql

   Para MySQL, o driver já está incluído nas dependências padrão do CakePHP.

Configuração Inicial

Após criar o projeto, faça algumas configurações essenciais, principalmente dos dados de conexão com o banco.

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

   A configuração local do CakePHP está concentrada no arquivo config/app_local.php. Edite a seção Datasources e configure conforme seu banco. O usuário padrão no ServBay costuma ser 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 banco de dados, padrão local 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,
   
           /**
            * Ative quoteIdentifiers se usar nomes reservados como "user" em tabelas.
            * Para nomes simples como "cake", pode desativar.
            * Se não souber, use true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Algumas limitações atuais:
            * - A maioria dos drivers não permite definir níveis de isolamento via opções PDO.
            *   Usar isso causa erro.
            * - Nem todos drivers suportam charset via opções PDO.
            *   Usar resulta em erro.
            * - Opções PDO não são suportadas para drivers como o Postgres do CakePHP.
            *   Para Postgres, defina apenas o encoding.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Se usar DATABASE_URL, ative esta linha
       ],
   ],

   Ajuste driver e possível port conforme o banco utilizado (MySQL/PostgreSQL). Certifique-se de que o nome em database seja o mesmo do banco criado.

Configurando o Servidor Web (Criando o site no ServBay)

Para acessar o projeto CakePHP pelo navegador, crie um site no ServBay apontando para o diretório do seu projeto.

1. Abra o Painel do ServBay

   Clique no ícone do ServBay para abrir o painel.

2. Vá para a aba "Sites"

   No painel, acesse a aba “Sites” (anteriormente “Hosts”) na barra lateral.

3. Adicione um novo site

   Clique no botão + para adicionar um novo site. Preencha:

   • Nome: Nome fácil para identificação, como My CakePHP Dev Site.
   • Domínio: Um domínio local, como servbay-cakephp-test.local (o ServBay mapeia automaticamente para localhost).
   • Tipo de Site: Escolha PHP.
   • Versão do PHP: Selecione a versão compatível com seu CakePHP (ex: CakePHP 4+ requer PHP 7.4+, CakePHP 5+ geralmente pede PHP 8.1+), como 8.3.
   • Raiz do documento: Importante! O diretório raiz do CakePHP a ser usado pelo servidor web é o webroot dentro do projeto, não a pasta principal. Defina como /Applications/ServBay/www/servbay-cakephp-app/webroot (substitua servbay-cakephp-app conforme necessário).

4. Salve e aplique as alterações

   Após preencher, clique em “Salvar”. O ServBay solicitará a aplicação das mudanças, confirme. Assim, o ServBay configura automaticamente o servidor web (Caddy ou Nginx) para responder ao domínio servbay-cakephp-test.local apontando para o webroot do seu projeto.

Para ver detalhes do processo, consulte Adicionando o Primeiro Site na documentação do ServBay.

Verificando a Configuração Básica

Agora já é possível acessar o site criado.

Abra o navegador e acesse o domínio cadastrado, como https://servbay-cakephp-test.local.

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

Integração com Banco de Dados e Cache

O CakePHP possui um ORM e sistema de cache potentes que facilitam a integração com serviços como bancos de dados e cache do ServBay.

Exemplo de Banco Relacional (MySQL / PostgreSQL)

Veja como usar o ORM do CakePHP para conectar-se ao MySQL ou PostgreSQL no ServBay, criar uma tabela users e realizar operações básicas.

1. Crie o banco de dados no ServBay

   Antes de migrar, crie um novo banco no ServBay. Use ferramentas como phpMyAdmin (MySQL/MariaDB), pgAdmin (PostgreSQL) ou Navicat/DBeaver, conectando em 127.0.0.1, usuário root, senha password e crie um banco chamado servbay_cakephp_app.

2. Crie o arquivo Model do ORM

   O ORM do CakePHP precisa de um Model para representar a tabela. Crie UsersTable.php para a tabela users.

   Salve o código a seguir em src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Para regras de validação
   
   class UsersTable extends Table
   {
       /**
        * Método de inicialização
        *
        * @param array $config Configuração da tabela.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Nome da tabela
           $this->setDisplayField('name'); // Campo padrão exibido em associações
           $this->setPrimaryKey('id'); // Chave primária
   
           // Para uso de comportamento de timestamp
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Regras de validação padrão.
        *
        * @param \Cake\Validation\Validator $validator Instância de Validator.
        * @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 email único
   
           return $validator;
       }
   }

3. Crie o arquivo de migration com Bake

   O CakePHP recomenda migrations para gerenciar estrutura de banco. No terminal, no diretório do projeto (/Applications/ServBay/www/servbay-cakephp-app), rode:

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

   Isso cria um migration para a tabela users, com campos name (string) e email (string e único).

4. Execute a migration

   Rode a migration para criar a tabela no banco:

   bin/cake migrations migrate

   Após o comando, a tabela users estará criada.

5. Configure a conexão ao banco (se necessário)

   Verifique se config/app_local.php tem a configuração correta do banco.

   • 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',
             // ... outras configs
         ],
     ],

   • 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', // Usuário padrão ServBay
             'password' => 'password', // Senha padrão
             'database' => 'servbay_cakephp_app',
             // ... outras configs
         ],
     ],

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

   Em config/routes.php, adicione rotas para inserir 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 com banco
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... outras rotas
       $routes->fallbacks(DashedRoute::class);
   });

   Depois, em src/Controller/PagesController.php, adicione os métodos:

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

7. Acesse os exemplos no navegador

   • Vá para https://servbay-cakephp-test.local/db-add-user para adicionar um usuário. Uma mensagem de sucesso será mostrada.
   • Vá para https://servbay-cakephp-test.local/db-list-users para exibir todos os usuários cadastrados.

Assim, você conecta o CakePHP ao banco relacional do ServBay e executa operações básicas com ORM.

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

O CakePHP tem uma API de cache unificada, facilitando a troca entre engines, como Memcached e Redis. O ServBay já oferece Memcached e Redis prontos, com extensões PHP.

Antes, confira se ativou Memcached ou Redis na aba “Pacotes” do painel do ServBay.

1. Configure a conexão de cache

   Edite o arquivo config/app_local.php, seção Cache.

   • Exemplo Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // Endereço e porta padrão ServBay
             'prefix' => 'servbay_cakephp_',
         ],
     ],

   • Exemplo Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1',
             'port' => 6379,
             'password' => null, // Adicione se configurou senha no Redis
             'database' => 0,
             'prefix' => 'servbay_cakephp_',
         ],
     ],

   Configure a engine conforme serviço utilizado.

2. Adicione rotas e métodos de exemplo

   Em config/routes.php:

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

   Em src/Controller/PagesController.php:

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

3. Testando o cache no navegador

   • Se configurou Memcached, acesse https://servbay-cakephp-test.local/cache-memcached. Da primeira vez, verá "Cache miss", depois "Cache hit".
   • Se configurou Redis, acesse https://servbay-cakephp-test.local/cache-redis. O comportamento é equivalente.

Isso mostra que o CakePHP está usando o serviço de cache do ServBay com sucesso.

Atenção

• Credenciais do banco: As credenciais padrão (root/password) são só para desenvolvimento local. Em produção, utilize dados seguros.
• Raiz do site: Sempre aponte a "Raiz do documento" do site no ServBay para o diretório webroot dentro do projeto CakePHP.
• Versão do PHP: Use uma versão de PHP compatível com a versão do CakePHP usada. Consulte a documentação oficial do CakePHP.
• Portas do ServBay: Caso as portas padrão (80 e 443) estejam em uso, altere nas configurações do ServBay e ajuste hosts ou use o número da porta ao acessar.

Perguntas Frequentes (FAQ)

• Q: Ao acessar servbay-cakephp-test.local recebo “Página não encontrada”?
  • A: Confirme se a "Raiz do documento" do site está apontando para /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Verifique se o servidor web (Caddy/Nginx) está em execução.
  • Veja se o hosts do sistema está mapeando corretamente servbay-cakephp-test.local para 127.0.0.1 (o ServBay faz isso automaticamente, mas vale checar).
  • Confirme se as configurações do .htaccess do CakePHP ou arquivos de configuração do servidor web estão corretas (normalmente webroot/.htaccess já está certo).
• Q: Falha ao conectar ao banco?
  • A: Confira se os serviços de banco de dados no ServBay (MySQL/PostgreSQL) estão ativos.
  • Certifique-se que os dados de conexão (host, port, username, password, database) no config/app_local.php estão corretos e compatíveis com a configuração do ServBay.
  • Verifique se o banco servbay_cakephp_app foi criado.
• Q: Comando Composer (bin/cake) não executa?
  • A: Esteja no diretório raiz do projeto (/Applications/ServBay/www/servbay-cakephp-app).
  • Assegure-se que os pacotes PHP e Composer do ServBay estão ativos.
  • Verifique se o terminal encontra o comando php (o ServBay normalmente adiciona o PHP ao PATH). Tente o terminal integrado do ServBay ou ajuste o PATH manualmente.

Resumo

O ServBay facilita a preparação de ambientes CakePHP no macOS, com PHP, Composer, servidor web e banco de dados integrados, tornando a configuração muito mais simples. Este guia apresentou desde a criação do projeto, passando pela configuração básica, ajustes do servidor web, até integração com banco de dados e cache, permitindo que você comece a desenvolver com CakePHP rapidamente. Aproveite a praticidade do ServBay para focar no código, não na complexidade do ambiente!