O que é CORS e por que sua API PHP está bloqueando o front-end?

CORS (Cross-Origin Resource Sharing) é um mecanismo de segurança do navegador que bloqueia requisições entre domínios diferentes. Se você tem uma API em PHP e tenta consumi-la via fetch, AJAX ou JavaScript, provavelmente já viu o erro:

Access to fetch at 'https://api.exemplo.com' 
from origin 'https://site.com' has been blocked by CORS policy

Importante: o erro não é no PHP, nem no servidor. É o navegador protegendo o usuário.

---

Quando o erro de CORS acontece?

• Front-end em domínio diferente da API
• Uso de Authorization: Bearer
• Requisições PUT, DELETE ou PATCH
• Headers personalizados (X-Token, X-Requested-With)

Nesses casos o navegador faz uma requisição OPTIONS (preflight) antes da requisição real. Se a API não responder corretamente, tudo é bloqueado.

---

Configuração mínima de CORS em PHP (exemplo funcional)

Coloque este bloco no início do index.php da sua API, antes de qualquer saída:

<?php
header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type, Authorization");

Isso já resolve a maioria dos erros básicos de CORS.

---

Tratando corretamente o preflight (OPTIONS)

Se o navegador enviar OPTIONS e sua API não responder, a requisição real nunca acontece. Adicione:

<?php
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
  http_response_code(200);
  exit;
}

Isso evita erro 401/403 antes mesmo do front conseguir chamar a API.

---

Exemplo completo (recomendado)

<?php
header("Access-Control-Allow-Origin: https://seusite.com");
header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type, Authorization");
header("Access-Control-Allow-Credentials: true");

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
  http_response_code(200);
  exit;
}

🔐 Use domínio específico em produção, nunca * se usar credenciais.

---

CORS + Bearer Token (caso mais comum)

Se sua API usa autenticação Bearer:

Authorization: Bearer eyJhbGciOi...

Você precisa liberar explicitamente o header Authorization:

header("Access-Control-Allow-Headers: Content-Type, Authorization");

Sem isso, o navegador bloqueia antes do PHP validar o token. ---

CORS não substitui autenticação

CORS não protege sua API. Ele apenas controla quem pode chamá-la via navegador.

• ❌ Não use CORS como segurança
• ✅ Sempre valide token, sessão ou API key no backend

---

Checklist rápido de CORS em PHP

• [ ] Headers CORS enviados antes de qualquer output
• [ ] OPTIONS tratado corretamente
• [ ] Authorization liberado (se usar Bearer)
• [ ] Domínio específico em produção
• [ ] Autenticação validada no backend

---