PHP integration for Cloak4U

The PHP integration runs Cloak4U’s invalid-traffic check on your server before the page renders. You paste one snippet at the top of your entry file; it collects minimal signals, asks Cloak4U for a decision, and blocks only when the service returns an explicit block. If anything goes wrong, it fails open so real visitors always reach your normal page.

How the PHP integration works

On each request, the snippet gathers a handful of non-sensitive request signals, sends them to the Cloak4U decision endpoint, and reads back one of a few outcomes — typically allow, block, or challenge. Because the check runs server-side before output starts, invalid traffic can be stopped before your page does any work. Valid visitors never notice it.

The important design choice is that the snippet defaults to allow and only blocks on an explicit block decision. This keeps your site resilient: a slow or unreachable service can never lock out your real audience.

Before you start

• PHP 7.4 or newer with the cURL extension enabled.
• A Cloak4U campaign and its token from the dashboard.
• Write access to the entry file that renders your landing page.
• A place to store your token securely — an environment variable or a config file outside the web root.

Replace demo_tok_XXXXXXXX with a token supplied via the CLOAK4U_TOKEN environment variable, and replace YOUR_APP_DOMAIN with your Cloak4U app domain. Never commit a real token to a public repository or a world-readable file.

The PHP snippet

Paste this at the very top of your entry file, before any HTML or whitespace is output. It is a safe placeholder — review it and adapt the endpoint and token handling to your environment.

<?php
// --- Cloak4U traffic-quality check (paste at the very top of your entry file) ---
// Reads a token from the environment; falls back to a safe placeholder.
// NEVER hard-code a real token in a public file. Store secrets outside the web root.
$cloak4u_token = getenv('CLOAK4U_TOKEN') ?: 'demo_tok_XXXXXXXX';
$cloak4u_endpoint = 'https://YOUR_APP_DOMAIN/api/v1/decide';

// Collect only minimal, non-sensitive request signals.
$payload = json_encode([
    'ip'        => $_SERVER['REMOTE_ADDR']       ?? '',
    'ua'        => $_SERVER['HTTP_USER_AGENT']   ?? '',
    'referer'   => $_SERVER['HTTP_REFERER']      ?? '',
    'path'      => $_SERVER['REQUEST_URI']       ?? '',
    'language'  => $_SERVER['HTTP_ACCEPT_LANGUAGE'] ?? '',
]);

$decision = 'allow'; // Default to allow — we fail OPEN.

$ch = curl_init($cloak4u_endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 2,   // fail fast
    CURLOPT_TIMEOUT        => 2,   // 2-second hard cap
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $cloak4u_token,
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Only act on a successful, well-formed response. Anything else fails open.
if ($response !== false && $status === 200) {
    $data = json_decode($response, true);
    if (is_array($data) && isset($data['decision'])) {
        $decision = $data['decision'];
    }
}

// Block ONLY on an explicit 'block' decision. Everyone else continues normally.
if ($decision === 'block') {
    http_response_code(403);
    header('Cache-Control: no-store');
    echo 'Access blocked.';
    exit;
}
// --- End Cloak4U check. Your normal page renders below. ---
?>

What the snippet does

• Reads the token from the environment and falls back to a placeholder, so no secret is hard-coded.
• Collects minimal signals only — IP, user agent, referrer, path, and language. It does not start a session, set cookies, or touch passwords or uploaded files.
• Uses a 2-second timeout on both connect and total request, so a slow service cannot hang your page.
• Fails open — the decision defaults to allow, and only a successful HTTP 200 with a valid decision field can change it.
• Blocks only on block — it returns a plain 403 with no-store and stops. Every other outcome continues to your normal page.

Secure file permissions

Keep your files locked down so tokens and code cannot be read or altered by others:

• Files: 644 — owner can read and write, others can only read.
• Folders: 755 — owner can write, others can traverse and read.
• Never 777. World-writable files and folders let anyone modify your code and are a serious security risk.
• Store any config file that holds your token outside the web root, or protect it so it is never served directly.

Testing your integration

Confirm the integration behaves as expected before you rely on it:

• Normal visit: load your page in a browser. You should see it render normally with no delay.
• Test URL: use the test decision URL or a preview token from your Cloak4U dashboard to simulate a block decision and confirm the 403 path works.
• Fail-open check: temporarily point the endpoint at an unreachable host and confirm your page still loads within the timeout — proving detection fails open.
• Logs: check the click log in the dashboard to confirm visits are recorded with a decision, reason code, and risk score.

Limitations and risks

Detection is probabilistic. Aggressive thresholds can block real users on shared or corporate networks, and loose settings let more invalid traffic through. Review your logs regularly, use the allowlist for sources you trust, and allowlist legitimate crawlers so SEO is unaffected. Cloak4U does not guarantee that every bot is caught or that no legitimate visitor is ever challenged. Adding a network request also introduces a small per-request latency, which the 2-second timeout caps.

Conclusion

The PHP integration gives you server-side invalid-traffic filtering with a small, auditable snippet that fails open and keeps secrets out of public files. Add it to your entry file, lock down permissions, test the block and fail-open paths, then watch your reports to tune sensitivity. Prefer no server changes? Try the JavaScript integration or the WordPress integration instead.