Troubleshooting

Common Issues

Notification Not Being Sent

Symptoms: notify() is called but nothing happens — no email, no database entry, no admin notice.

Possible Causes:

1. Service provider not registered:

   // Ensure you've registered the provider:
   $app->register(new NotificationServiceProvider());
   

2. via() returns empty array:

   // Check your notification's via() method returns channels
   public function via(): array
   {
       return ['mail', 'database']; // Not empty
   }
   

3. Channel not registered in manager:

   $manager = $app->make(NotificationManager::class);
   var_dump($manager->channelNames());
   // Should show ['mail', 'database', 'admin_notice']
   

4. apply_filters not available: The Notifiable trait resolves the manager via apply_filters('wpzylos_resolve_service', ...). If WordPress isn't loaded, this returns null and notifications are silently skipped.

Emails Not Delivered

Symptoms: toMail() returns a valid MailMessage, but no email arrives.

Possible Causes:

1. Invalid email routing:

   // Ensure routeNotificationFor('mail') returns a valid email
   public function routeNotificationFor(string $channel): mixed
   {
       if ($channel === 'mail') {
           return $this->email; // Must be a non-empty string
       }
   }
   

2. wp_mail() failing silently:

   // Test wp_mail() independently
   $result = wp_mail('[email protected]', 'Test', 'Body');
   var_dump($result); // Should be true
   

3. toMail() returning null: The base Notification::toMail() returns null by default. Ensure your notification overrides it.

Database Notifications Not Saving

Symptoms: toDatabase() returns data, but nothing appears in the database.

Possible Causes:

1. Table not created:

   $installer = $app->make(DatabaseNotificationInstaller::class);
   $installer->install();
   

2. wpzylos-database not installed:

   composer require KYNetCode/wpzylos-database
   

3. toDatabase() returning empty array: If toDatabase() returns [], the DatabaseChannel skips the insert.
4. Invalid notifiable ID routing:

   // Ensure routeNotificationFor('database') returns a numeric ID
   public function routeNotificationFor(string $channel): mixed
   {
       if ($channel === 'database') {
           return $this->id; // Must be numeric
       }
   }
   

Admin Notices Not Appearing

Symptoms: toAdminNotice() returns a message, but nothing shows in the dashboard.

Possible Causes:

1. Not on an admin page: Admin notices only render on wp-admin pages via the admin_notices hook.
2. Targeting wrong user: The notice is stored per-user via transients. Ensure routeNotificationFor('admin_notice') returns the correct user ID.
3. Transient expired: Notices expire after 1 hour. If the user doesn't visit admin within that time, the notice is lost.
4. Already displayed: Notices are deleted from the transient after being rendered. They only show once.

Channel Failure Errors

Symptoms: Some channels work but others silently fail.

Solution: Listen for the wpzylos_notification_failed action:

add_action('wpzylos_notification_failed', function (
    $notification, $notifiable, $channelName, $exception
) {
    error_log("Channel [{$channelName}] failed: {$exception->getMessage()}");
    error_log($exception->getTraceAsString());
}, 10, 4);

Custom Channel Not Receiving Notifications

Symptoms: You registered a custom channel, but it never receives send() calls.

Checklist:

1. Ensure the channel is registered before sending:

   $manager->extend('slack', new SlackChannel($url));
   

2. Ensure the notification's via() includes the channel name:

   public function via(): array
   {
       return ['slack']; // Must match the name used in extend()
   }
   

3. Verify with hasChannel():

   var_dump($manager->hasChannel('slack')); // Should be true
   

PHPStan Errors for WordPress Functions

Symptoms: PHPStan reports "Function esc_html not found" or similar.

Solution: These are ignored in phpstan.neon. Ensure the ignoreErrors section includes all WordPress functions used:

parameters:
    ignoreErrors:
        - '#Function esc_html not found#'
        - '#Function wp_mail not found#'
        # ... etc

Or install szepeviktor/phpstan-wordpress for full WordPress stubs.