Getting Started

Minimal Setup

Install Dependencies

composer require componist/reminder-notifications
composer dump-autoload
php artisan migrate

Run migrations to create the reminder_notifications table.

Publish Config & Assets

php artisan vendor:publish --provider="Componist\ReminderNotifications\ReminderNotificationsServiceProvider" --tag="config"
php artisan vendor:publish --provider="Componist\ReminderNotifications\ReminderNotificationsServiceProvider" --tag="views"

Publish config (config/reminder-notifications.php) and views to customize templates.

Configure Mail & Queue Ensure your .env has valid mail settings (e.g., MAIL_MAILER=smtp) and a queue worker running:
```
php artisan queue:work
```
First Use Case: Create a Reminder
- Visit /dashboard/reminder-notification/create (authenticated route).
- Fill in:
  - Recipient Email (or use a model-based approach via ReminderNotification::create()).
  - Type (daily/monthly/yearly).
  - Time/Day (e.g., 14:00 for daily, 15 for monthly).
  - Message (custom email template or default).
- Save. The package queues the job for the specified trigger time.

Implementation Patterns

Core Workflows

1. Model-Based Reminders (Recommended)

Use the ReminderNotification model to attach reminders to Eloquent models (e.g., User, Order):

use Componist\ReminderNotifications\Models\ReminderNotification;

// Attach a yearly reminder to a User
$user->reminders()->create([
    'type' => 'yearly',
    'day' => 15,
    'month' => 12, // December 15th
    'message' => 'Happy Anniversary!',
    'trigger_at' => now()->addYear(), // Optional: Override auto-calculation
]);

Trigger Logic: The package auto-calculates trigger_at based on type/day/month during job dispatch.

2. Livewire Dashboard Integration

Customize the Dashboard: Extend the default Livewire component (ReminderNotificationDashboard) by publishing views and overriding methods in a child component:

namespace App\Livewire;

use Componist\ReminderNotifications\Livewire\ReminderNotificationDashboard as BaseDashboard;

class CustomReminderDashboard extends BaseDashboard {
    public function mount() {
        parent::mount();
        // Add custom logic (e.g., filter by user role)
    }

    public function updatedSearch($search) {
        $this->reminders = $this->reminders->where('message', 'like', "%{$search}%");
    }
}

'livewire' => App\Livewire\CustomReminderDashboard::class,

Accessing Data: Use Livewire’s $reminders property to display/manage reminders in a table or card layout. Example:

@foreach($reminders as $reminder)
    <div>
        {{ $reminder->type }} on {{ $reminder->trigger_at->format('Y-m-d H:i') }}
        <button wire:click="edit({{ $reminder->id }})">Edit</button>
    </div>
@endforeach

3. Email Templates

Default Templates: Located in resources/views/remindernotifications/emails. Override by publishing views:
```
php artisan vendor:publish --tag="remindernotifications-views"
```
Customize default.blade.php or create type-specific templates (e.g., monthly.blade.php).

Dynamic Data: Pass variables via the ReminderNotification model:

$reminder->data = ['user_name' => $user->name]; // Available in email template as `$data`

4. Scheduling Jobs

Manual Dispatch: Trigger a reminder immediately (e.g., for testing):
```
ReminderNotification::dispatchNow($reminderId);
```
Queue Workers: Ensure your queue worker processes RemindNotificationJob:
```
php artisan queue:work --queue=reminders
```
Configure queue connection in .env (e.g., QUEUE_CONNECTION=database).

Integration Tips

Laravel Events

Listen for reminder events to extend functionality:

// In EventServiceProvider
protected $listen = [
    \Componist\ReminderNotifications\Events\ReminderSent::class => [
        \App\Listeners\LogReminderSent::class,
    ],
];

API Endpoints

Expose a JSON API for reminders:

Route::get('/api/reminders', function () {
    return ReminderNotification::with('recipient')->get();
});

Testing

Use the ReminderNotification facade to test job dispatch:

$this->artisan('queue:work --once')
     ->expectsQuestion('Continue processing jobs? (yes/no)', 'no');

$this->assertDatabaseHas('reminder_notifications', [
    'type' => 'daily',
    'trigger_at' => now()->addHours(1),
]);

Gotchas and Tips

Pitfalls

Queue Stuck Jobs
- Issue: Reminders fail silently if the queue worker crashes.
- Fix: Monitor failed jobs:
```
php artisan queue:failed-table
php artisan queue:retry <job-id>
```
- Config: Set REMINDER_NOTIFICATIONS_RETRY_AFTER in .env to control retry delays.
Timezone Mismatches
- Issue: trigger_at uses the server’s timezone. If users are in different timezones, reminders may send at unexpected times.
- Fix: Store reminders in UTC and convert to user timezone in the dashboard:
```
$reminder->trigger_at->setTimezone($user->timezone);
```
Livewire Component Caching
- Issue: Changes to the Livewire dashboard may not reflect due to caching.
- Fix: Clear Livewire view cache:
```
php artisan livewire:discover
php artisan view:clear
```
Recipient Validation
- Issue: The package assumes valid email addresses. Invalid emails may cause job failures.
- Fix: Validate emails before creating reminders:
```
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    throw new \InvalidArgumentException('Invalid email');
}
```
Migration Conflicts
- Issue: Custom migrations for reminder_notifications may conflict with package updates.
- Fix: Use Schema::hasTable() to check before running migrations:
```
if (!Schema::hasTable('reminder_notifications')) {
    // Run migrations
}
```

Debugging Tips

Log Job Dispatch Add a listener to log when reminders are queued:

ReminderNotification::created(function ($reminder) {
    \Log::info("Queued reminder for {$reminder->recipient_email} at {$reminder->trigger_at}");
});

Inspect Queue Jobs List pending jobs:

php artisan queue:list
php artisan queue:work --once --verbose

Test with Immediate Triggers Use dispatchNow() to test email delivery without waiting:
```
ReminderNotification::dispatchNow($reminderId);
```

Extension Points

Custom Reminder Types Extend the ReminderNotification model to add custom types (e.g., "weekly"):

// In a service provider
ReminderNotification::addType('weekly', function ($dayOfWeek) {
    return now()->next($dayOfWeek)->startOfDay();
});

Webhook Notifications Add a webhook listener to notify external services when reminders are sent:

ReminderSent::dispatch($reminder)
    ->then(function () {
        Http::post('https://external-api.com/webhook', [
            'event' => 'reminder_sent',
            'data' => $reminder->toArray(),
        ]);
    });

Bulk Actions Add bulk delete/edit to the Livewire dashboard:

// In CustomReminderDashboard
public function bulkDelete() {
    ReminderNotification::whereIn('id', $this->selected)->delete();
    $this->emit('alert', 'Reminders deleted!');
}

Recipient Models Extend the recipient_email

Reminder Notifications Laravel Package