Nova Resource Notes Laravel Package

Getting Started

This is a small, single-purpose package: it bolts a notes panel onto a Nova resource so admins can leave free-text commentary against records. Treat it as a starting point rather than a polished dependency — last release was February 2019, so budget time to read the source before you commit.

1. Check compatibility before anything else. Open the package's composer.json on GitHub and compare against your stack. A 2019 release almost certainly targets Nova 1.x/2.x and Laravel 5.5–5.8. If you're on Nova 4/5 (Vue 3, restructured field API) the shipped JS component will not mount, and no amount of config will fix it.

2. Install.

composer require digitalcloud/nova-resource-notes

3. Register the provider if it isn't auto-discovered. Older packages predate Laravel package discovery conventions; check the README and src/ for a *ServiceProvider. If it's missing from discovery, add it to config/app.php:

'providers' => [
    // ...
    DigitalCloud\NovaResourceNotes\NovaResourceNotesServiceProvider::class,
],

4. Publish and run migrations.

php artisan vendor:publish --provider="DigitalCloud\NovaResourceNotes\NovaResourceNotesServiceProvider"
php artisan migrate

Inspect the published migration before running it — see the gotchas below on table naming and polymorphic columns.

5. Attach it to a resource. Look in src/ for the field class (likely something like ResourceNotes) and add it to the fields() method of a resource, typically on the detail view only:

public function fields(Request $request)
{
    return [
        ID::make()->sortable(),
        Text::make('Name'),
        // ...
        ResourceNotes::make('Notes'),
    ];
}

First use case to validate with: an internal CRM Customer resource where account managers need an append-only comment thread ("called re: renewal, wants a 10% discount"). It's read-heavy, low-volume, and doesn't need rich text — exactly the shape this package assumes.

Implementation Patterns

Detail-view field as the primary integration. The package is designed around a field that renders existing notes plus a form to add a new one. Keep it on the detail view; putting it in index() produces a heavy query per row and a cramped UI.

If a model trait is exposed, use it for non-Nova access. Small packages of this vintage often ship a HasNotes trait alongside the field. If so, add it to the model so the same data is reachable from your own controllers, exports, and console commands:

use DigitalCloud\NovaResourceNotes\Traits\HasNotes;

class Customer extends Model
{
    use HasNotes;
}

Then $customer->notes()->create([...]) works from anywhere. Verify the trait exists in src/Traits/ first — don't assume it.

Author attribution. Notes are only useful if you know who wrote them. Confirm how the package stamps user_id (most likely auth()->id() at write time, possibly via a saving observer or directly in the field's store logic). If it doesn't, add it yourself with a model event:

protected static function booted()
{
    static::creating(function ($note) {
        $note->user_id ??= auth()->id();
    });
}

Also eager-load the author, or the note list will fire an N+1 on every render:

$customer->load('notes.user');

Gate visibility with Nova's own tooling. Notes frequently contain the kind of internal commentary you don't want every role to read. Wrap the field:

ResourceNotes::make('Notes')
    ->canSee(fn (Request $request) => $request->user()->hasRole('account-manager'))
    ->canUpdate(fn (Request $request) => $request->user()->can('update', $this->resource)),

If the package doesn't honour canUpdate, fall back to a policy on the underlying note model.

Pair with a global Note resource for oversight. Rather than hunting through each customer, exposing the note model as its own Nova resource gives admins one searchable list. You'll need to check whether the package registers that resource itself or expects you to build it:

php artisan nova:resource Note

Treat it as an activity log, not a document store. The schema is almost certainly body/content plus timestamps — flat and append-only. That makes it a good fit for status-change commentary and a poor fit for attachments, mentions, or threading. If you need any of those, you're building on top of it, not with it.

Gotchas and Tips

Nova version is the make-or-break issue. A 2019 field ships precompiled Vue 2 assets against Nova's old Nova::script() / field-mixin API. Nova 4+ moved to Vue 3 and changed field scaffolding; the component will silently fail to render (empty panel, or a Vue warning in the console). Before adopting, open the built JS and look at the Vue version, or just test it on a throwaway Nova install. If you're on Nova 4/5, plan to fork and rewrite the field component — the PHP side is usually trivial and the front end is the only real work.

Confirm the migration's table name and shape. Vendored migrations from this era often use a fixed table name (notes) without a config override. That will collide if you already have a notes table, and re-publishing after an upgrade can produce duplicate Schema::create calls. Read the published file, rename if needed, and never re-publish over a live migration.

Polymorphic keys need indexes. If noteable_type/noteable_id are used, verify the migration adds a composite index. Without it, listing notes for a resource does a full scan. Add it manually if missing:

$table->index(['noteable_type', 'noteable_id']);

Watch the morph map. If you use Relation::enforceMorphMap(), notes written before the map was introduced will carry FQCNs and silently fail to resolve. Either migrate the column or keep the map permissive.

Sanitise the body. Depending on how the field renders, note text may be output with v-html. Since only authenticated admins write notes the risk is lower, but if you ever expose notes to end users, escape on render or strip tags on save.

No pagination means a slow panel. A record with hundreds of notes will render all of them. Either cap the relationship or add a ->limit() / paginated custom tool. Check whether the field accepts a perPage-style option before writing your own.

Debuggability is limited. There's no test suite to lean on and no recent issue activity (17 stars, last release 2019). When something breaks, the source is your documentation. Trace it in this order: service provider (what it registers) → migration (schema) → field class (resolve/fill semantics) → Vue component (props in, events out).

Extension points are thin — plan for a fork. The realistic extension surface is: subclass the field and override resolve/fill, override the published Blade/Vue view, or listen to model events on the note model. For anything structural — threading, mentions, per-resource note types — fork the repo, pin your fork in composer.json via a VCS repository, and own the maintenance. For a package scoring ~2.3 on opportunity with no activity in six years, that's the honest default assumption rather than the fallback.