graymatterlabs / pingtree
A Ping Tree is a process in which a single lead is offered to multiple buyers in real-time and sold to the highest bidder
Fund package maintenance!
graymatterlabs
Requires
- php: ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- phpunit/phpunit: ^9.5
- psr/simple-cache: ^3.0
Suggests
- psr/simple-cache: ^3.0
This package is auto-updated.
Last update: 2024-10-08 10:00:08 UTC
README
A Ping Tree is a process in which a single lead is offered to multiple buyers in real-time and sold to the highest bidder.
Installation
You can install the package via composer:
composer require graymatterlabs/pingtree:^0.3.0
Usage
$tree = new Tree($strategy, $offers); $response = $tree->ping($lead);
Responses
The ping tree will return the first successful response provided by an offer. Responses must implement the GrayMatterLabs\PingTree\Contracts\Response
interface but should be customized beyond that.
$tree = new Tree($strategy, $offers); $response = $tree->ping($lead); if ($response instanceof RedirectResponse) { return redirect($response->url()); }
Offers
Offer instances are responsible for communicating with and managing state of the offer such as health and eligibility rules.
<?php namespace App\Offers; use App\Http; use App\Leads\AutoLead; use GrayMatterLabs\PingTree\Contracts\Offer; use GrayMatterLabs\PingTree\Contracts\Lead; use GrayMatterLabs\PingTree\Contracts\Response; class Example implements Offer { private string $url = 'https://example.com'; public function __construct(private Http $http, private string $key) { } public function getIdentifier(): string|int { return 'example'; } public function ping(AutoLead $lead): int { $response = $this->http ->withHeader('Authorization', $this->key) ->post($this->url . '/value', [ // ... ]); return (int) $response->json('value'); } public function send(AutoLead $lead): Response { $response = $this->http ->withHeader('Authorization', $this->key) ->post($this->url . '/send', [ // ... ]); return new RedirectResponse(!$response->ok(), $response->json('accepted'), $response->json('url')); } public function isEligible(AutoLead $lead): bool { return $lead->validate(); } public function isHealthy(): bool { return $this->http->get($this->url . '/health')->ok(); } }
Events
This package fires events and provides you the ability to register listeners for each. Listeners can be used for performing any custom logic. Listeners are executed synchronously to be sure to handle any potential exceptions.
Listeners can be registered to the Tree class, which handles all events, using the listen
method, like so:
$tree = new Tree($strategy, $offers); // listen for any events $tree->listen($event, $callable); $tree->listen($event, $other_callable); $response = $tree->ping($lead);
Below is a list of all events fired, their descriptions, and the parameters passed to any registered listeners.
Strategies
This package provides a concept of "strategies" to decide which offer to send the lead to. A default set of strategies are provided out-of-the-box. The only requirement to providing your own strategies is that they implement the GrayMatterLabs\PingTree\Contracts\Strategy
interface.
Testing
composer test
Changelog
Please see the Release Notes for more information on what has changed recently.
Credits
License
The MIT License (MIT). Please see License File for more information.