Castle adds real-time monitoring of your authentication stack, instantly notifying you and your users on potential account hijacks.
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');
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)
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.
By default, the SDK extracts the contextual client IP address from headers in the following priority:
X-Forwarded-For
X-Real-Ip
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();
// While in a web request context, extract the information needed to send the
// request.
$context = Castle_RequestContext::extractJson();
$event = array(
'user_id' => 1,
'event' => '$login.succeeded'
);
// Now, push this data to your async worker, eg.
$castleWorker->perform($event, $context);
In your worker code (ie. non web environment):
// Pass the context to track or authenticate
Castle::track(array(
'event' => $event['event'],
'user_id' => $event['user_id'],
'context' => json_decode($context)
));
Whenever something unexpected happens, an exception is thrown to indicate what went wrong.
Name | Description |
---|---|
Castle_Error |
A generic error |
Castle_RequestError |
A request failed. Probably due to a network error |
Castle_ApiError |
An unexpected error for the Castle API |
Castle_ConfigurationError |
The Castle secret API key has not been set |
Castle_UnauthorizedError |
Wrong Castle API secret key |
Castle_BadRequest |
The request was invalid. For example if a challenge is created without the user having MFA enabled. |
Castle_ForbiddenError |
The user has entered the wrong code too many times and a new challenge has to be requested. |
Castle_NotFoundError |
The resource requestd was not found. For example if a session has been revoked. |
Castle_InvalidParametersError |
One or more of the supplied parameters are incorrect. Check the response for more information. |
Execute vendor/bin/phpunit test
to run the full test suite