PHP SDK

Installation

1

composer require botbye/botbye-php-sdk

Configuration

Phishing lives in its own dedicated BotbyePhishingClient, separate from the evaluate BotbyeClient. It is identified by a public, browser-safe clientKey, so it needs no server key — it only needs a PSR-18 HTTP client and a PSR-17 request factory. On first use it makes a one-off, process-wide-guarded, best-effort server-integration init handshake that reports this server-side integration to BotBye; it is non-blocking.

BotbyePhishingConfig takes endpoint (optional, defaults to https://verify.botbye.com), clientKey, and the optional initGuardFlagFile — where the once-per-process init-handshake guard flag is kept (default: the temp dir).

Getting clientKey

clientKey is the public, browser-safe identifier of your phishing project. It travels in the asset URL path, so it is safe to expose — no secret token and no Base64 encoding are required.

Find it on the Get Started screen of your phishing project in the BotBye dashboard.

1
2
3
4
5
6
7
8
9
10
11
12

use Botbye\Phishing\BotbyePhishingClient;
use Botbye\Phishing\BotbyePhishingConfig;
use Botbye\Phishing\BotbyePhishingCatcher;

$phishing = new BotbyePhishingClient(
    new BotbyePhishingConfig(
        endpoint: 'https://verify.botbye.com',
        clientKey: '<public-client-key>',
    ),
    $httpClient,     // PSR-18 ClientInterface
    $requestFactory, // PSR-17 RequestFactoryInterface
);

Usage

Anti-phishing needs two routes on your own origin: an SVG route — the URL your client code passes to getCatcher({ url }) — and a PNG route that the SVG references. The paths are arbitrary, so name them like ordinary static assets and let the route decide the format. A path that spells out the vendor or the feature (/api/phishing/…) is what a copied page is searched for and stripped of, and a format query param on the pixel URL reads the same way.

On the SVG route, pass innerPngUrl — the absolute URL of your PNG route: the returned SVG embeds it as its tracking pixel. It is required: the SVG catcher takes it as a constructor argument, so an SVG asset without one does not compile, and a blank one is rejected on the spot rather than reaching the wire. Build that URL from your own host — image_id is owned by the SDK and is not read from the forwarded query. skipExecution defaults to true, the script-less SVG; pass false only for browsers predating crossorigin on svg <image> (Chrome 118, Firefox 114, Safari 17.2), where the script-driven variant is the one that still reports.

These examples forward no query: format, image_id and executable are set by the call itself, and only module_name / module_version pass through from the browser's pixel query — which a catcher mounted on your own routes never receives.

If you would rather not read the request yourself, bind it once: BotbyePhishingClient::withExtractor($config, $httpClient, $requestFactory, $extractor) — where $extractor maps your request to a BotbyePhishingRequestInfo ($origin, $referer, $query) — and call fetchCatcher(BotbyePhishingCatcher::svg(…), $request), passing the request where the $origin header value would go. The extractor is then the only thing that reads the request — headers and query alike.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Botbye\Phishing\BotbyePhishingCatcher;

// Absolute URL of your PNG route — the SVG catcher references it as innerPngUrl.
const PNG_CATCHER_URL = 'https://your-site.example/your-image-route.png';

$origin = $_SERVER['HTTP_ORIGIN'] ?? null;
$referer = $_SERVER['HTTP_REFERER'] ?? null;

// Serve this from /your-image-route.svg. The PNG route is the same script with
// BotbyePhishingCatcher::png() — the path picks the catcher.
$res = $phishing->fetchCatcher(BotbyePhishingCatcher::svg(PNG_CATCHER_URL), $origin, $referer);

if ($res->error !== null) {
    http_response_code(502);
    echo $res->error->message;
    exit;
}

http_response_code($res->status);
header('Content-Type: ' . ($res->headers['Content-Type'] ?? 'image/png'));
echo $res->body;

Settings

Configuration parameters for phishing integration: