jolicode/JoliNotif for PHP desktop notifications

JoliNotif's place in local PHP automation

JoliNotif solves a specific problem: displaying a desktop notification from PHP without requiring the sender to be a native application. It is aimed at developers and operators who run local CLI utilities, scheduled jobs or other PHP processes and want a visible status message through the operating system's notification interface.

The README documents support for Linux, Windows, WSL and macOS. That makes the library relevant when a PHP command should report completion, a warning or another event to a person at the workstation. It is different from email, logging or an HTTP response because the intended destination is the desktop notification service.

The operating-system label alone does not guarantee that every field behaves identically. The example adds `subtitle`, which the README limits to macOS with `AppleScriptDriver`, and `sound`, which it limits to macOS with `AppleScriptDriver` and `TerminalNotifierDriver`. A cross-platform application therefore needs a portable base message and should add richer properties only when the selected driver accepts them.

JoliNotif is also unsuited to direct use while handling a PHP web request. The README explicitly states that it cannot be used in a web context such as FPM or an equivalent environment. Its documented contexts are CLI scripts and CRON. Even there, a headless server or scheduled process without access to a user's desktop session may have no notification service to receive the request. The README does not document login-session discovery, permission prompts or a fallback for headless hosts, so those conditions need checking in the local environment.

How JoliNotif separates notifications from delivery

The documented PHP API separates notification content from delivery. A `Joli\JoliNotif\Notification` object carries the title, body, icon and optional values. A `Joli\JoliNotif\DefaultNotifier` instance receives that object through `send()`. The fluent methods let application code assemble the message step by step without exposing platform commands in the example.

Basic fields are assigned through methods including `setTitle`, `setBody` and `setIcon`. The README uses `__DIR__.'/path/to/your/icon.png'`, so an application supplies a local filesystem path. The documentation does not say whether a missing icon blocks delivery, whether the path is validated or how images behave on a remote host. Code should not claim stronger validation than the README describes.

`addOption()` provides an extension point for driver-specific properties. That approach allows the notification model to carry options beyond the common fields, but portability is the caller's responsibility. The documented `subtitle` and `sound` examples are tied to particular macOS drivers. An application that always sends those values would create a cross-platform assumption that the README does not support.

The linked `doc/03-drivers.md` file is the authoritative place to inspect the complete driver set. The README does not explain how `DefaultNotifier` selects a driver, whether that selection can be overridden, what fallback it uses, or which native programs must be present on each operating system. Those omissions matter when diagnosing a notification that PHP accepts but the desktop never shows.

Installing JoliNotif and sending a first notification

The README directs users to Composer for installation. Its current version requirement is PHP 8.3 or newer, so the command should be run in an application that already satisfies that constraint:

composer require "jolicode/jolinotif"

After installation, the generated Composer autoloader can load the classes. This first-use example follows the README, including its local image path and macOS-specific properties:

include __DIR__.'/vendor/autoload.php';

use Joli\JoliNotif\Notification;
use Joli\JoliNotif\DefaultNotifier;

$notifier = new DefaultNotifier();
$notification =
    (new Notification())
    ->setTitle('Notification title')
    ->setBody('This is the body of your notification')
    ->setIcon(__DIR__.'/path/to/your/icon.png')
    ->addOption('subtitle', 'This is a subtitle')
    ->addOption('sound', 'Frog');

$notifier->send($notification);

On a correctly configured supported desktop, the expected result is a notification containing the supplied title and body. The icon and additional fields still depend on driver support. The `subtitle` and `sound` values shown here are not portable across all systems.

The README does not define the return type of `send()`, a list of exceptions or a boolean delivery result. It also does not state whether notification-service acknowledgement is available to PHP. This makes `doc/01-basic-usage.md` and `doc/02-notification.md` the relevant files to consult before using JoliNotif in a workflow that must record delivery failures.

The repository also contains `example/index.php`, `jolinotif` and an `example/icon-success.png` asset. The README does not explain the exact command for running `example/index.php`, so the documented Composer example is the safer starting point.

Sending JoliNotif messages from jolinotif

The package provides a shell executable named `jolinotif`. The README gives this basic invocation:

jolinotif --title "Hello" --body "World"

This interface is useful for shell scripts that already know the notification text and do not need to construct a PHP object. It can sit beside an existing deployment or maintenance command without adding a new PHP entry point. For values assembled during application execution, the `DefaultNotifier` API provides direct integration.

