Merge pull request #104 from jolicode/refacto-everything

Refactor public notifiers into internal drivers

.github/workflows/build-phar.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Build the PHAR
         uses: ./.github/actions/phar

.github/workflows/ci.yaml

@@ -30,7 +30,7 @@ jobs:
         - name: PHPStan
           uses: docker://oskarstark/phpstan-ga
           env:
-            REQUIRE_DEV: true
+              REQUIRE_DEV: true
 
     ci:
         name: Test PHP ${{ matrix.php-version }} ${{ matrix.name }}
@@ -71,27 +71,40 @@ jobs:
               run: |
                   composer update --prefer-dist --no-interaction ${{ matrix.composer-flags }}
 
-            - name: Install libnotify4 for LibNotifyNotifier
+            - name: Install libnotify4 for LibNotifyDriver
               run: |
                 sudo apt-get install -y --no-install-recommends --no-install-suggests libnotify4
 
             - name: Run Tests
               run: php vendor/bin/simple-phpunit
 
     phar:
-      name: Create a PHAR and ensure it is working
-      runs-on: ubuntu-latest
+        name: Create a PHAR and ensure it is working
+        runs-on: ubuntu-latest
 
-      steps:
-        - uses: actions/checkout@v3
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup PHP, with composer and extensions
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: ${{ matrix.php-version }}
+                  extensions: mbstring, xml, ffi
+                  ini-values: phar.readonly="Off"
+
+            - name: Install libnotify4 for LibNotifyDriver
+              run: |
+                sudo apt-get install -y --no-install-recommends --no-install-suggests libnotify4
 
-        - name: Build the PHAR
-          uses: ./.github/actions/phar
+            - name: Build the PHAR
+              uses: ./.github/actions/phar
 
-        - name: Execute the PHAR
-          run: |
-            tools/phar/build/jolinotif.phar --help
+            - name: Execute the PHAR
+              run: |
+                tools/phar/build/jolinotif.phar --help
 
-        - name: Trigger a notification
-          run: |
-            tools/phar/build/jolinotif.phar --title "Yolo" --body "Hello world!"
+            - name: Trigger a notification
+              run: |
+                # This command will fail because libnotify will fail to send a notification to a real desktop environment
+                # But we still ensure that everything else in the PHAR works
+                tools/phar/build/jolinotif.phar --title "Yolo" --body "Hello world!" --verbose | grep "Notification failed with LibNotifyDriver"

.github/workflows/release.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Build the PHAR
         uses: ./.github/actions/phar

CHANGELOG.md

@@ -2,10 +2,14 @@
 
 ## 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
 * Added libnotify based notifier for Linux through FFI
 * Changed TerminalNotifier to use contentImage option for icon instead of appIcon
 * Fixed phar missing some dependencies
+* 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

@@ -11,10 +11,10 @@
 # About JoliNotif
 
 JoliNotif is a cross-platform PHP library to display desktop notifications.
-It works on Linux, Windows or MacOS.
+It works on Linux, Windows or macOS.
 
-Requires PHP >= 7.4 (support for PHP 5 was available in version 1.x, for PHP 7.0
-and 7.1 in version < 2.1.0, for PHP 7.2 and 7.3 in version < 2.4.0).
+Requires PHP >= 8.1 (support for PHP 5 was available in version 1.x, for PHP 7.0
+and 7.1 in version < 2.1.0, for PHP 7.2 and 7.3 in version < 2.4.0, for PHP < 8.0 in version 2.6.0).
 
 > [!NOTE]
 > This library can not be used in a web context (FPM or equivalent). Use
@@ -30,26 +30,22 @@ composer require "jolicode/jolinotif"
 
 ## Usage
 
-Use the `NotifierFactory` to create the correct `Notifier` (adapted to your OS),
-then use it to send your notification:
-
 ```php
 include __DIR__.'/vendor/autoload.php';
 
 use Joli\JoliNotif\Notification;
-use Joli\JoliNotif\NotifierFactory;
+use Joli\JoliNotif\DefaultNotifier;
 
-// Create a Notifier
-$notifier = NotifierFactory::create();
+$notifier = new DefaultNotifier();
 
 // Create your notification
 $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') // Only works on macOS (AppleScriptNotifier)
-    ->addOption('sound', 'Frog') // Only works on macOS (AppleScriptNotifier)
+    ->addOption('subtitle', 'This is a subtitle') // Only works on macOS (AppleScriptDriver)
+    ->addOption('sound', 'Frog') // Only works on macOS (AppleScriptDriver)
 ;
 
 // Send it
@@ -68,7 +64,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,7 +23,9 @@
     "require": {
         "php": ">=8.1",
         "jolicode/php-os-helper": "^0.1.0",
-        "symfony/process": "^5.4 || ^6.0 || ^7.0"
+        "psr/log": "^3.0",
+        "symfony/process": "^5.4 || ^6.0 || ^7.0",
+        "symfony/deprecation-contracts": "^3"
     },
     "require-dev": {
         "symfony/finder": "^5.4 || ^6.0 || ^7.0",

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

@@ -1,10 +1,10 @@
 # Notification
 
 `Notification` is the main model of JoliNotif. It contains all the options
-that should be applied - if possible - by the notifier.
+that should be applied - if possible - by the driver.
 
 > **Note**
-> Notifiers are designed to handle the options they support and discard not
+> Drivers are designed to handle the options they support and discard not
 > supported ones gracefully without throwing any exception.
 
 Currently, only three options are supported but new ones could be added later.
@@ -15,12 +15,12 @@ Each option can be set via a setter on the `Notification` class.
 The body is the main message of the notification that you want to display.
 
 > **Note**
-> This is the only required option. Notifiers will throw an`InvalidNotificationException`
+> This is the only required option. Drivers will throw an`InvalidNotificationException`
 > if the body is empty or null.
 
 ## Title
 
-You can also optionally provide a title. Notifiers will certainly display the
+You can also optionally provide a title. Drivers will certainly display the
 title above the body, in bold.
 
 ## Icon
@@ -37,25 +37,25 @@ $notification->setIcon(__DIR__.'/Resources/icons/success.png');
 > care to extract this icon in your system temp directory to make it accessible
 > from command line executable.
 
-Not all notifiers support icon but again, you can safely add an icon to your
-notification since the notifier will discard it if not supported.
+Not all drivers support icon but again, you can safely add an icon to your
+notification since the driver will simply discard it if not supported.
 
 ## Options with restricted support
 
-Some options are available only on few notifiers. They can be configured
+Some options are available only on few drivers. They can be configured
 through the `addOption` method.
 
 ### Subtitle
 
-Only works with AppleScriptNotifier at the moment.
+Only works with AppleScriptDriver at the moment.
 
 ```php
 $notification->addOption('subtitle', 'This is a subtitle');
 ```
 
 ### Sound
 
-Only works with AppleScriptNotifier at the moment.
+Only works with AppleScriptDriver at the moment.
 
 Non-exhaustive list of sounds: Basso, Frog, Hero, Pop, Submarine, Blow, Funk,
 Morse, Purr, Tink, Bottle, Glass, Ping, Sosumi.
@@ -66,15 +66,15 @@ $notification->addOption('sound', 'Frog');
 
 ### Url
 
-Only works with TerminalNotifierNotifier at the moment.
+Only works with TerminalNotifierDriver at the moment.
 
 ```php
 $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)