Download the PHP package ilbronza/schedules without Composer

Schedules

Scadenze e soglie di notifica per Laravel, basate su un valore che avanza nel tempo (chilometri, date, ore, pezzi, …).

Il package non calcola “quanto manca” da solo: legge il valore corrente dal modello host, lo confronta con una scadenza, e quando una soglia è raggiunta notifica i ruoli configurati.

Se stai arrivando da v2.5.1, leggi anche UPGRADING.md.

Indice

1. A cosa serve
2. I pezzi del dominio
3. Installazione
4. Configurazione dell’applicazione host
5. Rendere un modello schedulabile
6. Creare un tipo di scadenza
7. Soglie di notifica
8. Applicare le scadenze
9. Valutare le scadenze (cron)
10. Segnare una scadenza come gestita
11. Leggere le scadenze da un modello
12. Stati
13. Interfaccia HTTP
14. Soft delete
15. Personalizzazioni
16. Comportamento fail-fast

A cosa serve

Esempio classico: un veicolo ha un odometro. Vuoi:

• una revisione ogni 20.000 km;
• un avviso 2.000 km prima;
• poi un reminder ogni 500 km fino a 500 km dalla scadenza;
• quando l’operatore ha fatto la revisione, chiudere la scadenza.

Lo stesso schema vale per date (assicurazione tra 365 giorni, avviso a 30), ore di lavoro, pezzi prodotti, e qualunque unità gestita da ilbronza/measurementunits.

Il flusso è sempre questo:

I pezzi del dominio

Una schedule vive su un morph (schedulable_type / schedulable_id). Il valore corrente non è salvato sulla schedule: viene riletto dal modello a ogni valutazione.

Installazione

Dipendenze runtime dichiarate in composer.json: Laravel 11, Carbon 3, Spatie Activitylog e Permission, e i pacchetti IlBronza crud, buttons, datatables, form, formfield, measurementunits, notifications.

Prima di lanciare le migration di Schedules deve già esistere la tabella Laravel notifications (di solito creata da ilbronza/notifications). Le scheduled notification tengono una foreign key su notifications.id.

Configurazione dell’applicazione host

Il package non conosce i modelli del progetto. Pubblica config/schedules.php e dichiara:

Punti fermi:

• Ogni classe in applicableTo deve implementare IlBronza\Schedules\Contracts\Schedulable.
• L’alias (vehicles) è lo slug usato nelle URL. Non mettere mai un FQCN PHP in una route.
• Un FQCN può comparire una sola volta: alias duplicati o ambigui lanciano RuntimeException.
• Se AccountManager è installato e notifications.roleModel è null, si usa il role model di AccountManager.
• All’avvio l’applicazione valida la config. Classi inesistenti o non Schedulable fanno fallire il boot. Per disattivare (sconsigliato): 'validateConfiguration' => false.

Rendere un modello schedulabile

Getter allowlistati

Il tipo di scadenza indica come leggere il valore, in uno di questi due modi:

Se sono presenti entrambi, vince method. In ogni caso il metodo deve stare in $allowedScheduleValueMethods. Un getter non allowlistato lancia RuntimeException (e in HTTP create/update del tipo dà 422).

Non è un accessor Eloquent: source = current_km risolve getCurrentKm(), non getCurrentKmAttribute().

Metodi opzionali del trait

Scope per l’applicazione da UI

getSchedulableElementsQuery() chiama scope{Studly(nome del Type)}. Se manca, l’indice di applicazione lancia un’eccezione. Se vuoi tutti i record:

Applicando le scadenze da codice (ScheduleApplicatorHelper) lo scope non è necessario.

Creare un tipo di scadenza

Un Type è il template. Campi rilevanti:

models deve:

• essere un array non vuoto;
• usare FQCN presenti in schedules.applicableTo;
• avere source e/o method;
• risolvere a getter allowlistati.

Esempio in codice:

roles accetta anche role_id o id come chiave dell’entry. Entry malformate o vuote lanciano RuntimeException in valutazione.

Dalla UI: Impostazioni → Scadenze → Tipologie (/schedules-management/types).

Soglie di notifica

Una TypeNotification appartiene a un tipo e definisce quando avvisare rispetto alla deadline della schedule.

type_id è immutabile dopo la creazione.

Vincoli (save + form HTTP 422)

• repeat_every e l’unità di ripetizione stanno insieme: uno senza l’altro è errore.
• last_repetition richiede la ripetizione.
• repeat_every deve essere numerico e > 0.
• last_repetition deve essere numerico, ≥ 0, e più vicino alla deadline di before (last_repetition ≤ before).

Esempio numerico

Tipo con validity = 20000 km, veicolo a 90.000 km:

• schedule: starting 90000, deadline 110000
• soglia before = 2000 → prima notifica a 108000
• repeat_every = 500, last_repetition = 500 → invii a 108000, 108500, 109000, 109500

Senza ripetizione la soglia parte una sola volta, anche se l’evaluator gira di nuovo.

