castle/castle-php

PHP bindings for Castle

3.2.0 2023-03-31 06:30 UTC

README

Latest Stable Version Total Downloads License

Code Climate Coverage Status

PHP SDK for Castle

Castle analyzes user behavior in web and mobile apps to stop fraud before it happens.

Usage

See the documentation for how to use this SDK with the Castle APIs

Getting started

Obtain the latest version of the Castle PHP bindings with:

git clone --single-branch --branch master https://github.com/castle/castle-php

To get started, add the following to your PHP script:

require_once("/path/to/castle-php/lib/Castle.php");

Configure the library with your Castle API secret.

Castle::setApiKey('YOUR_API_SECRET');

Optional Configurations

Set preferred connection and request timeouts: valid options for setting are:

  • CURLOPT_CONNECTTIMEOUT
  • CURLOPT_CONNECTTIMEOUT_MS
  • CURLOPT_TIMEOUT
  • CURLOPT_TIMEOUT_MS
Castle::setCurlOpts($curlOpts)

Set a specified list of request headers to include with event context (optional, not recommended):

Castle::setUseAllowlist($headers)

Request context

By default, Castle extracts all the necessary information, such as IP and request headers, from the PHP globals in order to build and send the requests to the Castle API. However in some cases you want to track data to Castle from a context where these globals are not available, eg. when tracking async in a background worker. In this case you can build the request context manually.

Origin IP Address

By default, the SDK extracts the contextual client IP address from headers in the following priority:

  1. X-Forwarded-For
  2. X-Real-Ip
  3. REMOTE_ADDR

If the true client IP address is not specified in the above headers, you can manually set the IP address like so:

Castle_RequestContext['ip'] = '1.1.1.1'
$context = Castle_RequestContext::extractJson();

Errors

Whenever something unexpected happens, an exception is thrown to indicate what went wrong.

Running test suite

Execute vendor/bin/phpunit test to run the full test suite