QR Code em PHP que a pessoa aponta a câmera sem medo: o que codificar e como gerar

A cantina imprimiu 40 displays de mesa com um QR Code para o cardápio. Na primeira semana, metade das mesas pede o cardápio de papel. Quem aponta a câmera vê um endereço encurtado de um serviço que ninguém conhece, cheio de letras aleatórias, e desiste. Três meses depois, o site muda de plataforma, o caminho do cardápio muda e os 40 displays passam a abrir uma página de erro. A resposta curta: codifique uma URL https curta do seu próprio domínio, que você controla e que pode redirecionar quando o destino mudar; escreva esse mesmo endereço em texto ao lado do código; e gere a imagem uma vez, no seu servidor, em vez de chamar um serviço externo a cada visualização.

O QR Code não tem nada de mágico: ele guarda um texto, quase sempre uma URL. Toda a confiança vem de a pessoa conseguir ver e reconhecer esse texto antes de abrir.

Por que as pessoas hesitam diante de um QR Code

Um link na tela mostra o endereço ao passar o mouse. Um QR Code impresso não mostra nada: é um salto às cegas até a câmera exibir a prévia. Golpistas sabem disso e colam adesivos com códigos falsos sobre os verdadeiros, em parquímetros, cardápios e boletos. Quem já ouviu falar desses golpes aprende a ler o endereço antes de tocar, e foge de domínio desconhecido.

Encurtadores de terceiros pioram o quadro de duas formas. Escondem o destino real atrás de um domínio genérico, que é justamente o padrão usado em golpe. E criam uma dependência: se o serviço sair do ar, mudar de regra ou apagar links antigos, o seu impresso morre junto, e você não tem como consertar papel já distribuído.

Há também um limite físico. Quanto mais texto, mais módulos (os quadradinhos) o código precisa, e mais denso ele fica. Código denso exige impressão mais nítida, mais luz e câmera mais próxima. Uma URL de 150 caracteres cheia de parâmetros de rastreamento gera um código bem mais difícil de ler num display de mesa amassado do que uma URL de 30.

O que nunca vai dentro do QR Code

Tudo que está no código é público para qualquer pessoa que apontar a câmera ou fotografar o papel. Não coloque token de sessão, link de redefinição de senha, CPF, número de pedido com dados pessoais na URL, nem chave de acesso. Se o código precisa identificar algo privado, ele aponta para uma página que pede login.

Como escolher a URL que vai no código

1. Use o seu domínio, com https, e não um encurtador de terceiros.
2. Crie um caminho curto e estável só para impressos, como /q/cardapio.
3. Faça esse caminho redirecionar para a página real. Se o destino é definitivo, 301; se você pretende trocar o destino de tempos em tempos, 302, que o navegador não guarda.
4. Deixe parâmetros de campanha no redirecionamento, do lado do servidor, e não dentro do código.
5. Escreva o endereço curto em texto, legível, ao lado do código.

No caso da cantina, o display traz o código e, embaixo, a linha "cantinarua7.com.br/q/cardapio". Quem não quer usar a câmera digita; quem usa vê na prévia o mesmo domínio que está impresso e no letreiro da porta. Quando o site mudar de plataforma, só a regra de redirecionamento muda. O guia de redirecionar URL do jeito certo explica a diferença entre 301 e 302 e como testar.

# nginx: caminho curto para impressos
location = /q/cardapio {
    return 302 https://cantinarua7.com.br/cardapio?utm_source=mesa;
}

Como gerar o QR Code no servidor com PHP

Há bibliotecas PHP para gerar QR Code instaláveis pelo Composer, e elas servem bem. Para um código que nasce na publicação e vai para a gráfica, uma opção simples é a ferramenta de linha de comando qrencode, disponível nos repositórios das distribuições Linux comuns, chamada por um script PHP rodado no terminal.

# Debian e Ubuntu
sudo apt install qrencode zbar-tools

