README

Shields help to create a barrier between requests and your API. A Shield provides a way to filter requests based on a simple set of rules before they reach the rest of your application. This helps to fail early and consistently against malformed requests so you don't need to deal with this continually within your controllers.

Why use Shields?

Allows simple request inspection to be abstracted into a separate classes.
Reduces controller bloat by removing the amount of "input checking" if statements.
Highly configurable, extensible and framework-agnostic.

What can Shields check?

Required parameters are being sent.
Ensure two fields match, such as password confirmation.
Anything you want via custom Guards.

Requirements

The following versions of PHP are supported by this version.

PHP 5.4
PHP 5.5
PHP 5.6
HHVM

Install

The primary way to install Shields is via Composer:

{
    "require": {
        "cairns/shields": "~0.1"
    }
}

Getting Started

When setting up Shields, you can provide an array of Guards which can be used. This list can be customised with your own guards, however several Guards are provided for common checks.

For example, to only run some simple checks on input, your configuration may look like:

use Cairns\Shields\ShieldManager;
use Cairns\Shields\Guards\ArrayGuard;

$shields = new ShieldManager([
    'post' => new ArrayGuard($_POST)
]);

Example Usage

Following on from our simple setup, we can look at a simple use case for a login attempt.

An example shield for this action may look like:

use Cairns\Shields\ShieldFilterAbstract;

class LoginControllerShield extends ShieldFilterAbstract
{
    public function post()
    {
        $this->post->required('username');
        $this->post->required('password');
    }
}

... your controller may then look something like this:

use Cairns\Shields\ShieldManager;

class LoginController
{
    private $shield;

    public function __construct(ShieldManager $shield)
    {
        $this->shield = new LoginControllerShield($shield);
    }

    public function post()
    {
        $this->shield->post();

        // shields are down, you may proceed.
    }
}

Manager

The ShieldManager controls the shields. It contains the list of Guards which can be used along with determining what happens when the shields need to be raised.

When creating the manager, there are a few pieces of data you can set:


$shields = new Cairns\Shields\ShieldManager([
    // Guards go here!
]);

// Set the error handler
$shields->setErrorHandler(function ($exception) {
    // What happens when something goes wrong.
    // Default: throw $exception;
});

Guards

Think of Guards as sensors - tools to determine which requiests can make it through the shield.

Guards are really simple checks that can be run quickly before a request makes it to your controller. Failing guards will call $this->raiseShields(...) passing through an exception which extends \Cairns\Shields\Exceptions\ShieldsUpException

Let's take a quick look at the structure of a Guard;

use Cairns\Shields\Guars\BaseGuard;
use Cairns\Shields\Guars\GuardInterface;
use Cairns\Shields\Exceptions\ShieldsUpException;

class ExampleGuard extends BaseGuard implements GuardInterface
{
    public function checkSomething()
    {
        // If a check fails, the shields are raised.
        if (false) {
            $this->raiseShields(new ShieldsUpException);
        }

        return true;
    }
}

When adding the guard to the ShieldManager, ensure it is indexed appropriately so it is accessible within your filter.

use Cairns\Shields\ShieldManager;

$shields = new ShieldManager([
    'example' => new ExampleGuard
]);

You can then use the following code to run the check:

$this->example->checkSomething();

Todo

Setup TravisCI
Setup Scrutinizer
Improve test coverage
Update README.md with badges

Ponderings

Consider throwing exceptions instead of $this->fail(...)

Credits

License

The MIT License (MIT). Please see LICENSE file for more information.

cairns / shields

Maintainers

Details