Doctrine Lifecycle Bundle Laravel Package

Getting Started

• Install via Composer and check the package README for supported Laravel/PHP versions. Publish any config or migrations the package provides.
• Look first at src/Interfaces/Contracts and the traits: BlameableInterface, BlameableTrait, TimestampableInterface, TimestampableTrait. In 0.1.3, confirm the setter return types before implementing interfaces manually.
• Add BlameableTrait and/or TimestampableTrait to an Eloquent model, implement the matching interface if required, and ensure the expected columns exist (created_by, updated_by, deleted_by where applicable, and timestamp columns).
• First use case: add blameable behavior to a model like Post, authenticate a user, create/update a record, and verify the audit columns are populated. Then add timestampable behavior and verify updates are tracked as expected.

Implementation Patterns

• Use the traits on models that need audit metadata or package-managed timestamps. Keep the trait/interface pairing consistent across models.
• Configure the package’s user resolver to return the current authenticated user. For jobs, commands, and other non-HTTP contexts, set the resolver explicitly or provide a safe fallback.
• In migrations, use nullable foreign keys for blameable columns and index them for reporting/audit queries. Match the column type to your users table key (integer, UUID, ULID, etc.).
• For custom column names or user models, override the relevant setters or extend the trait. In 0.1.3, keep your overridden setter return types compatible with the updated interface/trait signatures.
• In tests, use actingAs($user) and assert the database columns directly. For queued jobs, assert the resolver context is restored or set correctly inside the job.
• If using soft deletes, verify whether the package supports deleted_by through the blameable trait or whether you need a model observer/event hook.

Gotchas and Tips

• 0.1.3 changes setter return types in BlameableInterface/BlameableTrait and TimestampableInterface/TimestampableTrait. If you implement these interfaces manually or override setters, update your signatures to match the package source. Using the provided traits avoids most breakage.
• Auth users are often null in console commands, queue workers, and scheduled tasks. Guard against null or configure a fallback resolver.
• Do not expose blameable columns through mass assignment. Keep them guarded and set them only through the package traits or explicit service logic.
• Avoid double-managing timestamps if the model already uses Laravel’s built-in timestamps. Confirm whether TimestampableTrait replaces or supplements Laravel behavior before adding custom timestamp columns.
• Clear config cache after changing package config. Debug by checking trait boot methods, model events, and the generated SQL for create/update/delete/restore flows.
• Extension points to review: published config, migrations, custom user resolver, overridden setters, and custom interface implementations.