Formulários em PHP: processar, validar e reexibir

Um formulário PHP envia de volta para o script que o imprimiu: escreva <form method="post"> com inputs que têm nome, e quando $_SERVER['REQUEST_METHOD'] for 'POST', leia cada campo como $_POST['name']. Escape tudo o que você imprimir de volta com htmlspecialchars().

Rode este bloco, digite um nome no formulário e clique em Send: o mesmo script roda de novo, desta vez com $_POST preenchido.

<?php
$name = '';
if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    $name = trim($_POST['name'] ?? '');
}
?>
<form method="post">
  <label>Your name <input name="name" value="<?= htmlspecialchars($name) ?>"></label>
  <button>Send</button>
</form>
<?php if ($name !== ''): ?>
  <p>Hello, <?= htmlspecialchars($name) ?>.</p>
<?php endif; ?>

Três coisas acontecem aqui que todo processador de formulário precisa:

• A verificação do método. Na primeira visita a requisição é um GET e não há nada a processar. O ?? 'GET' só importa quando o arquivo roda pela linha de comando, onde REQUEST_METHOD não está definido; num servidor web ele sempre está.
• ?? '' em cada campo. Um campo pode faltar (um input renomeado, uma requisição enviada por um script), e ler uma chave ausente imprime um aviso.
• Escapar na saída. O nome volta para a página duas vezes, e o htmlspecialchars() garante que um valor como <b>Ada</b> apareça como texto em vez de virar marcação. Os detalhes estão na página sobre htmlspecialchars.

Validar um formulário e mostrar erros ao lado dos campos

Reúna os erros num array com o nome do campo como chave. Se o array estiver vazio, o formulário é válido; senão, imprima o formulário de novo com cada mensagem embaixo do seu campo e a entrada do visitante ainda no lugar. Envie vazio, depois com um e-mail inválido, depois com valores válidos.

<?php
$values = ['name' => '', 'email' => '', 'age' => ''];
$errors = [];
$sent = false;

if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    foreach ($values as $field => $_) {
        $values[$field] = trim((string) ($_POST[$field] ?? ''));
    }

    if ($values['name'] === '') {
        $errors['name'] = 'Please enter your name.';
    } elseif (mb_strlen($values['name']) > 50) {
        $errors['name'] = 'Use 50 characters or fewer.';
    }

    if (filter_var($values['email'], FILTER_VALIDATE_EMAIL) === false) {
        $errors['email'] = 'That does not look like an email address.';
    }

    $age = filter_var($values['age'], FILTER_VALIDATE_INT, ['options' => ['min_range' => 13, 'max_range' => 120]]);
    if ($age === false) {
        $errors['age'] = 'Enter a whole number from 13 to 120.';
    }

    $sent = $errors === [];
}

