Cloudflare Turnstile PHP Formuna Nasıl Eklenir?

Bu örnek PHP 8.1+ ve cURL uzantısıyla token doğrulamasını gösterir. Gerçek formunuzda CSRF ve alan doğrulamasından sonra, e-posta/veritabanı işlemlerinden önce çalıştırın. Ortam değişkenine Turnstile secret'ını tanımlayın.

1. HTML widget

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<div class="cf-turnstile" data-sitekey="SITE_KEY_BURAYA" data-action="contact"></div>

Widget formun içinde olmalıdır. Form method POST olmalı ve token alanını sunucuya göndermelidir. Site key ile secret key'yi karıştırmayın.

2. PHP doğrulama katmanı

Aşağıdaki dosyada example.com değerini widget'ın izinli hostname'iyle değiştirin. Bu kod form göndermez; yalnız doğrulama sonucunu döndürür.

<?php
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
function fail(int $status): never {
    http_response_code($status);
    echo json_encode(['ok' => false]);
    exit;
}
if ($_SERVER['REQUEST_METHOD'] !== 'POST') { fail(405); }
$token = $_POST['cf-turnstile-response'] ?? null;
$secret = getenv('TURNSTILE_SECRET');
if (!is_string($token) || $token === '' || strlen($token) > 2048) { fail(400); }
if (!is_string($secret) || $secret === '') { fail(503); }
$ch = curl_init('https://challenges.cloudflare.com/turnstile/v0/siteverify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query(['secret' => $secret, 'response' => $token]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 8,
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($raw === false || $status !== 200) { fail(503); }
$result = json_decode($raw, true);
if (!is_array($result) || ($result['success'] ?? false) !== true
    || ($result['hostname'] ?? '') !== 'example.com'
    || ($result['action'] ?? '') !== 'contact') { fail(403); }
echo json_encode(['ok' => true]);

TLS doğrulaması varsayılan olarak açıktır; kapatmayın. Secret'ı hata çıktısına yazmayın. Örnekte IP doğrulama alanı gönderilmez; yanlış/güvensiz proxy başlığından IP türetmekten kaçınılır.

3. Test ve entegrasyon

php -l dosya.php ile sözdizimini kontrol edin. Resmi test anahtarlarıyla başarılı/başarısız token yollarını sınayın; test cevabının hostname/action değerleri test kurulumuna göre ele alınmalıdır. Üretimde gerçek hostname/action kontrolünü kaldırmayın. Eksik token POST'u 400, başarısız doğrulama 403, servis sorunu 503 vermelidir. Başarılı yanıtı gerçek form işleminize bağlarken sunucu tarafında rate limit, CSRF ve alan sınırlarını koruyun; tarayıcıdaki ok değerine güvenerek ayrı bir korunmasız endpoint'e yazmayın.