Estrutura de Pastas do CakePHP: Se você já instalou o CakePHP seguindo o nosso guia anterior, deve ter aberto a pasta do projeto e pensado: “Puxa, por que tantos arquivos?”. Calma! Como um especialista que já “assou” centenas de projetos, posso te garantir: essa organização é o seu maior trunfo. No CakePHP, cada arquivo tem um endereço fixo, e entender esse mapa é o que separa um programador que “faz sites” de um desenvolvedor que constrói sistemas escaláveis.

Neste quarto artigo da nossa trilha, vamos explorar a Estrutura de Pastas do CakePHP. Prepare-se para entender a anatomia do framework e descobrir por que a convenção é a alma da produtividade.

Estrutura de Pastas: Onde cada arquivo deve ficar no CakePHP

Quando trabalhamos com PHP puro ou frameworks menos opinativos, perdemos horas discutindo onde colocar uma classe de validação ou onde salvar um arquivo de configuração. No CakePHP, essa discussão não existe. O framework adota o princípio de Convenção sobre Configuração, o que significa que, se você colocar o arquivo no lugar certo e com o nome certo, a “mágica” acontece automaticamente.

Dominar a árvore de diretórios do CakePHP é o primeiro passo para parar de lutar contra a ferramenta e começar a usá-la a seu favor.

1. O Nível Superior: A Visão Geral

Ao abrir a raiz do seu projeto, você encontrará pastas que gerenciam o ciclo de vida da aplicação, desde as dependências até os arquivos públicos.

• bin/: Contém os executáveis de console. É aqui que mora o arquivo cake, que usamos para rodar o servidor embutido ou gerar código automaticamente com o Bake.
• config/: O cérebro do seu app. Aqui ficam as definições de rotas, banco de dados e e-mail.
• logs/: Essencial para debug. Tudo o que der errado no seu código será registrado aqui.
• plugins/: Onde moram as extensões de terceiros ou módulos isolados que você mesmo criar.
• resources/: Para arquivos não-PHP, como arquivos de tradução (locales).
• src/: O coração pulsante. Aqui vive 99% do seu código customizado.
• templates/: Onde o HTML ganha vida (as Views).
• tests/: Onde você escreve seus testes automatizados (PHPUnit).
• tmp/: Arquivos temporários, cache e sessões.
• vendor/: A “caixa preta” do Composer. Nunca mexa aqui manualmente!
• webroot/: A única pasta que o mundo exterior deve ver.

2. A Pasta config: Onde as regras são ditadas

Antes de escrever uma linha de lógica, você passará pela pasta config/. Ela é pequena, mas poderosa.

• app.php: Contém configurações globais. Aqui você define o fuso horário, o idioma padrão e as chaves de segurança.
• app_local.php: O arquivo de segredos. É aqui que você configura a conexão com o MySQL ou PostgreSQL. Dica de ouro: Nunca envie este arquivo para o Git; ele deve ser único para cada ambiente (Local, Staging, Produção).
• routes.php: Aqui você mapeia URLs amigáveis. Quer que meusite.com/blog aponte para ArtigosController? É aqui que você faz isso.

3. O Diretório src: O Santuário do Desenvolvedor

Se o CakePHP fosse um corpo humano, a pasta src/ seria os órgãos vitais. Quase tudo o que discutimos sobre o MVC está aqui dentro.

src/Controller/

Aqui moram os controladores. Eles recebem as requisições e decidem o que fazer.

• Exemplo: ArtigosController.php. Note o plural e o sufixo “Controller”. Isso é convenção pura!

src/Model/

Esta pasta é dividida em três subpastas fundamentais:

1. Entity/: Representa um único registro do banco de dados (ex: Artigo.php). Aqui você coloca lógica de visualização de dados, como um método getFormatDate().
2. Table/: Representa a tabela inteira e lida com consultas (ex: ArtigosTable.php). É aqui que você define validações e relacionamentos (HasMany, BelongsTo).
3. Behavior/: Lógica reaproveitável entre tabelas, como o comportamento de “Timestamp” (que preenche datas automaticamente).

