Give Notice

Fire-and-forget HTTP notifications - send a request to a preset URI and don't expect a response.

Vision

The idea of the package is to just “give notice” to another service. When the
notification is sent, it is not relevant to get any feedback.

This package provides a static method to send requests to a preset URI.

The URI is configured with an environment variable and therefore separated
from application code.

The app calling the method does not need or want a response.

The method is silent and non-blocking. The request timeout is very low by default.

Use cases:

Send a heartbeat to another service, to
push instead of polling, but yet don't reverse
responsibilities to react to unavailability
Ping a tracking service whenever a certain API endpoint was called,
limit the timeout and discard any response,
because under heavy load it is more important to keep a fast API than
losing some tracking requests
Notify an unimportant service or be absolutely positive the message will
receive its target and do not block the app unnecessarily

See »Usage« for an example.

The package follows the KISS principle.

Requirements

Installation

Packagist Entry https://packagist.org/packages/pixelbrackets/give-notice/

Source

https://gitlab.com/pixelbrackets/give-notice/

Mirror https://github.com/pixelbrackets/give-notice/

Usage

Set an environment variable to preset a URI to call later on.

GIVENOTICE_URI='https://example.com/endpoint/11azqde1'

Send a GET request straightaway, reading the URI from environment variable
```
\Pixelbrackets\GiveNotice\Notification::push();
```

Send a request and overwrite URI with https://example.com/alternative/

\Pixelbrackets\GiveNotice\Notification::push('https://example.com/alternative/');

Send a POST request with JSON payload

\Pixelbrackets\GiveNotice\Notification::push('https://example.com/webhook', \Pixelbrackets\GiveNotice\HttpMethod::POST, ['event' => 'order_placed', 'id' => 42]);

Send a HEAD request for lightweight heartbeats

\Pixelbrackets\GiveNotice\Notification::push('https://example.com/heartbeat', \Pixelbrackets\GiveNotice\HttpMethod::HEAD);

Use instance method instead of static call

(new \Pixelbrackets\GiveNotice\NotificationService())->push();

The method can be called multiple times throughout your application. All
requests are collected and sent asynchronously, so your code continues immediately.
At the end of the script execution all collected requests are sent.

Use pushSync() for long-running processes instead (daemons, queue workers) where
the script never ends and the asynchronous request would not be sent.

☝️ Be aware that the static notification object is silent by design. It returns
nothing and catches exceptions, such as connection errors. If the notified
service is not available then your app will not hear about it. Instead,
the service needs to monitor and react to overdue messages.

🎒 Tip: Some real word usage examples are listed in the vision section above. Another one is
pushing tracking events to Matomo without blocking your app:
read blog note

Testing

Using static method calls in application code sucks at testing. The static method
is mainly for convenience, when testing is not a concern.

The library also provides a NotificationService class to send notifications instead.

$notice = new \Pixelbrackets\GiveNotice\NotificationService();
$notice->push();

If static method calls are used and they block unit tests, you may mock the notification calls like this:

// Your app
class BookCatalogue {
    public function addBook(): void {
        // …
        \Pixelbrackets\GiveNotice\Notification::push();
    }
}

// Your test
$mock = $this->createMock(\Pixelbrackets\GiveNotice\NotificationService::class);
$mock->expects($this->once())->method('push');
\Pixelbrackets\GiveNotice\Notification::setService($mock);

$catalogue = new BookCatalogue();
$catalogue->addBook(); // no HTTP request is made

License

GNU General Public License version 2 or later

The GNU General Public License can be found at http://www.gnu.org/copyleft/gpl.html.

Author

Dan Kleine (mail@pixelbrackets.de / @pixelbrackets)

Changelog

See ./CHANGELOG.md

Contribution

This script is Open Source, so please use, patch, extend or fork it.

Contributions are welcome!

pixelbrackets/give-notice