webgefaehrten/laravel-auto-notes

Polymorphic notes package for Laravel models with owner support, field diffs, retention, and multi-language support.

v0.1.5 2025-09-10 10:35 UTC

Requires

• php: ^8.2|^8.3
• illuminate/console: ^11.0|^12.0
• illuminate/database: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

MIT

• Webgefaehrten

• timeline
• observer
• laravel
• activity
• history
• notes

README

Polymorphe Notizen für Laravel-Modelle mit optionalem Owner (Aggregation), automatischen Diffs (Feldänderungen), In-Class-Konfiguration, Retention/Pruning, optionalem Owner-Index und Mehrsprachigkeit (DE/EN).

🇩🇪 Deutsch

✨ Features

• Automatische Notizen bei created, updated, deleted
• Feld-Diffs: von X → Y
• Owner/Aggregation: z. B. Kunde ↔ Baustellen ↔ Kontakte
• In-Class-Konfiguration (kein zentrales Config-File nötig)
• Manuelles Hinzufügen von Notizen (addNote())
• Observer pro Model deaktivierbar oder austauschbar
• Retention & Archivierung (alte Notizen löschen oder verschieben)
• Optionaler Owner-Index für schnelle Abfragen
• Mehrsprachigkeit (DE/EN) mit Publish-Option

🚀 Installation

composer require webgefaehrten/laravel-auto-notes

Publizieren:

php artisan vendor:publish --provider="Webgefaehrten\AutoNotes\AutoNotesServiceProvider" --tag=auto-notes-config
php artisan vendor:publish --provider="Webgefaehrten\AutoNotes\AutoNotesServiceProvider" --tag=auto-notes-migrations
php artisan vendor:publish --provider="Webgefaehrten\AutoNotes\AutoNotesServiceProvider" --tag=auto-notes-lang

Migrationen ausführen:

php artisan migrate

🛠 Verwendung

Subject-Model (z. B. CustomerSite):

use Webgefaehrten\AutoNotes\Traits\HasNotes;
use Webgefaehrten\AutoNotes\Contracts\ProvidesAutoNotesConfig;
use Illuminate\Database\Eloquent\Model;

class CustomerSite extends Model implements ProvidesAutoNotesConfig
{
    use HasNotes;

    protected $fillable = ['customer_id','name','street','zip','city'];

    public function customer() { return $this->belongsTo(Customer::class); }

    // In-Class Konfiguration
    public function autoNoteContext(): ?string { return 'site'; }
    public function autoNoteLabels(): array { return ['name'=>'Name','city'=>'Ort']; }
    public function autoNoteInclude(): array { return ['name','city','zip','street']; }

    // Variante 1: direkte Relation (funktioniert, wenn Relation verfügbar ist)
    public function autoNoteOwner(): ?Model { return $this->customer; }

    // Variante 2: robuste Variante (nur Klasse zurückgeben, FK wird automatisch erkannt)
    public function autoNoteOwner(): Model|string|array|\Closure|null
    {
        return \App\Models\Customer::class;
    }

    public function autoNoteOwnerKey(): ?string
    {
        return 'customer_id'; // optional
    }

    public function autoNoteDisplayName(): ?string { return $this->name; }
}

Owner-Model (z. B. Customer):

use Webgefaehrten\AutoNotes\Traits\AggregatesNotes;

class Customer extends Model
{
    use AggregatesNotes; // ->allNotes()
}

Manuell Notiz anlegen:

$site->addNote(
    title: 'Adresse geändert',
    body:  'Von A-Straße nach B-Straße',
    context: 'site',
    owner:  $site->customer
);

Alle Notizen abrufen:

$notes = $customer->allNotes; // alle Notizen des Customers
$notes = $site->notes;        // nur Notizen der Site

⚙️ Retention / Archivierung

Konfiguration in config/auto-notes.php:

'retention_days'      => 730,
'retention_overrides' => [
    'order' => 1825, // 5 Jahre für Aufträge
],
'archive_to_table'    => 'notes_archive',

Prune-Command:

php artisan auto-notes:prune

🌍 Mehrsprachigkeit

php artisan vendor:publish --tag=auto-notes-lang

Verfügbare Sprachen: de, en.

🇬🇧 English

✨ Features

• Automatic notes on created, updated, deleted
• Field diffs: from X → Y
• Owner/Aggregation: e.g. Customer ↔ Sites ↔ Contacts
• In-class configuration (no central config file required)
• Add notes manually (addNote())
• Observer per model can be disabled or replaced
• Retention & pruning (delete/archive old notes)
• Optional owner index for fast queries
• Multi-language (EN/DE) with publish option

🚀 Installation

composer require webgefaehrten/laravel-auto-notes

Publish:

php artisan vendor:publish --provider="Webgefaehrten\AutoNotes\AutoNotesServiceProvider" --tag=auto-notes-config
php artisan vendor:publish --provider="Webgefaehrten\AutoNotes\AutoNotesServiceProvider" --tag=auto-notes-migrations
php artisan vendor:publish --provider="Webgefaehrten\AutoNotes\AutoNotesServiceProvider" --tag=auto-notes-lang

Run migrations:

php artisan migrate

🛠 Usage

Subject model (e.g. CustomerSite):

use Webgefaehrten\AutoNotes\Traits\HasNotes;
use Webgefaehrten\AutoNotes\Contracts\ProvidesAutoNotesConfig;
use Illuminate\Database\Eloquent\Model;

class CustomerSite extends Model implements ProvidesAutoNotesConfig
{
    use HasNotes;

    protected $fillable = ['customer_id','name','street','zip','city'];

    public function customer() { return $this->belongsTo(Customer::class); }

    public function autoNoteContext(): ?string { return 'site'; }
    public function autoNoteLabels(): array { return ['name'=>'Name','city'=>'City']; }
    public function autoNoteInclude(): array { return ['name','city','zip','street']; }

    // Variant 1: direct relation
    public function autoNoteOwner(): ?Model { return $this->customer; }

    // Variant 2: more robust (only return class, FK auto-resolved)
    public function autoNoteOwner(): Model|string|array|\Closure|null
    {
        return \App\Models\Customer::class;
    }

    public function autoNoteOwnerKey(): ?string
    {
        return 'customer_id'; // optional
    }

    public function autoNoteDisplayName(): ?string { return $this->name; }
}

Owner model (e.g. Customer):

use Webgefaehrten\AutoNotes\Traits\AggregatesNotes;

class Customer extends Model
{
    use AggregatesNotes; // ->allNotes()
}

Add note manually:

$site->addNote(
    title: 'Address changed',
    body:  'From A-Street to B-Street',
    context: 'site',
    owner:  $site->customer
);

Fetch notes:

$notes = $customer->allNotes; // all notes of the customer
$notes = $site->notes;        // only notes of the site

⚙️ Retention / Archiving

Config in config/auto-notes.php:

'retention_days'      => 730,
'retention_overrides' => [
    'order' => 1825, // 5 years for orders
],
'archive_to_table'    => 'notes_archive',

Prune command:

php artisan auto-notes:prune

🌍 Multi-language

php artisan vendor:publish --tag=auto-notes-lang

Available languages: en, de.

ℹ️ Owner Resolution

• autoNoteOwner() may return:

  • a Model
  • a class-string (e.g. Customer::class)
  • an array [Customer::class, $id]
  • a Closure returning a Model
  • or null

• Optional methods:

  • autoNoteOwnerKey() → explicit FK name
  • autoNoteOwnerRelation() → explicit relation name

Default heuristics: customer_id → owner_id → {ClassSnake}_id → relation.