dakotajune / blueprint_observers
First-class Eloquent Observer generation for Laravel Blueprint.
Requires
- php: ^8.3
- ext-tokenizer: *
- illuminate/console: ^11.0|^12.0|^13.0
- illuminate/support: ^11.0|^12.0|^13.0
- laravel-shift/blueprint: ^2.10
Requires (Dev)
- orchestra/testbench: ^9.0|^10.0|^11.0
- pestphp/pest: ^3.0|^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
First-class Eloquent Observer generation for Laravel Blueprint,
with opt-in, build-time snippets that add code to the generated event methods, and a nova_observers:
block for observers that should only run for Laravel Nova requests.
composer require dakotajune/blueprint_observers --dev
Draft syntax
Observers live in their own top-level observers: block. Blueprint's built-in lexers ignore that
section, so nothing is decorated or reordered and a column called observer can never be created.
observers: Invoice: ~ # model=Invoice, events from config, no snippets PaymentObserver: model: Payment # optional; defaults to the name minus "Observer" (Admin\User is allowed) afterCommit: true # implements ShouldHandleEventsAfterCommit events: creating: [audit] # opt in to the "audit" snippet for this event only updated: # event with no snippets deleted: false # do not generate this event
- Snippets are always written inside
[...]. A bare value (creating: audit) is rejected with a hint. This also sidesteps Blueprint stripping leading-list dashes from the draft before YAML is parsed. event:orevent: truegenerates the event with no snippets;event: falseswitches it off (a previously generated, still-tagged method for it is removed on the next build).eventsmay also be a flow list ([creating, updated]) orcreating, updated.
Unknown events, unknown or unsupported snippets, and duplicates fail the build with a clear message.
Nova observers
Laravel Nova has its own way to register observers that fire only for Nova requests:
Laravel\Nova\Observable::make(Model::class, Observer::class). The nova_observers: block generates those
observers and does the registering.
nova_observers: Invoice: ~ # App\Nova\Observers\InvoiceObserver, events from config, no parent class PaymentObserver: model: Payment # same keys as `observers:` ... afterCommit: false events: creating: [audit] deleted: false extends: ~ # ... plus `extends`: extend the regular App\Observers\PaymentObserver Post: extends: App\Support\BaseObserver # or extend any class you like
model,afterCommitandevents(including snippets) behave exactly as inobservers:.extendsis optional. Leave it out (or writefalse) for no parent class;extends: ~(ortrue) means the regular observer with the same name; anything else is read as a fully qualified class name. It is applied when the file is first created; after that the class header is yours (you get a notice if the file does not extend what the draft asks for).- Unknown keys fail the build, so a typo like
extend:cannot be silently ignored. - Files are written to
app/Nova/Observers(nova_namespacein the config), with the same ownership rules as every other observer. They are not given#[ObservedBy]: that would make them run everywhere.
Registration: blueprintObservers()
blueprint_observers adds one method to your Nova service provider (app/Providers/NovaServiceProvider.php,
nova_provider in the config) and calls it from boot():
public function boot(): void { parent::boot(); $this->blueprintObservers(); } /** * Register the Nova-only observers generated by blueprint_observers. * * @generated blueprint_observers Rewritten on every build. Remove this tag to take ownership of the method. */ protected function blueprintObservers(): void { Observable::make(Post::class, PostObserver::class); }
Nothing else in the provider is touched. Specifically:
- The tagged method is rewritten in place with the Nova observers of the current build. Remove the tag to take
it over; it is never touched again (you are told, and the call to it is still kept in
boot()). - The call is appended as the last statement of
boot()only if it is not already there (a commented-out call does not count). If the provider has noboot(), one is added (callingparent::boot()when the class extends something). - Imports are only added. When a short name is already taken (say your own
App\Nova\Postresource), the generated code uses the fully qualified name instead. - If the provider file does not exist you get a notice and the observers are still written.
- Removing the whole
nova_observers:block takes the method, the call and the imports blueprint_observers added back out of the provider on the next build.
Heads up when using
extends: ~. Nova requests run both observers: the regular one (through#[ObservedBy]) and the Nova one (throughObservable). A Nova observer that extends the regular one inherits its handlers, so any event it does not override fires twice during Nova requests. Override the event (an empty method is enough) or extend a separate base class instead.
Snippets
A snippet is a named piece of code added to one observer method at build time. Snippets are always
opt-in, per event, from the draft. There is no runtime behaviour: what you see in the file is what runs.
They work the same in observers: and nova_observers:.
use Dakotajune\BlueprintObservers\Snippets\{Snippet, SnippetContext, SnippetOutput}; final class AuditSnippet implements Snippet { public function name(): string { return 'audit'; } public function supports(string $event): bool { return in_array($event, ['creating', 'updated'], true); } public function render(SnippetContext $context): SnippetOutput { return new SnippetOutput( "Log::info('{$context->event}', ['id' => {$context->variableName()}->getKey()]);", imports: ['Illuminate\\Support\\Facades\\Log'], ); } }
SnippetContext exposes the observer, model, event, the method's variable name, and (when the model is in
the draft) hasColumn() / columns(), so snippets can adapt to the model.
The registry
The registry is a single explicit list. Nothing is scanned or discovered; a snippet exists only if a service provider registered it:
public function boot(): void { $this->app->make(\Dakotajune\BlueprintObservers\Snippets\SnippetRegistry::class)->register(new AuditSnippet()); }
Duplicate names fail. Each snippet's output is syntax-checked on its own, so a broken snippet fails the build by name before anything is written. Snippets contribute method bodies and imports only (no constructor dependencies in v1).
Auto observers: unique enforcement
Turn on blueprint_observers.auto.enabled and nobody has to list observers for unique constraints. Every model
in the draft with a unique column (number: string unique) or a unique index (- unique: tenant_id, slug
under indexes:) gets an observer that runs the built-in unique snippet on creating and updating.
Each constraint lands in its own generated method, like every other generated piece:
public function creating(Invoice $invoice): void { $this->ensureUniqueNumber($invoice); $this->ensureUniqueTenantIdAndSlug($invoice); } protected function ensureUniqueNumber(Invoice $invoice): void { /* ... */ }
Failures throw a ValidationException ("The number has already been taken.") keyed on the first column.
Rows whose unique columns contain null are skipped (databases allow many NULLs), and an update that does not
touch the unique columns runs no query.
Rules:
- Switches are config:
auto.enabled(defaultfalse),auto.uniqueandauto.guards(both defaulttrue). - An observer you list yourself is never changed and suppresses the auto one for that model. Opt in there with
events: { creating: [unique], updating: [unique] }. - Pivot models are skipped. Auto observers are never after-commit, because the check must run before the write.
- Helpers are
@generated: dropping a constraint removes its helper; removing the tag takes the method over. uniqueis a reserved snippet name. It fails loudly on a model with no unique constraint.
Caveats: the database index stays the real guard (the check is not atomic), and the check is bypassed by
saveQuietly(), query-builder writes and upsert(). Soft-deleted rows count as taken, as in the index.
Turning auto off later does not delete observers already generated; blueprint:erase does.
Guards: what an observer does about relationships on delete
A guard decides what happens to related rows when the model is deleted. Three actions:
| action | does |
|---|---|
restrict |
blocks the delete with a ValidationException while related rows exist |
cascade |
deletes the related rows (their own model events fire) |
nullify |
sets the related rows' foreign key to null |
observers: Invoice: guards: payments: restrict # name of the relationship method on the model line_items: { action: cascade, trashed: ignore } notes: nullify comments: false # switch off a guard that `auto` would add auto: true # also derive guards from hasMany / hasOne (same as `guards: auto`)
guards:also takes a flow list ([payments, notes]) orauto. A relationship with no action (payments:orpayments: true) is worked out like an auto guard. Names are camelised (line_itemsislineItems).- Guards are written into
deleting, which is generated even when the draft does not list it. Each relationship gets its own tagged method,restrictPayments(),nullifyNotes(),cascadeLineItems(), called fromdeletingin the order restrict, nullify, cascade, so a refusal always comes before anything is changed. Guards run before any snippets ondeleting. - They work in
nova_observers:too.
Auto-derived guards
auto.guards (config, on by default, needs auto.enabled) gives every model in the draft that has hasMany or
hasOne relationships and no listed observer an observer with a guard per relationship. guards: auto does the
same inside an observer you list. The action comes from the child's foreign key, if the draft says one:
ondelete:cascade is cascade, ondelete:null is nullify, ondelete:restrict / no_action is restrict.
With no ondelete: it is auto.guard_default (restrict). Only hasMany and hasOne are derived, and only for
plain references (Payment, Payment:alias, Payment.key:alias). Anything else (morph relations, fully
qualified names, belongsToMany) can be guarded by naming the method. cascade and nullify refuse a
relationship the draft shows to be anything but hasMany / hasOne; restrict works on any relationship.
Trashed rows
If the related model uses soft deletes, trashed rows count by default: they block a restrict, and cascade
and nullify include them (cascade force-deletes them, otherwise the foreign key would still point at the deleted
row). To ignore them, set guards.trashed to ignore in config, or per guard with trashed: ignore. When the
related model is not in the draft, the generated code checks for soft deletes at runtime.
Soft-deleting models
Like a foreign key, a guard acts when the row is really removed. On a model that uses soft deletes it is skipped for
a soft delete and runs on forceDelete().
Caveats
restrictis a check, not a lock: the database foreign key stays the real guard. Guards do not run for mass deletes (Model::query()->delete()), which fire no model events.nullifyis a singleUPDATEon the related rows (no model events on them), and the foreign key column must be nullable.cascadeloads the related models and deletes them one by one, so their own observers and guards run. For very large relations use the database'sondelete:cascadeinstead.- An observer that holds guards (or the
uniquesnippet) is never generated as after-commit, whateverafterCommitsays: the check must run before the write, and after-commit handlers are deferred until the transaction has finished.
Validation
Observers can validate their model with Laravel's own validator before it is saved. The rules are derived from
the columns under models: and can be overridden per observer, in observers: and in nova_observers:.
Turn it on for every observer (config validation.enabled, off by default), or per observer with a validation:
key:
observers: Invoice: validation: number: [required, string, max:20] # replaces the derived rules of the column notes: [derived, min:3] # the derived rules, plus these legacy_code: false # no validation for this column Payment: validation: true # derived rules only, even with validation.enabled off Tag: validation: false # never, even with validation.enabled on
Rules are written as a list, or as a required|string|max:20 string. A rule that contains a comma (in:a,b) goes
in quotes inside a list (['in:a,b']) or in the string form; a rule that contains | (a regex, say) needs the list.
What is derived
| column | rules |
|---|---|
nullable |
nullable |
| not nullable, no default | required (a default means the database fills it in) |
string, char |
string, max:<length> (255 by default) |
text, mediumText, tinyText |
string, max:<bytes> (longText: just string) |
| integer types | integer, min/max of the column type (unsigned: min:0) |
id, foreignId (not the key) |
integer, min:1 |
decimal:8,2 |
numeric, decimal:0,2, min/max that fit the column |
float, double |
numeric |
boolean |
boolean |
date, dateTime, timestamp |
date |
uuid, ulid, ipAddress, macAddress |
uuid, ulid, ip, mac_address |
enum:a,b |
Rule::in(['a', 'b']) |
Not validated: the primary key, auto increments, created_at / updated_at / deleted_at. Types with no useful
rule (json, binary, time, geometry ...) only get required / nullable. Uniqueness is not validation here: use the
unique snippet or auto.unique.
What gets generated
saving calls $this->validateAttributes($invoice) first, and two tagged methods hold the rest:
protected function validationRules(Invoice $invoice): array { return [ 'number' => ['required', 'string', 'max:255'], 'status' => ['required', Rule::in(['draft', 'issued', 'paid'])], ]; } protected function validateAttributes(Invoice $invoice): void // Validator::make(...), throws ValidationException
Take over validationRules() (remove its tag) to hand-tune the rules; everything else keeps being maintained.
Nova
Failures are a plain Illuminate\Validation\ValidationException, so Nova (and any form request) shows them on the
fields. To make that work well:
- Errors are keyed by column name (
number), which is how Nova names its fields. A*_idcolumn's errors are also keyed by the relationship (team_idandteam), because Nova names aBelongsTofield after the relationship. - An update validates only the attributes that changed. A legacy row with a bad value in a column you are not editing does not block saving another one.
- A create validates the attributes the model holds, so a column with a database default is not "required".
- Nova observers (
nova_observers:) never inheritvalidation.enabled: the regular observer already validates Nova's saves. They validate only with their ownvalidation:key, typically for stricter, Nova-only rules. Note that a Nova observer thatextends: ~the regular one and does not sayvalidation:inherits itssavinghandler like any other.
Auto observers
With auto.enabled and validation.enabled, models in the draft that have no listed observer get one that only
validates (auto.validation, on by default, can switch that part off). Pivot models are skipped.
Caveats
- Rules derive from the draft only. A column the draft does not know about is not validated; list it under
validation:. - The raw attribute values are validated (before casts and accessors), which is what the database receives.
- Validation does not run for
saveQuietly(), mass updates or query-builder writes. - Like every blocking check, an observer with validation is never generated as after-commit.
Ownership: what blueprint_observers will and will not touch
Every method blueprint_observers writes carries a docblock tag:
/** * Handle the Invoice "creating" event. * * @generated blueprint_observers Rewritten on every build. Remove this tag to take ownership of the method. */
- Tagged methods are the generator's. They are rewritten in place on every build, and deleted when their event leaves the draft.
- Everything else is yours and is never modified or removed: untagged methods, properties, constants, traits, comments, and your imports. Imports are only ever added.
- If you already have an untagged method named after an event, it is left alone and you get a notice.
- Remove the tag to take a method over; it is never touched again.
- The class header is managed only for
ShouldHandleEventsAfterCommit(followsafterCommit). Other interfaces, parents and traits are left alone. - In the Nova provider the same rule applies to exactly one method,
blueprintObservers(), and one statement inboot()(see above).
Rebuilds are therefore surgical edits of the existing file, not Blueprint's usual overwrite.
blueprint:build
- Writes
app/Observers/{Name}.php(stub:--tag=blueprint-observers-stubs, only{{ namespace }}and{{ class }}). - Writes
app/Nova/Observers/{Name}.phpfornova_observers:(stubnova_observer.stub, which also has{{ extends }}) and registers them in the Nova provider. - Adds
#[ObservedBy(...)]to the model when its file exists (attach_attribute). Existing attributes, docblocks,final/abstract/readonly, aliased imports and short-name clashes are handled; an existing#[ObservedBy]is merged, never duplicated; reruns change nothing. - Reports observers it created under
createdand everything else it edited underupdated; honours--only=observers/--skip=observersand, for the Nova block,--only=nova_observers/--skip=nova_observers. - Prints notices (left-alone methods, skipped imports, a missing Nova provider) after the command.
blueprint:erase
Erase deletes everything under created in .blueprint. To keep that from destroying your code,
blueprint_observers acts just before erase starts:
- strips the
#[ObservedBy]attributes and imports it added to models; - strips the generated
blueprintObservers()method, its call inboot()and the imports it added from the Nova provider, so Nova never registers an observer class that erase is about to delete; - strips the
@generated blueprint_observersmethods from each observer it touched; - if an observer still holds your code (or was not created by blueprint_observers), removes it from
.blueprint'screatedlist so erase skips it..blueprintis backed up first to.blueprint.bak-YYYYmmddHHMMSSand is only edited if the backup succeeds.
Observers with nothing of yours left stay on the list and are deleted by erase as normal. blueprint_observers
records its edits in .blueprint_observers (latest build only, like .blueprint) and removes it on erase.
Config (--tag=blueprint-observers-config)
| key | default |
|---|---|
default_events |
['creating', 'updating', 'deleted'] |
after_commit |
true |
attach_attribute |
true |
namespace |
Observers (relative to blueprint.namespace) |
nova_namespace |
Nova\Observers (relative to blueprint.namespace) |
nova_provider |
Providers\NovaServiceProvider (relative to blueprint.namespace) |
auto.enabled |
false |
auto.unique |
true |
auto.guards |
true |
auto.guard_default |
'restrict' |
auto.validation |
true |
validation.enabled |
false |
guards.trashed |
'block' (or 'ignore') |
manifest |
.blueprint_observers |
Known limits
- Source edits assume LF line endings.
- Grouped imports (
use A\{B, C};) are not tracked when checking for name clashes. - Changing a snippet's output only reaches methods that still carry the
@generatedtag. extendson a Nova observer is applied only when its file is created.- Only one Nova provider is managed (
nova_provider). - Auto observers are for regular observers only (not
nova_observers), and only cover models defined in the draft. - Guard method names are derived the way Blueprint names
hasMany/hasOne/belongsToManymethods; a custom method name Blueprint cannot see has to be written out inguards:.
Tests
composer install && vendor/bin/pest