Tópico 3 — Arquitetura de Diretórios e Arquivos | Guia Técnico WordPress, Banco de Dados e Next.js

1. Entendendo a Estrutura

O WordPress é organizado para separar responsabilidades entre núcleo, conteúdo e interface. A leitura correta dessa estrutura é essencial para editar com segurança, manter compatibilidade e compreender onde o código é executado.

Objetivo entender o que cada pasta faz, como o sistema se comporta no servidor e como estruturar um ambiente limpo e versionado.

2. Estrutura Principal

Mapa de diretórios (nível raiz)

/ (raiz)
├── index.php                # Entrada principal
├── wp-config.php            # Configurações do site e banco
├── wp-admin/                # Interface administrativa
├── wp-includes/             # Core: classes e funções centrais
└── wp-content/              # Temas, plugins e uploads
    ├── themes/              # Temas ativos e filhos
    ├── plugins/             # Funcionalidades adicionais
    └── uploads/             # Mídias enviadas via painel

As pastas wp-admin e wp-includes são parte do core e não devem ser alteradas. A única pasta destinada a personalização é wp-content.

3. Estrutura de um Tema

Tema padrão

wp-content/
└── themes/
    └── meu-tema/
        ├── style.css         # Identifica o tema e define metadados
        ├── functions.php     # Hooks, scripts, configurações
        ├── index.php         # Template base (fallback)
        ├── header.php / footer.php / sidebar.php
        ├── single.php / page.php / archive.php / 404.php
        ├── template-parts/   # Componentes reutilizáveis
        └── assets/           # css, js, imagens, fontes

Arquivo	Finalidade
style.css	Arquivo obrigatório. Contém nome do tema, autor e descrição.
functions.php	Adiciona hooks, registra menus, enfileira scripts e estilos.
index.php	Template genérico usado como fallback.
template-parts/	Blocos reutilizáveis como cards, cabeçalhos e rodapés.
assets/	Contém os recursos estáticos do tema, organizados por tipo.

4. Estrutura de um Plugin

Exemplo de plugin

wp-content/
└── plugins/
    └── meu-plugin/
        ├── meu-plugin.php           # Arquivo principal (header obrigatório)
        ├── includes/                # Funções auxiliares
        ├── assets/                  # css/js do plugin
        ├── admin/                   # telas e lógica do painel
        └── readme.txt

Cabeçalho obrigatório (meu-plugin.php)

<?php
/*
Plugin Name: Meu Plugin Exemplo
Description: Adiciona funcionalidades personalizadas.
Version: 1.0
Author: Seu Nome
*/

5. Organização do Ambiente Local

Em desenvolvimento, mantenha cada projeto isolado. Use versionamento (Git) para rastrear mudanças e separar ambientes de teste e produção.

Estrutura sugerida

~/projetos/
└── estudos-wordpress/
    ├── public/            # Instalação do WordPress
    ├── database/          # Dumps SQL e backups
    ├── wp-debug.log       # Log local de erros
    ├── .git/              # Controle de versão
    └── docs/              # Documentação e anotações

Use o arquivo .gitignore para excluir pastas como wp-content/uploads e wp-config.php de commits. Evite expor credenciais.

6. Exemplo de .gitignore

.gitignore básico

# Ignorar arquivos sensíveis e temporários
wp-config.php
wp-content/uploads/
wp-content/cache/
debug.log
*.log
*.sql
node_modules/
vendor/
.env

7. Boas Práticas

Mantenha o core intacto. Atualize via painel oficial.
Desenvolva em tema filho. Evite sobrescrever diretamente o pai.
Organize assets (CSS/JS) em subpastas claras.
Adicione documentação curta em cada arquivo PHP explicando sua função.
Padronize nomes de arquivos e funções (snake_case).
Versione apenas o necessário. Evite commits de uploads ou bibliotecas externas.

Benefício Estrutura organizada reduz erros, facilita manutenção e acelera onboarding de novos devs.