PHPackages                             castle/castle-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. castle/castle-php

ActiveLibrary[Utility & Helpers](/categories/utility)

castle/castle-php
=================

PHP bindings for Castle

3.2.0(3y ago)8225.3k↑57.5%7[3 issues](https://github.com/castle/castle-php/issues)1MITPHPPHP >=7.2.0

Since Jun 27Pushed 3y ago18 watchersCompare

[ Source](https://github.com/castle/castle-php)[ Packagist](https://packagist.org/packages/castle/castle-php)[ Docs](https://github.com/castle/castle-php)[ RSS](/packages/castle-castle-php/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (28)Used By (1)

[![Latest Stable Version](https://camo.githubusercontent.com/f5879675ee3e5028a420821f485a9cae7a956facad83cdebdc78f99d4de4d731/68747470733a2f2f706f7365722e707567782e6f72672f636173746c652f636173746c652d7068702f762f737461626c652e737667)](https://packagist.org/packages/castle/castle-php) [![Total Downloads](https://camo.githubusercontent.com/0328168c2ccc411105d9a3edebe184c06715bf7aa5ac38bc4887d23691eda72c/68747470733a2f2f706f7365722e707567782e6f72672f636173746c652f636173746c652d7068702f646f776e6c6f6164732e737667)](https://packagist.org/packages/castle/castle-php) [![License](https://camo.githubusercontent.com/da953e6697094857514b4bfcc2051c94cf6b3ba7294fa54b615c068628599da1/68747470733a2f2f706f7365722e707567782e6f72672f636173746c652f636173746c652d7068702f6c6963656e73652e737667)](https://packagist.org/packages/castle/castle-php)

[![Code Climate](https://camo.githubusercontent.com/1db2e699980859c50e075165d1a8f6d5f77377c4cb660a3175b4ece084655bec/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f636173746c652f636173746c652d7068702e706e67)](https://codeclimate.com/github/castle/castle-php)[![Coverage Status](https://camo.githubusercontent.com/56b896f0d42e460d9401ac69e5a0b928dcd3432b7731df3a4750b4547e9779dc/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f636173746c652f636173746c652d7068702f62616467652e7376673f6272616e63683d666978253246636f64652d636f766572616765)](https://coveralls.io/github/castle/castle-php?branch=fix%2Fcode-coverage)

PHP SDK for Castle
==================

[](#php-sdk-for-castle)

**[Castle](https://castle.io) analyzes user behavior in web and mobile apps to stop fraud before it happens.**

Usage
-----

[](#usage)

See the [documentation](https://docs.castle.io) for how to use this SDK with the Castle APIs

Getting started
---------------

[](#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
-----------------------

[](#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
---------------

[](#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

[](#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
------

[](#errors)

Whenever something unexpected happens, an [exception](/lib/Castle/Errors.php) is thrown to indicate what went wrong.

NameDescription`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.`Castle_InvalidRequestTokenError`The request token parameter is missing or invalidRunning test suite
------------------

[](#running-test-suite)

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

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance13

Infrequent updates — may be unmaintained

Popularity43

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 72.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~159 days

Recently: every ~335 days

Total

21

Last Release

1145d ago

Major Versions

1.7.0 → 2.0.02019-07-26

2.1.0 → 3.0.02021-06-03

PHP version history (3 changes)1.0.0PHP >=5.3.2

1.4.0PHP >=5.6.0

2.0.0PHP >=7.2.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4f78a6b633ad45fd5c5139daee3b453d339321844254c0cbec502d43735a89ff?d=identicon)[castle](/maintainers/castle)

---

Top Contributors

[![wallin](https://avatars.githubusercontent.com/u/268917?v=4)](https://github.com/wallin "wallin (191 commits)")[![lluft](https://avatars.githubusercontent.com/u/617198?v=4)](https://github.com/lluft "lluft (31 commits)")[![brissmyr](https://avatars.githubusercontent.com/u/238031?v=4)](https://github.com/brissmyr "brissmyr (21 commits)")[![bartes](https://avatars.githubusercontent.com/u/93064?v=4)](https://github.com/bartes "bartes (13 commits)")[![joladev](https://avatars.githubusercontent.com/u/297627?v=4)](https://github.com/joladev "joladev (3 commits)")[![afterdesign](https://avatars.githubusercontent.com/u/672767?v=4)](https://github.com/afterdesign "afterdesign (3 commits)")[![marysieek](https://avatars.githubusercontent.com/u/7430071?v=4)](https://github.com/marysieek "marysieek (1 commits)")[![szphie](https://avatars.githubusercontent.com/u/3667695?v=4)](https://github.com/szphie "szphie (1 commits)")[![brunov25](https://avatars.githubusercontent.com/u/1091322?v=4)](https://github.com/brunov25 "brunov25 (1 commits)")

---

Tags

castlefraud-detectionfraud-preventionphpsdkreal-time user account monitoring

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/castle-castle-php/health.svg)

```
[![Health](https://phpackages.com/badges/castle-castle-php/health.svg)](https://phpackages.com/packages/castle-castle-php)
```

###  Alternatives

[pragmarx/support

PragmaRX components support package

591.5M27](/packages/pragmarx-support)[bcremer/line-reader

Read large files line by line in a memory efficient (constant) way.

301.6M4](/packages/bcremer-line-reader)[beelab/recaptcha2-bundle

Provide Google Recaptcha2 form type

55455.1k1](/packages/beelab-recaptcha2-bundle)[lkrms/pretty-php

The opinionated PHP code formatter

14659.1k1](/packages/lkrms-pretty-php)[kreyu/data-table-bundle

Streamlines creation process of the data tables

11299.6k](/packages/kreyu-data-table-bundle)[adhocore/cron-expr

Ultra lightweight Cron Expression parser for PHP

53436.1k3](/packages/adhocore-cron-expr)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)