---
title: PHP Server SDK
---

# PHP Server SDK

SDK sisi server PHP resmi — diterbitkan sebagai [`captchala/captchala-php`](https://packagist.org/packages/captchala/captchala-php) di Packagist.

Tiga tugas yang ditangani SDK ini untuk Anda:

1. **Validate** — memverifikasi pass token `pt_` dari browser SDK.
2. **Issue** — mencetak server token `sct_` sekali pakai untuk mengikat tantangan berikutnya ke aksi / IP / UID tertentu.
3. **Moderate** — moderasi konten multi-modal (teks + gambar) terhadap pipeline yang kompatibel dengan OpenAI, sama seperti yang dipakai dashboard.

## Pasang

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

Membutuhkan **PHP ≥ 8.0** dengan `ext-json`. Memakai cURL bila tersedia, jatuh kembali ke `file_get_contents`.

## Validate (token `pt_`)

Kirim IP pengguna akhir sebagai argumen ketiga (dari `CF-Connecting-IP` /
`X-Forwarded-For`, jatuh kembali ke `REMOTE_ADDR`). Opsional, tetapi
**disarankan** — dipakai untuk pemeriksaan risiko tambahan.

```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 '';
}
```

Tidak ada IP di tangan? Gunakan `$client->validate($_POST['captcha_token'])` — tetap
melakukan verifikasi, hanya tanpa sinyal risiko tambahan berbasis IP.

Jika `server_token` awal diterbitkan dengan `bind_uid`, bandingkan `uid` yang dikembalikan dengan pengguna yang sebenarnya Anda harapkan:

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

## Menerbitkan server token

Untuk alur bernilai tinggi (login, registrasi, pembayaran) pola yang disarankan adalah: backend mencetak token `sct_` sekali pakai, mengirimkannya ke peramban, peramban meneruskannya sebagai prop `serverToken`. Setiap token sekali pakai, terikat aksi, dan opsional terikat IP / UID saat diterbitkan.

```php
$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // detik; default 300
    maxUses:   5,           // anggaran retry SDK
    bindUid:   $user->id,   // dipasangkan dengan ValidateResult::getUid() saat verifikasi
);

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

return ['server_token' => $issue->getToken()];  // kirim ke peramban
```

## Moderasi konten

Multi-modal — menerima campuran URL teks dan gambar dalam format kompatibel OpenAI:

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

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

if ($result->isFlagged()) {
    // model di hulu menandai; periksa kategori untuk alasannya
    if ($result->hasCategory('violence', 'csam')) {
        // blokir keras
    }
}
```

Pintasan teks polos:

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

Kategori ditentukan oleh model (mis. `violence`, `hate`, `sexual`, `self-harm`); iterasikan `getCategories()` secara defensif daripada meng-hardcode himpunan tetap.

## Kelas hasil

| Kelas | Method |
|---|---|
| `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()` |

## Tautan

- [Packagist](https://packagist.org/packages/captchala/captchala-php) · [GitHub](https://github.com/Captcha-La/captchala-php)
- [Ikhtisar Web SDK](/id/web-sdk) · [Referensi API](/id/api-reference)