Events, Jobs, Schedules and Notifications

React to things that happen elsewhere in TruCMS, move slow work out of the request, and run housekeeping on a timer. All of it is wired from your plugin's service provider.

Events you can listen to

These are the events the current code actually fires. Listening to anything else in the codebase is not safe until you have checked that something dispatches it.

Listening from a plugin

For a handful of listeners, register them in boot():

Modules/Testimonials/app/Providers/TestimonialsServiceProvider.php

use Illuminate\Support\Facades\Event;
use Modules\Booking\Models\Booking;
use Modules\Testimonials\Listeners\AskForTestimonial;
use Nwidart\Modules\Facades\Module;

public function boot(): void
{
    parent::boot();

    Event::listen(TicketCloseEvent::class, NotifyTicketClosed::class);

    // Only touch another module's classes when that module is enabled.
    if (Module::isEnabled('Booking')) {
        Booking::updated(function (Booking $booking): void {
            if ($booking->wasChanged('status') && $booking->status === 'completed') {   // AppointmentStatus::Completed
                app(AskForTestimonial::class)->handle($booking);
            }
        });
    }
}

For many listeners, add a child EventServiceProvider with a $listen map and list it in your provider's $providers array, as Booking does (Modules/Booking/app/Providers/EventServiceProvider.php).

• Guard references to optional modules with Module::isEnabled() or class_exists(). If your plugin cannot work at all without one, declare it in requires instead.
• Listeners run inside the request that fired the event unless the listener implements ShouldQueue. Keep them quick, or queue them.
• Prefer ShouldHandleEventsAfterCommit (or the event's own after-commit behaviour) when you react to data written in a transaction; the core ticket observer and TruPayments refunds do.

Firing your own events

Define plain event classes in app/Events with Dispatchable and SerializesModels, and dispatch them with MyEvent::dispatch($model). Document them for other plugin authors, and keep the payload stable once released.

Background jobs

Modules/Testimonials/app/Jobs/SendTestimonialRequest.php

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class SendTestimonialRequest implements ShouldQueue
{
    use Queueable;

    public function __construct(public int $customerId) {}    // pass ids, not models with big relations

    public function handle(): void
    {
        // ...
    }
}

// dispatching from a transaction: wait until it commits
SendTestimonialRequest::dispatch($customer->id)->afterCommit();

• Booking follows this pattern: SendBookingNotificationJob and SyncBookingIntegrationsJob take ids and are dispatched afterCommit().
• Because sync runs the job immediately, an exception in the job surfaces in the visitor's request. Catch and report failures that should not break the page.
• There is no broadcasting transport (BROADCAST_DRIVER=log, no Echo or Pusher client). Do not build features that need real-time pushes without adding one.

Scheduled tasks

Override configureSchedules() in your module provider. The base provider calls it once the application has booted, so your tasks appear in php artisan schedule:list only while the plugin is enabled.

Modules/Testimonials/app/Providers/TestimonialsServiceProvider.php

use Illuminate\Console\Scheduling\Schedule;
use Modules\Testimonials\Console\PruneRejectedTestimonials;

protected array $commands = [
    PruneRejectedTestimonials::class,          // registered by parent::boot()
];

protected function configureSchedules(Schedule $schedule): void
{
    $schedule->command('testimonials:prune-rejected')->dailyAt('04:10')->withoutOverlapping();
}

Name commands {alias}:{verb}-{noun}, use withoutOverlapping() for anything that can run long, and pick a time that does not collide with the bundled tasks:

None of this runs unless the server's cron calls php artisan schedule:run every minute; the end-user installation guide tells site owners how to set it up. dotartisan:tickets:autoclose exists but is not scheduled by default.

Notifications and mail

• Notifications use the mail and database channels (the notifications table exists). Logged-in visitors see database notifications in their account area.
• Mail settings live in Settings → Mail and are written to .env. A fresh site uses the log mailer until the owner configures SMTP, so never treat "mail sent" as "mail delivered".
• Put the text of your notifications in your language files, so sites can translate them.

Testing

use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\Event;

it('queues a thank-you job when a testimonial is published', function (): void {
    Bus::fake();

    $testimonial = Testimonial::factory()->create(['is_published' => false]);
    $testimonial->update(['is_published' => true]);

    Bus::assertDispatched(SendThankYou::class);
});

it('registers the prune task', function (): void {
    $this->artisan('schedule:list')->expectsOutputToContain('testimonials:prune-rejected');
});

The test environment forces QUEUE_CONNECTION=sync, so jobs you do not fake run inline. Booking has no model factories; when your plugin reacts to bookings, create the rows you need in the test itself.