/castle-php

PHP library for Castle

Primary LanguagePHPMIT LicenseMIT

Latest Stable Version Total Downloads License

Build Status Code Climate Coverage Status

PHP SDK for Castle

Castle adds real-time monitoring of your authentication stack, instantly notifying you and your users on potential account hijacks.

Getting started

Obtain the latest version of the Castle PHP bindings with:

git clone 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');

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.

Example

// While in a web request context, extract the information needed to send the
// request.
$context = Castle_RequestContext::extractJson();
$event = array(
	'user_id' => 1,
	'name' => '$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, identify or authenticate
Castle::track(array(
  'name' => $event['name'],
  'user_id' => $event['user_id'],
  'context' => json_decode($context)
));

Errors

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.

Running test suite

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