The README links to `doc/05-cli-usage.md` for the complete CLI documentation, but it does not list optional flags, configuration files, environment variables or exit statuses. It also does not state where Composer places the executable after installation. A deployment wrapper that branches on the command's exit code needs facts from the CLI documentation or source before it can be considered reliable.

CRON is another documented context. The README points to `doc/04-cron-usage.md`, which should be read before scheduling notifications. The top-level README does not state which scheduler environment receives the notification, whether `DISPLAY` or another platform variable must be inherited, or whether the process must run under the interactive user's account. A CRON example should therefore be verified in its actual scheduler context, not only in an open terminal.

JoliNotif runtime, platform and permission boundaries

The clearest runtime constraint is PHP 8.3. The README says the current library requires PHP 8.3 and that support for earlier PHP versions exists in older releases. An application on an earlier PHP version therefore cannot adopt the current release without upgrading PHP or selecting a different JoliNotif version. Moving to an older package means reviewing that version's documentation and changelog rather than assuming the current API is identical.

The process boundary is equally firm. FPM and equivalent web contexts are excluded by the README, while CLI and CRON are listed as supported uses. That exclusion is especially important for web applications that want to notify an administrator after an upload, deployment or background event. Moving the call to a worker can address the FPM restriction only if that worker has access to the appropriate desktop session. The README does not promise that background or headless execution will display a notification.

Driver support creates another failure point. `subtitle` works only on macOS with `AppleScriptDriver`. The documented `sound` option also applies only to macOS with `AppleScriptDriver` and `TerminalNotifierDriver`. Passing these options does not make them useful on Linux, Windows or WSL.

The README does not document user notification permissions, missing platform executables, timeouts, duplicate suppression or delivery acknowledgements. Those are not optional details for a notification feature used as an operational signal. A real workstation check should establish what the user sees, what `send()` reports on failure and whether an administrator can suppress messages at the operating-system level.

JoliNotif compared with its Node.js inspiration

The README names `mikaelbr/node-notifier` as the project that originally inspired JoliNotif. That is the only direct alternative identified by the repository documentation. JoliNotif exposes PHP notification classes and a `jolinotif` executable. Its origin does not imply that their current APIs, driver coverage or release policies are identical.

For a PHP CLI application, JoliNotif keeps notification code in the existing language and dependency tree. Composer installs the package, PHP code can construct `Notification` objects, and shell automation can call `jolinotif`. A project without a Node.js runtime can therefore avoid adding one just for desktop notification delivery.

The tradeoff is equally direct. JoliNotif's current README requires PHP 8.3 and excludes FPM. A team already standardized on Node.js notification tooling would need its own comparison of drivers, process-context behavior and operating-system requirements. The JoliNotif README does not provide that comparison, so it should not be used to claim superiority in feature coverage.

JoliNotif releases, PHP upgrades and MIT licensing

The repository is not archived, and its last push was on 2026-09-29. Recent releases include `v3.4.1` on 2026-09-29, `v3.4.0` on 2026-09-09 and `v3.3.1` on 2026-07-22. The README points readers to Git tags, the GitHub releases page and `CHANGELOG.md` when they need version history.

The PHP 8.3 requirement can dominate upgrade planning. A team that already runs PHP 8.3 can install the current package through Composer. A team on an older PHP version must either upgrade its runtime or investigate an older JoliNotif release. The repository contains `VERSIONING.md` for its branching and versioning model, plus `composer.json`, `phpstan.necon`, `phpunit.xml.dist`, `.php-cs-fixer.php` and `tools/`. The actual repository file is `phpstan.neon`, not `phpstan.necon`; these files indicate development and static-analysis configuration, although the README does not prescribe those tools for library consumers.

JoliNotif uses the MIT License. The README identifies the repository's `LICENSE` file as the source for its details. Applications that redistribute JoliNotif should preserve the required licence notices and review the package metadata as part of their release process. This is repository-level licensing information, not an assessment of unrelated desktop, operating-system or third-party driver terms.

Editorial conclusion

PHP teams that need notifications from local CLI scripts or scheduled jobs should evaluate JoliNotif, especially where the process can access the desktop session associated with the user. Web applications, FPM processes and projects pinned to an earlier PHP version should reject the current release unless they can change that constraint. Before adoption, verify the selected platform driver on the actual workstation or host and confirm how `send()` reports failure, because the README does not document an exception contract or return value.

Frequently asked questions

Official sources

1. jolicode/JoliNotif on GitHub
2. License: MIT
3. Project website
4. README
5. Releases