<?php
// gerar-qr.php: rodar na publicação, pela linha de comando
function gerarQr(string $url, string $destino, string $tipo = 'SVG'): void
{
    if (!str_starts_with($url, 'https://')) {
        throw new InvalidArgumentException('Use a URL https do seu domínio');
    }
    $cmd = sprintf(
        'qrencode -t %s -l M -m 4 -o %s %s',
        escapeshellarg($tipo),
        escapeshellarg($destino),
        escapeshellarg($url)
    );
    exec($cmd, $saida, $codigo);
    if ($codigo !== 0) {
        throw new RuntimeException('qrencode falhou');
    }
}

$url = 'https://cantinarua7.com.br/q/cardapio';
gerarQr($url, __DIR__ . '/qr/cardapio.svg');
gerarQr($url, __DIR__ . '/qr/cardapio.png', 'PNG');

As opções usadas: -t escolhe o formato de saída, -l M define o nível médio de correção de erro, -m 4 deixa a margem branca de quatro módulos ao redor e -o indica o arquivo. O escapeshellarg em cada argumento impede que um caractere da URL seja interpretado pelo shell.

O SVG vai para a gráfica, porque é vetorial e não serrilha ao ampliar. O PNG serve para a página e para o teste. A correção de erro existe para o código continuar legível com parte danificada ou suja; níveis mais altos aguentam mais estrago, mas deixam o código mais denso. Para uma URL curta, o nível médio costuma ser um bom equilíbrio.

Gerar uma vez e guardar tem outra vantagem além de desempenho: você não manda a URL do seu cliente, a cada visualização, para o servidor de outra empresa que monta a imagem.

Como testar antes de mandar imprimir

1. Decodifique o arquivo gerado no próprio servidor e confira o texto.
2. Imprima uma prova no tamanho final, no papel final.
3. Teste com dois ou três celulares diferentes, inclusive um mais antigo, na luz do local.
4. Confira se a prévia da câmera mostra o domínio que está escrito no papel.
5. Abra o link e confirme que o redirecionamento chega na página certa, com https.

$ zbarimg -q qr/cardapio.png
QR-Code:https://cantinarua7.com.br/q/cardapio

Respeite a margem branca ao montar a arte: logotipo, borda decorativa ou fundo colorido encostado no código atrapalham a leitura. Contraste também conta: módulos escuros em fundo claro são o que todo leitor espera. Código claro sobre fundo escuro, ou cinza sobre bege, falha em parte das câmeras.

Erros comuns

• Usar encurtador de terceiros no impresso. O endereço parece golpe, e se o serviço sumir, todos os impressos param de funcionar.
• Codificar a URL final e longa da página. O código fica denso, difícil de ler, e qualquer mudança de caminho no site quebra o papel.
• Não escrever o endereço em texto ao lado. Quem desconfia da câmera ou está com o celular sem leitor fica sem alternativa.
• Colocar dado pessoal ou token na URL do código. Qualquer pessoa que fotografar o papel tem acesso.
• Gerar a imagem num serviço externo a cada visualização. A página depende de outra empresa para carregar, e cada URL vai para fora.
• Apertar a margem ou enfeitar o código sem testar. Parte dos celulares deixa de ler, e você só descobre depois da tiragem.

Checklist

• A URL no código é https e do seu domínio.
• O caminho é curto e reservado para impressos.
• Existe uma regra de redirecionamento que você controla.
• O endereço está escrito em texto ao lado do código.
• Nenhum dado pessoal ou token está na URL.
• O arquivo foi decodificado e conferido antes de imprimir.
• Uma prova no tamanho real foi lida por mais de um celular.
• A margem branca ao redor do código está preservada na arte.

Se o código aponta para uma página com várias versões de URL, defina qual é a principal, como no guia de canonical da página certa. Pegue agora um impresso seu com QR Code e aponte a câmera: o domínio que aparece na prévia é o mesmo que está escrito no papel?