Boas práticas essenciais em PHP moderno (para sair do código bagunçado)

Por /

Muita gente aprende PHP “na marra”: copia código de fórum, junta com HTML, joga tudo em um arquivo só e, quando vê, o sistema virou uma mistura impossível de entender.

O problema é que esse tipo de código:

  • é difícil de manter
  • quebra com qualquer mudança
  • dá vergonha de mostrar pra outro programador 😅

Se você quer trabalhar com PHP moderno, precisa ir além de “apenas funcionar” e começar a se preocupar com boas práticas.

Neste artigo, vou te mostrar práticas simples e diretas para sair do código bagunçado e começar a escrever PHP com cara de profissional.

1. Pare de jogar tudo em um arquivo só

Código assim é clássico:

<?php
// conexao banco
$con = mysqli_connect('localhost', 'root', '', 'meubanco');

// pega dados do formulário
$nome = $_POST['nome'];
$email = $_POST['email'];

// valida
if (empty($nome) || empty($email)) {
    die("Preencha todos os campos");
}

// salva no banco
mysqli_query($con, "INSERT INTO usuarios (nome, email) VALUES ('$nome', '$email')");

echo "Ok";

Tudo misturado: conexão, validação, regra de negócio e saída.

No PHP moderno, a ideia é separar responsabilidades:

  • Uma parte cuida de conexão
  • Outra parte cuida de lógica
  • Outra cuida da camada web (request/response)

Isso começa com algo simples: organizar arquivos e pastas.

2. Organize o projeto em pastas claras

Uma estrutura mínima (que já é muito melhor que jogar tudo na raiz) seria algo como:

meu-projeto/
  public/
    index.php
  src/
    Controller/
    Model/
    Service/
  config/
    database.php
  vendor/
  composer.json
  • public/ → ponto de entrada da aplicação (o que o navegador enxergar)
  • src/ → seu código principal (classes de controller, model, service)
  • config/ → arquivos de configuração
  • vendor/ → dependências do Composer

Essa organização já te força a parar de misturar tudo.

3. Use nomes claros para variáveis e funções

Evite coisas como:

$a = $_POST['nm'];
$b = $_POST['em'];

function x($a, $b) {
    // ...
}

Isso pode “funcionar”, mas daqui a 1 semana nem você vai lembrar o que é $a, $b, nm e em.

Prefira:

$nome = $_POST['nome'] ?? '';
$email = $_POST['email'] ?? '';

function cadastrarUsuario(string $nome, string $email): void
{
    // ...
}

Repare:

  • os nomes explicam o que são
  • a função diz exatamente o que faz: cadastrarUsuario
  • fica muito mais fácil de ler e manter

Se o nome não estiver óbvio, provavelmente ele está ruim.

4. Use tipagem (parâmetros e retorno)

PHP moderno permite e incentiva o uso de tipos. Em vez de:

function somar($a, $b) {
    return $a + $b;
}

Use:

function somar(int $a, int $b): int
{
    return $a + $b;
}

Benefícios:

  • se você acidentalmente passar uma string, o PHP avisa
  • o editor/IDE consegue te ajudar melhor
  • você deixa claro para outros devs como a função deve ser usada

Também vale para objetos:

function enviarEmail(Usuario $usuario, string $assunto, string $mensagem): void
{
    // ...
}

E para retornos que podem ser nulos:

function buscarUsuarioPorId(int $id): ?Usuario
{
    // retorna Usuario ou null
}

5. Separe regras de negócio da parte de acesso ao banco

Um erro comum é encher o código de mysqli_query ou PDO->query espalhado por tudo.

Em vez disso, crie uma camada de repositório ou model:

// src/Repository/UsuarioRepository.php
namespace App\Repository;

use PDO;

class UsuarioRepository
{
    public function __construct(private PDO $conexao)
    {
    }

    public function inserir(string $nome, string $email): bool
    {
        $sql = "INSERT INTO usuarios (nome, email) VALUES (:nome, :email)";
        $stmt = $this->conexao->prepare($sql);
        return $stmt->execute([
            ':nome' => $nome,
            ':email' => $email,
        ]);
    }
}

E na parte que cuida do fluxo da aplicação:

$repositorio = new UsuarioRepository($pdo);
$repositorio->inserir($nome, $email);

Assim:

  • se um dia você trocar MySQL por outro banco, muda só a camada de repositório
  • o resto da aplicação continua igual

6. Funções e métodos pequenos, com uma única responsabilidade

Se você tem funções de 200 linhas, algo está errado.

Prefira funções pequenas, com uma responsabilidade bem definida. Exemplo ruim:

function processarCadastro()
{
    // pega $_POST
    // valida os campos
    // conecta no banco
    // insere no banco
    // envia e-mail
    // devolve HTML na tela
}

Em vez disso, pense em quebrar:

