Captcha Modülü Yazma

coremio/modules/Captcha/Acme/
├── Acme.php        Acme sınıfı, ad alanı yok
├── config.php      kaydedilmiş anahtarları döndürür, örn. site-key ve secret-key
└── lang/
    ├── en.php      hata metinleri ve işaretlemenizin bastığı buton etiketleri
    └── tr.php

public function __construct();

// Karar. Durum dizisi değil bir bool: yardımcı onu doğrudan çağırana döndürür.
public function check(): bool;

// Bileşen parçası. Form etiketi yok, sarmalayıcı yok: yuvayı yardımcı sağlar.
public function getMarkup(): string;

// İstek başına sağlayıcı başına bir kez, yuvanın üstünde basılır.
public function headJS(): string;

// Fonksiyon değil bir ifade: yardımcı onu window.wcpCaptchaRefresh içine sarar.
public function refreshJS(): string;

// Yalnız kod sağlayıcıları. VARLIĞI yuvayı kod kipine geçirir.
public function getInputName(): string;

// Yalnız kod sağlayıcıları. Görseli kendisi yazar ve '' döndürür.
public function generateDisplay(): string;

// Ayar ekranı.
public function config_fields(): array;
public function save_fields($fields = []): array|bool;

// config_fields(): dizi anahtarı config anahtarının TA KENDİSİDİR. Burada ne ad verirseniz
// save_fields() metoduna o gelir ve $this->config içinden onu geri okursunuz.
public function config_fields(): array
{
    return [
        'site-key' => [
            'wrap_width'  => 100,        // alan satırının yüzde olarak genişliği
            'name'        => "Site Key", // etiket
            'description' => "",         // alanın altındaki yardım metni
            'type'        => "text",     // text | password | select | switch
            'value'       => $this->config['site-key'] ?? '',
        ],
        'secret-key' => [
            'wrap_width'  => 100,
            'name'        => "Secret Key",
            'description' => "",
            'type'        => "password",
            'value'       => $this->config['secret-key'] ?? '',
        ],
    ];
}

// save_fields(): doğrulayın, sonra saklanacak diziyi döndürün. Dosyayı ÇAĞIRAN yazar.
public function save_fields($fields = []): array|bool
{
    if (!isset($fields['site-key']) || !$fields['secret-key']) {
        $this->error = $this->lang['error1'];
        return false;
    }

    return $this->config ? array_replace_recursive($this->config, $fields) : $fields;
}

<?php
class Acme
{
    public array $lang;
    public array $config;

    // save_fields() false döndürdükten sonra ayar kaydetme tarafından okunur.
    public string $error = '';

    public function __construct()
    {
        $config       = Modules::Config("Captcha", __CLASS__);
        $this->config = is_array($config) ? $config : [];
        $this->lang   = Modules::Lang("Captcha", __CLASS__);
    }

    public function config_fields(): array
    {
        return [
            'site-key' => [
                'wrap_width'  => 100,
                'name'        => "Site Key",
                'description' => "",
                'type'        => "text",
                'value'       => $this->config['site-key'] ?? '',
            ],
            'secret-key' => [
                'wrap_width'  => 100,
                'name'        => "Secret Key",
                'description' => "",
                'type'        => "password",
                'value'       => $this->config['secret-key'] ?? '',
            ],
        ];
    }

    public function save_fields($fields = []): array|bool
    {
        if (!isset($fields['site-key']) || !$fields['secret-key']) {
            $this->error = $this->lang['error1'] ?? 'Both keys are required.';
            return false;
        }

        return $this->config ? array_replace_recursive($this->config, $fields) : $fields;
    }

    // Bir parça. Yuva sarmalayıcısını ve boşluk yardımcılarını yardımcı ekler.
    public function getMarkup(): string
    {
        return '<div class="acme-captcha" data-sitekey="' . htmlspecialchars($this->config['site-key'] ?? '', ENT_QUOTES) . '" data-theme="auto"></div>';
    }

    public function headJS(): string
    {
        return '<script src="https://challenges.example.com/v1/api.js" async defer></script>';
    }

    // Fonksiyon gövdesi değil bir ifade: yardımcı onu window.wcpCaptchaRefresh içine sarar.
    public function refreshJS(): string
    {
        return 'if (typeof acmeCaptcha !== "undefined") acmeCaptcha.reset();';
    }

    public function check(): bool
    {
        // POST alanını sağlayıcı kendi adlandırır, bu yüzden burası kod ailesinin bildirdiği
        // girdi adı üzerinden değil doğrudan okunur.
        $token = (string) Filter::init("POST/acme-captcha-response", "hclear");
        if ($token === '') return false;

        $response = Utility::HttpRequest([
            'url'  => 'https://challenges.example.com/v1/siteverify',
            'type' => 'POST',
            'data' => [
                'secret'   => $this->config['secret-key'] ?? '',
                'response' => $token,
                'remoteip' => UserManager::GetIP(),
            ],
        ]);

        $decoded = Utility::jdecode((string) $response, true) ?: [];

        // Bir bool, başka bir şey değil. Taşıma hatası bir istisna değil başarısız bir sorudur:
        // burada fırlatmak, ulaşılamayan bir sağlayıcıyı bozuk bir giriş formuna çevirir.
        return (bool) ($decoded['success'] ?? false);
    }
}

<form action="{link route='domain'}" method="post" data-check>
    <input type="text" name="domain" class="form-control">

    {csrf form='domain-check'}
    {captcha area='domain-check' tray='domainCaptchaTray'}

    <button type="submit" class="btn btn-primary">{lang key='search'}</button>
</form>

// Sıra önemlidir: sahtecilik denetimi, sonra sert engel, sonra soru.
if (!\Validation::verify_csrf_token((string) Filter::init("POST/token", "hclear"), "domain-check"))
    return $operation->output(['status' => "error", 'message' => Language::g("needs/csrf-failed")]);

if (\ProcessRestriction::blocked("domain-check"))
    return $operation->output(['status' => "error", 'message' => Language::g("needs/too-many-requests")]);

// Sormak için iki bağımsız sebep: operatör alanı açtı ya da bu ziyaretçi
// kalkanı tetikledi. İkisinden biri cevabı zorunlu kılar.
$needCaptcha = \Captcha::enabled("domain-check") || \BotShield::triggered("domain-check");

if ($needCaptcha && !(new \Captcha())->check()) {
    \BotShield::record("domain-check");

    // Genel bir hata değil ayırt edici bir durum: form JS'i bunda tepsiyi açar.
    return $operation->output([
        'status'  => "captcha_required",
        'message' => Language::g("needs/captcha-failed"),
    ]);
}

// ... asıl sorgu ...

\ProcessRestriction::hit("domain-check");
if ($needCaptcha) \BotShield::clear("domain-check");
else              \BotShield::record("domain-check");