---
title: PHP Sunucu SDK
---

# PHP Sunucu SDK

Resmi PHP sunucu tarafı SDK'sı — Packagist üzerinde [`captchala/captchala-php`](https://packagist.org/packages/captchala/captchala-php) olarak yayınlanmıştır.

SDK'nın sizin için üstlendiği üç iş:

1. **Validate** — tarayıcı SDK'sından gelen bir `pt_` pass token'ını doğrulayın.
2. **Issue** — gelecek challenge'ı belirli bir action / IP / UID'ye bağlamak için tek seferlik bir `sct_` server token'ı basın.
3. **Moderate** — panelin kullandığı OpenAI uyumlu pipeline ile çok modlu (metin + görüntü) içerik moderasyonu.

## Kurulum

```bash
composer require captchala/captchala-php
```

**PHP ≥ 8.0** ve `ext-json` gerektirir. cURL mevcutsa onu kullanır, aksi halde `file_get_contents`'a düşer.

## Doğrulama (`pt_` token)

Son kullanıcının IP'sini üçüncü argüman olarak geçirin (`CF-Connecting-IP` /
`X-Forwarded-For`'dan, `REMOTE_ADDR`'a düşerek). İsteğe bağlı ancak
**önerilir** — ek risk kontrolleri için kullanılır.

```php
use Captchala\Client;

$client = new Client('your_app_key', 'your_app_secret');
$result = $client->validate($_POST['captcha_token'], false, captchala_client_ip());

if (!$result->isValid()) {
    http_response_code(400);
    exit($result->getError());   // e.g. "token_expired"
}
// Verification passed; proceed with the request.
// $result->getCaptchaArgs() has platform / user_ip / referer / pkg / solved_at / risk_score

// Real end-user IP behind a CDN / proxy
function captchala_client_ip(): string {
    foreach (['HTTP_CF_CONNECTING_IP', 'HTTP_X_FORWARDED_FOR', 'HTTP_X_REAL_IP', 'REMOTE_ADDR'] as $h) {
        if (!empty($_SERVER[$h])) {
            $ip = trim(explode(',', $_SERVER[$h])[0]);
            if (filter_var($ip, FILTER_VALIDATE_IP)) return $ip;
        }
    }
    return '';
}
```

Elinizde IP yok mu? `$client->validate($_POST['captcha_token'])` kullanın — yine de
doğrulama yapar, sadece ek IP tabanlı risk sinyali olmadan.

Orijinal `server_token`'ı `bind_uid` ile düzenlediyseniz, döndürülen `uid` değerini gerçekten beklediğiniz kullanıcıyla karşılaştırın:

```php
if ($result->getUid() !== $expectedUserId) {
    http_response_code(400);
    exit('user mismatch');
}
```

## Sunucu token'ı düzenleme

Yüksek değerli akışlar (giriş, kayıt, ödeme) için önerilen desen şudur:
backend tek seferlik bir `sct_` token basar, tarayıcıya iletir, tarayıcı bunu
`serverToken` prop'u olarak geçirir. Her token tek kullanımlık, action kapsamlı
ve isteğe bağlı olarak düzenleme anında IP / UID'ye bağlıdır.

```php
$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // seconds; default 300
    maxUses:   5,           // SDK retry budget
    bindUid:   $user->id,   // pair with ValidateResult::getUid() on verify
);

if (!$issue->isOk()) {
    return ['error' => $issue->getError()];   // rate_limit_exceeded, invalid_action, ...
}

return ['server_token' => $issue->getToken()];  // hand to browser
```

## İçerik moderasyonu

Çok modlu — OpenAI uyumlu formatta metin ve görüntü URL'lerinin karışımını kabul eder:

```php
$result = $client->moderationCheck([
    ['type' => 'text', 'text' => $userComment],
    ['type' => 'image_url', 'image_url' => ['url' => $uploadedImageUrl]],
], userId: $user->id);

if (!$result->isOk()) {
    // request error: invalid_credentials, no_content, transport failure, ...
    return ['error' => $result->getError()];
}

if ($result->isFlagged()) {
    // upstream model flagged; inspect categories for the why
    if ($result->hasCategory('violence', 'csam')) {
        // hard block
    }
}
```

Düz metin kısayolu:

```php
$result = $client->moderationText('user comment here', userId: $user->id);
```

Kategoriler model tanımlıdır (örn. `violence`, `hate`, `sexual`, `self-harm`); sabit bir küme kodlamak yerine `getCategories()` üzerinde defansif olarak iterasyon yapın.

## Result sınıfları

| Sınıf | Yöntemler |
|---|---|
| `ValidateResult` | `isValid()`, `getError()`, `getUid()`, `getChallengeId()`, `getAction()`, `isOffline()`, `isClientOnly()`, `getWarning()`, `toArray()` |
| `IssueResult` | `isOk()`, `getToken()`, `getExpiresIn()`, `getIssuedAt()`, `getError()`, `getMessage()`, `toArray()` |
| `ModerationResult` | `isOk()`, `isFlagged()`, `hasCategory(...$names)`, `getCategories()`, `getContentType()`, `getRaw()`, `getError()`, `getMessage()`, `toArray()` |

## Bağlantılar

- [Packagist](https://packagist.org/packages/captchala/captchala-php) · [GitHub](https://github.com/Captcha-La/captchala-php)
- [Web SDK genel bakışı](/tr/web-sdk) · [API Referansı](/tr/api-reference)