src/View/

Diferente dos templates HTML, esta pasta contém classes auxiliares:

• Helper/: Funções para usar nos templates, como o FormHelper ou HtmlHelper.

src/Command/ e src/Middleware/

• Command: Para criar scripts que rodam via terminal (ex: um script de limpeza de banco).
• Middleware: Camadas que interceptam a requisição antes de chegar ao controller (ex: um filtro que verifica se o site está em manutenção).

4. templates: Onde o usuário interage

Antigamente chamada de “View”, a pasta templates/ agora fica na raiz para facilitar o acesso de designers e desenvolvedores front-end.

A estrutura aqui espelha os seus Controllers:

• templates/Artigos/index.php (Lista todos os artigos).
• templates/Artigos/view.php (Mostra um artigo específico).
• templates/layout/: Contém o “esqueleto” do site (Header, Footer, Sidebar).
• templates/element/: Pequenos pedaços de código que se repetem, como um banner ou um card de produto.

5. webroot: A Linha de Frente

Por questões de segurança, o seu servidor web (Apache ou Nginx) deve apontar para esta pasta. Isso garante que ninguém consiga acessar seus arquivos de configuração ou lógica diretamente pela URL.

Dentro de webroot/, você deve organizar seus ativos estáticos:

• css/
• js/
• img/
• files/ (Para uploads de usuários).

6. Exemplo Prático: Criando um novo recurso

Imagine que você quer criar uma seção de “Categorias” no seu blog. Onde cada arquivo deve morar? Seguindo a estrutura do CakePHP:

1. Banco de Dados: Tabela categorias.
2. Model (Tabela): src/Model/Table/CategoriasTable.php.
3. Model (Entidade): src/Model/Entity/Categoria.php.
4. Controller: src/Controller/CategoriasController.php.
5. Templates: templates/Categorias/index.php e templates/Categorias/add.php.

Se você seguir essa nomenclatura e localização, o CakePHP saberá exatamente como conectar as peças sem que você precise escrever uma única linha de include.

Por que essa organização é superior?

Muitos iniciantes reclamam que o CakePHP é “rígido”. No entanto, essa rigidez é o que traz escalabilidade. Quando você entra em um projeto CakePHP feito por outra pessoa, você não gasta três dias tentando entender onde os arquivos estão. Você vai direto na pasta src/Controller e pronto.

Essa padronização facilita:

• Trabalho em equipe: Todos falam a mesma “língua” de diretórios.
• Updates do Framework: O núcleo está isolado em vendor/, então atualizar o CakePHP é seguro.
• Segurança: A separação entre src/ e webroot/ é uma barreira natural contra ataques.

Conclusão: O Mapa na palma da sua mão

Estrutura de Pastas do CakePHP: Entender a Estrutura de Pastas do CakePHP é como aprender a planta baixa da sua própria casa. Agora você sabe onde cada ferramenta está guardada e como adicionar novos cômodos de forma organizada.

Não tente decorar tudo de uma vez. Com a prática e o uso constante do terminal, esses caminhos se tornarão automáticos na sua mente. No próximo artigo, vamos falar sobre o conceito que torna tudo isso funcional: “Convenção sobre Configuração: Por que o CakePHP acelera tanto o desenvolvimento?”

Mas antes de dominar o CakePHP, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no CakePHP, você precisará dominar as seguintes tecnologias:

E se você gosta do nosso conteúdo, não deixe de contribuir adquirindo os serviços e produtos dos nossos apoiadores e empresas que somos associados.

Estrutura de Pastas do CakePHP: E por fim e não menos importante, compartilhe nossos artigos com aquele amigo iniciante ou aquele que já trabalha na área e precisa de um material de apoio completinho!

Diga adeus à bagunça de arquivos e seja bem-vindo ao desenvolvimento profissional!