Ogni invio viene scritto in schedules__scheduled_notification_dispatches. Sulla scheduled notification restano solo notification_id e last_dispatched_value dell’ultimo invio (idempotenza e calcolo del prossimo intervallo).

Il messaggio di default:

La scadenza "Revisione" per "AB123CD" ha raggiunto una soglia di notifica.

Applicare le scadenze

ScheduleApplicatorHelper crea (o aggiorna) la schedule e tutte le soglie in una transazione. O tutto o niente.

Da codice

applicate* (senza findOr) crea sempre una schedule nuova. Se allow_multiple è false e ne esiste già una corrente, lancia RuntimeException.

Dalla UI

1. Apri il tipo → Applica.
2. Scegli il modello (vehicles).
3. Seleziona gli elementi e conferma.

La route usa l’alias, non la classe PHP:

/schedules-management/types/applicate/{type}/models/vehicles

Valutare le scadenze (cron)

Il package registra schedules:evaluate e, di default, lo mette nello scheduler Laravel ogni minuto (withoutOverlapping). L’host deve comunque far girare lo scheduler:

A mano:

Per invalidare manualmente le schedule:

type e --all sono alternativi. L'invalidazione soft-delete di ogni schedule e delle relative scheduled notification; non modifica expired_at e non fa force-delete, quindi resta possibile il ripristino.

Per ogni schedule corrente (non expired, non managed) l’evaluator:

1. rilegge il valore corrente dal modello (getter allowlistato);
2. per ogni scheduled notification ancora eligible, se la soglia è raggiunta invia la notifica ai ruoli del tipo;
3. se la deadline della schedule è raggiunta, marca expired_at e fa scadere le soglie ancora pending.

Le soglie già dispatched o managed non vengono toccate quando la schedule scade.

L’esecuzione è fail-fast: valore illeggibile, ruoli mancanti, unità di ripetizione incompatibile, errore di dispatch → il comando si ferma.

Il valore corrente della schedule è anche esposto come attributo current_value, cachato 60 secondi.

Per disattivare lo schedule automatico: 'evaluator.enabled' => false.

Segnare una scadenza come gestita

Quando l’intervento è stato fatto (revisione eseguita, rinnovo, …) si marca la schedule come managed. La transizione è transazionale: lo stesso managed_at va sulla schedule e su tutte le scheduled notification ancora senza timestamp. Ripetere l’azione non cambia il timestamp originale.

Dalla tabella scadenze: azione singola o “Segna come gestite” sulla selezione.

Una schedule managed non viene più valutata.

Leggere le scadenze da un modello

Metodi del trait InteractsWithSchedule:

Sulla schedule:

getPercentageValidity() lancia se starting e deadline coincidono (span zero).

Stati

Schedule

Precedenza: managed > expired > current.

Scope: Schedule::current(), notExpired(), notManaged(), byType($type).

Scheduled notification

Precedenza: managed > expired > dispatched > pending.

Una soglia dispatched non viene sovrascritta a expired. markExpired() su una notifica non pending lancia RuntimeException.

Le soglie repeating restano eligible dopo il primo invio: lo scope pending() include anche quelle già dispatchate se il tipo ha repeat_every + unità.

Interfaccia HTTP

Prefisso URL: /schedules-management. Prefisso nomi: ibSchedules. (config routePrefix).

Middleware: web, auth, schedules.roles. I ruoli ammessi sono defaultRoles, con override per route in routeRoles. Senza autenticazione o senza ruolo: accesso negato.

Il menu (se il package Menu è registrato) aggiunge sotto Impostazioni: elenco tipologie e elenco scadenze.

Non c’è create/edit di una Schedule da form: si crea solo applicando un tipo.

Soft delete

• Cancellare una Schedule soft-delete delle sue scheduled notification; il restore le ripristina.
• Force-delete di una schedule force-delete anche le notification già soft-deleted.
• Un Type non si cancella se esistono schedule non cancellate che lo referenziano. Se la cancellazione è permessa, le type notification cascano.
• Una TypeNotification non si cancella se esistono scheduled notification che la referenziano.

Tentativi non validi: RuntimeException, non silenzio.

Personalizzazioni

Dispatcher di notifiche

Il default è IlBronzaScheduleNotificationDispatcher: invia ScheduleThresholdReachedNotification al primo ruolo del tipo, poi ChildDatabaseNotification agli altri, tramite ilbronza/notifications.

Per sostituirlo:

dispatch() deve restituire l’id della riga in notifications.

FileCabinet (legacy)

Se è installato ilbronza/filecabinet, le Dossierrow di tipo expiration-date possono fornire il valore corrente senza implementare Schedulable. È un ponte esplicito, non il percorso consigliato per i modelli nuovi.

Modelli del package

In config/schedules.php → models.*.class puoi estendere Schedule, Type, ecc. La classe deve discendere da quella del package. La validazione di boot lo verifica.

Comportamento fail-fast

Il package non ignora gli errori di dominio. In particolare:

Questo è intenzionale: una scadenza silenziosa è peggio di un job che fallisce in evidenza.