Refactor public notifiers into internal drivers

CHANGELOG.md

@@ -2,8 +2,12 @@
 
 ## Not released yet
 
+* Added a new NotifierInterface and DefaultNotifier as the main public API of this package
 * Added wsl-notify-send notifier for Windows Subsystem for Linux
 * Changed TerminalNotifier to use contentImage option for icon instead of appIcon
+* Marked most of the classes as internal
+* Deprecated all the notifiers classes in favor of the new internal DriverInterface implementations
+* Deprecated the NotifierFactory in favor of the new DefaultNotifier class that hide driver implementation details
 
 ## 2.6.0 (2023-12-03)
 

README.md

@@ -68,7 +68,7 @@ Discover more by reading the docs:
 
 * [Basic usage](doc/01-basic-usage.md)
 * [Notification](doc/02-notification.md)
-* [Notifier](doc/03-notifier.md)
+* [Drivers](doc/03-drivers.md)
 * [CRON usage](doc/04-cron-usage.md)
 * [CLI usage](doc/05-cli-usage.md)
 

composer.json

@@ -23,6 +23,7 @@
     "require": {
         "php": ">=8.1",
         "jolicode/php-os-helper": "^0.1.0",
+        "psr/log": "^3.0",
         "symfony/process": "^5.4 || ^6.0 || ^7.0"
     },
     "require-dev": {

doc/01-basic-usage.md

@@ -1,31 +1,38 @@
 # Basic usage
 
-## Create a notifier
+## Create a notifier and sending a notification
 
-JoliNotif provides a `NotifierFactory` which creates the best supported
-notifier according to your platform. You don't have to care if you're running
-on Linux, Windows or Mac OS:
+JoliNotif provides a `DefaultNotifier` class which is the main entrypoint of
+the library. It's main goal is to provide a simple way to send a desktop
+notification without having to care about the platform you're running on. It
+will work whether you're on Linux, Windows or macOS.
 
 ```php
-use Joli\JoliNotif\NotifierFactory;
+use Joli\JoliNotif\DefaultNotifier;
+use Joli\JoliNotif\Notification;
+
+$notifier = new DefaultNotifier();
 
-$notifier = NotifierFactory::create();
+$notifier->send(new Notification());
 ```
 
-The factory use the notifier's priority to determine the best notifier to use.
-For example some notifier has a low priority because they don't support some
-notification options. The best notifier will then be returned.
+And you're done!
+
+Internally, the notifier will use each driver's priority to determine the
+best one available on your system.
+For example, some driver have a low priority because they don't support some
+notification options. So if a better driver is available, it will be used.
 
-> **Note**
-> The factory now returns a NullNotifier instead of null when no notifier is
-> available. You then no longer have to check for null value.
+> [!NOTE]
+> In case no driver is supported or if an error happens during notification
+> sending, the send method will return false.
 
-If you really need to ensure a Notifier is available, you can use the
-`createOrThrowException` method. It will return the best notifier available or
-throw a `Joli\JoliNotif\Exception\NoSupportedNotifierException` if no one is
-available on the current system.
+> [!TIP]
+> If you want to log when an error happens or if no driver is supported, you
+> can also pass an instance of `Psr\Log\LoggerInterface` as the first
+> parameter of the `DefaultNotifier`'s constructor.
 
-## Create your notification
+## Create and configure your notification
 
 Create a notification is as simple as instantiating a `Notification` and
 setting the option you want to use:
@@ -37,29 +44,18 @@ $notification =
     (new Notification())
     ->setBody('The notification body')
     ->setTitle('The notification title')
-    ->addOption('subtitle', 'This is a subtitle') // Only works on macOS (AppleScriptNotifier)
-    ->addOption('sound', 'Frog') // Only works on macOS (AppleScriptNotifier)
-    ->addOption('url', 'https://google.com') // Only works on macOS (TerminalNotifierNotifier)
+    ->addOption('subtitle', 'This is a subtitle') // Only works on macOS (AppleScriptDriver)
+    ->addOption('sound', 'Frog') // Only works on macOS (AppleScriptDriver)
+    ->addOption('url', 'https://google.com') // Only works on macOS (TerminalNotifierDriver)
 ;
 ```
 
-As you can see, the notification provides a fluent API.
-
-## Sending the notification
-
-Now that you get your notification, just send it via the notifier:
-
-```php
-$notifier->send($notification);
-```
-
-And you're done!
-
+As you can see, the notification class provides a fluent API.
 
 ## Next readings
 
 * [Notification](02-notification.md)
-* [Notifier](03-notifier.md)
+* [Drivers](03-drivers.md)
 * [CRON usage](04-cron-usage.md)
 * [CLI usage](05-cli-usage.md)
 

doc/02-notification.md

@@ -74,7 +74,7 @@ $notification->addOption('url', 'https://google.com');
 
 ## Next readings
 
-* [Notifier](03-notifier.md)
+* [Drivers](03-drivers.md)
 * [CRON usage](04-cron-usage.md)
 * [CLI usage](05-cli-usage.md)
 

doc/03-drivers.md

@@ -0,0 +1,157 @@
+# Drivers
+
+JoliNotif's default notifier uses drivers to delegate the notification sending
+to the right executable available on your system.
+
+## Interface
+
+All drivers implement the `Joli\JoliNotif\Driver\DriverInterface` interface.
+
+`Driver#send()` will return true if the command was successfully executed,
+false otherwise.
+
+## Supported drivers
+
+Currently, JoliNotif only provides drivers that use an executable available
+on your system. But nothing prevents to add network based notifiers later for
+example! :)
+
+Here is the full list of supported notifiers, grouped by platform:
+
+### Linux
+
+#### KDialogDriver
+
+This driver uses the executable `kdialog` (part of the standard KDE 5 Plasma
+Desktop installation) which should be installed by default on most Linux
+distributions which use the KDE 5 Plasma Desktop such as KUbuntu.
+
+kdialog can display notifications with a body and a title. It does not support
+icons. A default timeout of 5 seconds is hard-coded for the notification as it
+needs to be part of the command line.
+
+#### NotifySendDriver
+
+This notifier uses the executable `notify-send` (available in the 
+`libnotify-bin` package) which should be installed by default on most Linux
+distributions.
+
+notify-send can display notification with a body, a title and an icon.
+
+### Mac OS
+
+#### GrowlNotifyDriver
+
+This driver uses the `growlnotify` executable. It can be used when available
+alongside growl, which can be installed on Mac OS X.
+
+growl can display notification with a body, a title and an icon.
+
+#### TerminalNotifierDriver
+
+This driver uses the `terminal-notifier` executable and works on Mac OS X 10.8
+and higher.
+
+terminal-notifier can display notification with a body and a title. An icon can
+only be displayed on Mac OS X 10.9 and higher.
+
+#### AppleScriptDriver
+
+This driver is based on AppleScript and uses the `osascript` binary.
+AppleScript can display notification since Mac OS X 10.9, so this driver
+requires this version or higher.
+
+AppleScript can display notification with only a body and a title. AppleScript
+don't support to set an icon and will always use instead the icon of the
+application sending the notification, in our case, the terminal.
+
+#### WslNotifySendDriver
+
+This driver uses the executable `wsl-notify-send`.
+It permits to send notification from Windows Subsystem for Linux to Windows.
+
+wsl-notify-send can display notification with a body and a title.
+
+Icon is partially supported by `wsl-notify-send`, but it's not possible to set
+an icon for now.
+
+### Windows
+
+#### SnoreToastDriver
+
+This driver uses the Windows application called SnoreToastDriver. It works on
+Windows 8 and higher. Because SnoreToastDriver is probably not installed on
+your system, JoliNotif embed the binaries inside the [bin/snoreToast](bin/snoreToast)
+directory.
+
+When you use JoliNotif inside a phar archive, we take care to extract those
+binaries in the system temp directory to be able to execute them.
+
+SnoreToastDriver can display notification with a body, a title and an icon.
+
+#### ToasterDriver
+
+This driver uses the Windows application called Toaster. It works on Windows 8
+and higher. Because Toaster is probably not installed on your system, JoliNotif
+embed the binaries inside the [bin/toaster](bin/toaster) directory.
+
+When you use JoliNotif inside a phar archive, we take care to extract those
+binaries in the system temp directory to be able to execute them.
+
+Toaster can display notification with a body, a title and an icon.
+
+#### NotifuDriver
+
+This driver uses the Windows application called Notifu. It works on Windows 7.
+Because Notifu is probably not installed on your system, JoliNotif embed the
+binary inside the [bin/notifu](bin/notifu) directory.
+
+When you use JoliNotif inside a phar archive, we take care to extract this
+binary in the system temp directory to be able to execute it.
+
+Notifu can display notification with a body, a title and an icon. Sadly, Notifu
+can only display icon with the .ico format.
+
+## Using custom drivers
+
+If you created your own driver, you can pass it in the `$additionnalDrivers`
+parameter of the `DefaultNotifier` constructor:
+
+```php
+use Joli\JoliNotif\DefaultNotifier;
+use Joli\JoliNotif\Notification;
+
+$notifier = new DefaultNotifier(null, [new MyCustomDriver()]);
+
+$notifier->send(new Notification());
+```
+
+If the driver is supported, it will be used in priority. If not, the default
+drivers will be looked for. You can totally disable the default drivers by also
+passing `false` in the `$useOnlyAdditionalDrivers` parameter of the constructor:
+
+```php
+use Joli\JoliNotif\DefaultNotifier;
+use Joli\JoliNotif\Notification;
+
+$notifier = new DefaultNotifier(null, [new MyCustomDriver()], false);
+
+// If MyCustomDriver is not supported, no native drivers will not be used
+// and the send method will always return false.
+$notifier->send(new Notification());
+```
+
+> [!NOTE]
+> If you created a driver that could be useful for others, feel free to open a
+> pull request, so we can consider adding it natively in the library!
+
+## Next readings
+
+* [CRON usage](04-cron-usage.md)
+* [CLI usage](05-cli-usage.md)
+
+Previous pages:
+
+* [Notification](02-notification.md)
+* [Basic usage](01-basic-usage.md)
+* [README](../README.md)