theroadbunch/bouncer

Bouncer is an easy-to-use allow/deny list interface.

v2.1 2023-03-16 19:24 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Dan McAdams

README

What is Bouncer?

Bouncer is an easy-to-use allow/deny list interface.

Why the name Bouncer?

In the real-world, a bouncer holds the list of who is allowed entry and who is not.

• AllowBouncer: At an exclusive club, the bouncer has a list and if you're not on it, you can't come in.
• DenyBouncer: The local bar allows almost everyone in, the bouncer has a list of trouble-makers to stop at the door.

Contents

1. Installation
2. Implementation
   1. Standard Usage
   2. Real-World Use-Case
3. Bouncers
4. Abstract Bouncer
5. License

Install using composer ^[?]

composer require theroadbunch/bouncer

Implementation

Standard Usage

Use Bouncer::allow() or Bouncer::deny() to create your allow/deny lists (bouncer).

use RoadBunch\Bouncer\Bouncer;

$subjectList = ['example', 'one', 'two', 'three'];
$bouncer = Bouncer::allow($subjectList);
$bouncer->isAllowed('example'); // true

$bouncer = Bouncer::deny($subjectList);
$bouncer->isAllowed('example'); // false

// or
$subjectList = 'example;one;two;three';
$bouncer = Bouncer::allow($subjectList);
$bouncer->isAllowed('one'); // true
$bouncer->isAllowed('not in list'); // false

$bouncer = Bouncer::deny($subjectList);
$bouncer->isAllowed('two'); // false
$bouncer->isAllowed('not in list'); // true

// or 
$subject = 'onlydomainiwanttosendemailto.com';
$bouncer = Bouncer::allow($subject);
$bouncer->isAllowed($subject); // true
$bouncer->isAllowed('example.com'); //false

Update the Bouncer in real time

use RoadBunch\Bouncer\Bouncer;

$subject = 'allowedAndThenDenied';

$bouncer = Bouncer::allow($subject);
$bouncer->isAllowed($subject); // true

$bouncer->deny($subject);
$bouncer->isAllowed($subject); // false

Using BouncerFactory::create()
_{This has been deprecated and will be removed from the documentation in version 2.4}

use RoadBunch\Bouncer\Rule;
use RoadBunch\Bouncer\BouncerFactory;

$subjectList = ['example', 'one', 'two', 'three'];
$bouncer = BouncerFactory::create(Rule::ALLOW, $subjectList);
$bouncer->isAllowed('example'); // true
$bouncer->isAllowed('not in list'); // false

Example of a real-world use-case

<?php
declare(strict_types=1);

use Psr\Log\LoggerInterface;
use RoadBunch\Bouncer\Bouncer;
use RoadBunch\Bouncer\BouncerInterface;

class Mailer
{
    public function __construct(      
        /** ... config parameters ... */,
        private readonly LoggerInterface $logger,
        private readonly BouncerInterface $bouncer, 
    ) {}
    
    public function send(string $address, string $message): void
    {
        if (!$this->bouncer->isAllowed($address)) {
            $this->logger->warning("Cannot send email to blocked email address: {$address}");
            return;
        }
        // do work
        if (/* work fails */) {
            // deny this address in the next run
            $this->bouncer->deny($address);
            $this->logger->error("Sending failed, {$address} added to block list.")
            return;
        }
        $this->logger->info("Sending email to {$address}.");                               
    }
}

// Create a bouncer that has a DenyList
$bouncer = Bouncer::deny(['[e-mail]', '[e-mail]']);
$mailer = new Mailer($bouncer);

$mailer->send('[e-mail]', 'Welcome!'); // logs warning
$mailer->send('[e-mail]', 'Welcome!'); // sends mail

Bouncers

All bouncers implement RoadBunch\Bouncer\BouncerInterface

RoadBunch\Bouncer\AllowBouncer

method	description	return type
isAllowed(string $subject)	returns true if the subject is on the allow list	bool
allow(string $subject)	Add this subject to the allow list	void
deny(string $subject)	Remove this subject from the allow list	void

RoadBunch\Bouncer\DenyBouncer

method	description	return type
isAllowed(string $subject)	returns true if the subject is NOT on the deny list	bool
allow(string $subject)	Remove this subject from the deny list	void
deny(string $subject)	Add this subject to the deny list	void

Abstract Bouncer

RoadBunch\Bouncer\AbstractBouncer implements RoadBunch\Bouncer\BouncerInterface and is available to extend if you need to write your own logic to determine if a subject is allowed.

method	description	return type
has(string $subject)	returns true if a subject is held in the subject pool	bool
add(string $subject)	Add this subject to the pool	void
remove(string $subject)	Remove this subject from the pool	void

License

© Dan McAdams | The content of this library is released under the MIT License

You can find a copy of this license in LICENSE or at http://opensource.org/licenses/mit.