function validarDados(array $dados): array
{
    // valida e retorna array de erros ou dados filtrados
}

function salvarUsuarioNoBanco(PDO $conexao, array $dados): bool
{
    // insere
}

function enviarEmailDeBoasVindas(string $email): void
{
    // envia
}

E a função “principal” apenas orquestra:

$erros = validarDados($_POST);

if (!empty($erros)) {
    // exibe erros
} else {
    salvarUsuarioNoBanco($pdo, $_POST);
    enviarEmailDeBoasVindas($_POST['email']);
}

Isso é muito mais legível e fácil de testar.

7. Use Exceptions para tratar erros, não die() ou echo direto

Em código antigo é comum ver:

if (!$conexao) {
    die("Erro na conexão");
}

No PHP moderno, faz mais sentido lançar exceptions e deixar uma camada mais alta decidir o que fazer:

if (!$conexao) {
    throw new RuntimeException("Erro na conexão com o banco de dados.");
}

E em um ponto central da sua aplicação (por exemplo, no index.php), você trata:

try {
    // código da aplicação
} catch (Throwable $e) {
    // registrar log
    // mostrar uma página de erro amigável
    http_response_code(500);
    echo "Ocorreu um erro interno. Tente novamente mais tarde.";
}

Isso evita que mensagens de erro técnicas apareçam para o usuário final.

8. Evite misturar PHP com HTML demais (especialmente lógica complexa)

Não tem problema usar PHP dentro de HTML em views simples, mas evite colocar lógica pesada.

Exemplo aceitável em uma view:

<h1>Lista de usuários</h1>

<ul>
    <?php foreach ($usuarios as $usuario): ?>
        <li><?= htmlspecialchars($usuario->getNome()) ?></li>
    <?php endforeach; ?>
</ul>

Exemplo ruim:

<h1>Lista de usuários</h1>

<ul>
    <?php
    $con = new PDO(...);
    $stmt = $con->query("SELECT * FROM usuarios");
    while ($row = $stmt->fetch()) {
        if ($row['ativo'] == 1 && $row['tipo'] != 'admin' && $row['data'] > '2020-01-01') {
            echo "<li>" . $row['nome'] . "</li>";
        }
    }
    ?>
</ul>

A parte de banco de dados e regras não deveria estar dentro do HTML.
Faça isso antes, em outra camada, e passe só os dados prontos pra view.

9. Padronize seu código com PSR e tools automáticas

No PHP moderno, existem recomendações chamadas PSR (PHP Standards Recommendations).

Duas das mais usadas são:

  • PSR-1: padrão básico de código
  • PSR-12: padrão de estilo (espaços, chaves, indentação etc.)

Você não precisa decorar tudo, mas é importante:

  • sempre usar mesmo padrão em todo o projeto
  • não misturar estilos diferentes

Ferramentas que ajudam:

  • php-cs-fixer
  • PHP_CodeSniffer

Você pode rodar um comando e o próprio tool formata o código pra seguir o padrão.
Isso deixa tudo uniforme e facilita trabalhar em equipe.

10. Comentários: use com propósito, não pra explicar óbvio

Comentário bom:

// Calcula o valor total com desconto progressivo por quantidade
public function calcularTotalComDesconto(int $quantidade, float $precoUnitario): float
{
    // ...
}

Comentário inútil:

// Soma dois números
function somar($a, $b) {
    return $a + $b;
}

A regra é simples:

Comentário deve explicar o porquê, e não só repetir o que o código já mostra.

Se o nome da função e variáveis forem claros, muitos comentários se tornam desnecessários.

Conclusão: boas práticas = código que você não tem vergonha de abrir

Boas práticas em PHP moderno não são “teoria chata”. São coisas que:

  • evitam bugs bobos
  • tornam seu código mais fácil de manter
  • deixam seu projeto com cara de profissional
  • facilitam trabalhar com frameworks e projetos maiores

Recapitulando os pontos principais:

  1. Organize o projeto em pastas (src/, public/, config/…)
  2. Use nomes claros para variáveis, funções e classes
  3. Use tipagem em parâmetros e retornos
  4. Separe acesso a banco de regras de negócio
  5. Faça funções pequenas, com responsabilidade única
  6. Use exceptions e trate erros em um ponto central
  7. Evite misturar lógica pesada com HTML
  8. Padronize com PSR e ferramentas automáticas
  9. Use comentários com propósito

Comece aplicando essas práticas aos poucos no que você já faz.
Daqui a alguns meses, você vai olhar pro seu código novo e pensar:

“Ainda bem que eu parei com aquele PHP todo bagunçado.”

E nos próximos artigos de Programação PHP aqui no blog, dá pra entrar em:

  • organização por camadas (Controller, Service, Repository)
  • boas práticas específicas com PDO
  • pequenos padrões de projeto que já ajudam muito em sistemas reais.

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Rolar para cima