function e(string $s): string
{
    return htmlspecialchars($s, ENT_QUOTES, 'UTF-8');
}
?>
<style>.err { color: #c62828; margin: 2px 0 10px; } label { display: block; margin-top: 8px; }</style>
<?php if ($sent): ?>
  <p>Thanks, <?= e($values['name']) ?>. We will write to <?= e($values['email']) ?>.</p>
<?php else: ?>
  <form method="post" novalidate>
    <label>Name <input name="name" value="<?= e($values['name']) ?>"></label>
    <?php if (isset($errors['name'])): ?><p class="err"><?= e($errors['name']) ?></p><?php endif; ?>

    <label>Email <input name="email" value="<?= e($values['email']) ?>"></label>
    <?php if (isset($errors['email'])): ?><p class="err"><?= e($errors['email']) ?></p><?php endif; ?>

    <label>Age <input name="age" value="<?= e($values['age']) ?>"></label>
    <?php if (isset($errors['age'])): ?><p class="err"><?= e($errors['age']) ?></p><?php endif; ?>

    <button>Sign up</button>
  </form>
<?php endif; ?>

O novalidate desliga as verificações do próprio navegador para você ver as do PHP funcionando. Num formulário real, mantenha as duas: a validação do navegador é uma conveniência para o visitante, a validação do PHP é a que vale, porque qualquer pessoa pode enviar uma requisição sem o seu formulário. O filter_var() faz o e-mail e o intervalo inteiro com uma chamada cada; a página sobre filter_var mostra os outros filtros dele.

Checkboxes, botões de opção e select

Um campo de texto sempre envia um valor, mesmo vazio. Os outros controles não:

• Um checkbox desmarcado não envia nada, então a chave dele não aparece em $_POST.
• Checkboxes com o nome topics[] chegam como array: $_POST['topics'] é ['php', 'sql'].
• Um grupo de botões de opção ou um <select> envia o value da opção escolhida.

Para manter a escolha depois do envio, imprima checked ou selected na opção que bate. Marque algumas caixas, escolha um nível e clique em Save.

<?php
$topics = ['php' => 'PHP', 'sql' => 'SQL', 'js' => 'JavaScript'];
$levels = ['new' => 'New to coding', 'some' => 'Some experience', 'pro' => 'Professional'];

$picked = $_POST['topics'] ?? [];
$picked = is_array($picked) ? array_values(array_intersect($picked, array_keys($topics))) : [];

$level = $_POST['level'] ?? 'new';
if (!is_string($level) || !array_key_exists($level, $levels)) {
    $level = 'new';
}
?>
<form method="post">
  <p>Topics:
  <?php foreach ($topics as $key => $label): ?>
    <label><input type="checkbox" name="topics[]" value="<?= $key ?>"
      <?= in_array($key, $picked, true) ? 'checked' : '' ?>> <?= $label ?></label>
  <?php endforeach; ?>
  </p>
  <p>Level:
    <select name="level">
    <?php foreach ($levels as $key => $label): ?>
      <option value="<?= $key ?>" <?= $key === $level ? 'selected' : '' ?>><?= $label ?></option>
    <?php endforeach; ?>
    </select>
  </p>
  <button>Save</button>
</form>
<p>You picked: <?= $picked ? implode(', ', array_map(fn ($k) => $topics[$k], $picked)) : 'nothing yet' ?>
  (<?= $levels[$level] ?>)</p>

As duas verificações depois de ler a entrada importam mais do que parece. O array_intersect() descarta qualquer tópico que não estava na sua lista, e a verificação com is_string() mais array_key_exists() volta o nível para um padrão se alguém enviar um valor que você nunca ofereceu (ou um array, que faria $levels[$level] lançar um erro). Um select limita o que um navegador pode enviar, não o que uma requisição pode conter.

Formulários em várias etapas com campos ocultos

Um input oculto leva um valor de uma etapa para a próxima sem mostrá-lo. Aqui a etapa 1 pede um nome, a etapa 2 pede uma linguagem e envia o nome junto num campo oculto, e a etapa 3 mostra os dois. Passe pelas três etapas.

<?php
$name = trim((string) ($_POST['name'] ?? ''));
$lang = (string) ($_POST['lang'] ?? '');
$step = $name === '' ? 1 : ($lang === '' ? 2 : 3);
$e = fn (string $s) => htmlspecialchars($s, ENT_QUOTES, 'UTF-8');
?>
<p>Step <?= $step ?> of 3</p>
<?php if ($step === 1): ?>
  <form method="post">
    <label>Name <input name="name"></label> <button>Next</button>
  </form>
<?php elseif ($step === 2): ?>
  <form method="post">
    <input type="hidden" name="name" value="<?= $e($name) ?>">
    <p>Hi <?= $e($name) ?>, which language do you want to learn?</p>
    <label><input type="radio" name="lang" value="PHP" checked> PHP</label>
    <label><input type="radio" name="lang" value="Python"> Python</label>
    <button>Next</button>
  </form>
<?php else: ?>
  <p><?= $e($name) ?> wants to learn <?= $e($lang) ?>.</p>
<?php endif; ?>

Campos ocultos aparecem no código-fonte da página e podem ser editados como qualquer outro campo, então servem para levar as próprias respostas do visitante entre as etapas, mas nunca um preço, um id de usuário ou um papel. Mantenha esses no servidor, numa sessão; veja sessões e cookies.

Post/Redirect/Get: evitar o reenvio ao atualizar

Depois de um POST bem-sucedido, se o script imprimir uma página de "obrigado" diretamente, apertar atualizar faz o navegador enviar o POST de novo, e o pedido ou comentário é salvo duas vezes. A correção é salvar, redirecionar e mostrar o resultado num GET:

<?php
session_start();

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $errors = validate($_POST);
    if (!$errors) {
        save_comment($_POST);
        $_SESSION['flash'] = 'Comment posted.';
        header('Location: /comments.php', true, 303);
        exit;
    }
    // On errors, fall through and print the form with the messages.
}

$flash = $_SESSION['flash'] ?? null;
unset($_SESSION['flash']);

303 See Other diz ao navegador para seguir o redirecionamento com um GET. O exit depois do header() importa: sem ele o resto do script continua rodando. O redirecionamento também precisa acontecer antes de qualquer saída, senão o PHP se recusa com "headers already sent".

Formulários reais também adicionam um token CSRF: um valor aleatório guardado na sessão e num campo oculto, comparado com hash_equals() no envio, para que outro site não consiga enviar o seu formulário em nome de um visitante logado.

Testar a validação sem navegador

Coloque as regras numa função que recebe um array e retorna os erros. A página a chama com $_POST, e você pode chamá-la com o array que quiser, o que facilita testar os casos extremos. Adicione os seus próprios casos à lista.

<?php
function validateSignup(array $input): array
{
    $errors = [];
    $name = $input['name'] ?? '';
    $email = $input['email'] ?? '';

    if (!is_string($name) || trim($name) === '') {
        $errors['name'] = 'required';
    }
    if (!is_string($email) || filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
        $errors['email'] = 'invalid';
    }
    return $errors;
}

$cases = [
    ['name' => 'Ada', 'email' => 'ada@example.com'],
    ['name' => '   ', 'email' => 'ada@example.com'],
    ['name' => 'Ada', 'email' => 'ada@'],
    ['name' => ['x'], 'email' => 'ada@example.com'],
    [],
];

foreach ($cases as $case) {
    echo json_encode($case), ' => ', json_encode(validateSignup($case)), "\n";
}

O quarto caso é o que as pessoas esquecem. Uma requisição pode enviar name[]=x, o que torna $_POST['name'] um array, e passar um array para o trim() lança um TypeError e para o script. Verificar is_string() antes transforma uma entrada hostil num erro de validação comum. O cast (string) dos blocos anteriores também evita o TypeError, mas transforma o array na palavra Array e imprime um aviso, então is_string() é a verificação mais limpa.

Erro comum: ler $_POST antes de o formulário ser enviado

O primeiro script de formulário mais comum lê os campos no topo do arquivo:

<?php
$name = $_POST['name'];
echo "Hello, $name";

Na primeira visita nada foi enviado, então o PHP imprime:

Warning: Undefined array key "name" in /var/www/form.php on line 2

A correção é o padrão do primeiro bloco: processe o formulário só quando a requisição for um POST, e leia cada campo com um padrão, $_POST['name'] ?? ''. Se o aviso aparecer depois do envio, compare o atributo name no HTML com a chave no PHP: name="Name" e $_POST['name'] são chaves diferentes.