Jolinotif Laravel Package

Getting Started

Install the package via Composer:

composer require jolicode/jolinotif

Then get started with a minimal usage example in a CLI script:

use Joli\Notif\NotifierFactory;

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

$notifier = NotifierFactory::create();
$notifier->notify('Build Complete', 'All tests passed! ✅', __DIR__ . '/assets/icon.png');

Start by testing with php -r "..." in your terminal to verify notifications appear. The factory automatically detects your platform (macOS, Linux, Windows/WSL) and selects the appropriate backend.

Note (v3.3.0): PHP 8.5 is now fully supported. As of this release, PHP 8.2 is no longer supported—ensure your project targets PHP 8.3, 8.4, or 8.5. Composer will enforce this via ^8.3 in the package requirements.

Implementation Patterns

• Dependency Injection: Inject the NotifierInterface (resolved via NotifierFactory::create()) into service classes (e.g., BuildRunner, DeploymentTask) instead of coupling to OS-specific logic.
• Conditional Notifications: Wrap notifications in if ($notifier->isSupported()) for environments like headless servers or CI where desktop notifications may be unavailable or undesirable.
• Custom Icons & Actions: Use named parameters for richer notifications:

  $notifier->notify(
      title: 'Deployment Success',
      body: 'Release v2.4 deployed to production 🚀',
      icon: '/opt/app/assets/rocket.png',
      actionLabel: 'View Logs',
      actionCallback: fn() => shell_exec('tail -f /var/log/app.log')
  );
  

• Async/Background Scripts: Pair with nohup or background jobs to notify long-running processes (e.g., php generate-report.php &).
• Configurable Backends: Override default driver priority via environment variables or config:

  $notifier = NotifierFactory::create(['drivers' => ['win', 'libnotify', 'terminal']]);
  

Gotchas and Tips

• Linux Limitations: On Linux, notify-send is the fallback driver, but custom icons require absolute paths. Relative paths (e.g., ./icon.png) often fail silently—use realpath().
• Windows/WSL Quirks: Native Windows notifications require Windows 10+; WSL users may need wslu installed (wslnotify backend). Ensure wslview is available for icon paths.
• Silent Failures: Notifications fail silently if dependencies are missing. Always use isSupported() before notifying in production scripts.
• Icons: macOS requires .icns, Linux expects .png, and Windows uses .ico. Normalize via a helper:

  $icon = match(PHP_OS_FAMILY) {
      'Darwin' => realpath(__DIR__ . '/icon.icns'),
      'Linux' => realpath(__DIR__ . '/icon.png'),
      'Windows' => realpath(__DIR__ . '/icon.ico'),
      default => null,
  };
  

• Extensibility: Add custom backends by implementing DriverInterface and registering via NotifierFactory::registerDriver($driver). Useful for team-specific integrations (e.g., Mattermost, Slack desktop notifications).
• Testing: Stub the Notifier in unit tests by injecting a mock NotifierInterface—no OS dependencies needed.
• PHP Version Compatibility (v3.3.0): If your project uses PHP 8.2, upgrade to PHP 8.3+ before updating to v3.3.0. The jolicode/jolinotif package now requires ^8.3. Check composer.json for require.php constraints, and update CI pipelines accordingly.