Laravel Markable Laravel Package

Getting Started

1. Install the package: Run composer require maize-tech/laravel-markable.
2. Publish and run migrations: Pick the migrations you need (e.g., likes, bookmarks, reactions, custom marks) using php artisan vendor:publish --tag="markable-migration-{type}", then php artisan migrate.
3. Publish config: Run php artisan vendor:publish --tag="markable-config" to customize table prefixes, user model, and allowed values.
4. First use: Add the Markable trait to your model (e.g., Post, Course) and declare $marks = [Like::class]. Start adding likes with Like::add($post, $user).

Implementation Patterns

• Standard marks (likes, bookmarks): Simply define the mark class in $marks and use static methods: add(), remove(), toggle(), has(), count().
• Custom marks: Create a migration with markable_ prefix (e.g., markable_bookmarks), then define a Mark-extending class (e.g., Bookmark extends Mark) and include it in $marks.
• Reactions with values: Configure allowed_values['reaction'] = ['heart', 'laugh'] in config/markable.php, then call Reaction::add($post, $user, 'heart').
• Eager & query filtering:
  • Retrieve marks: $post->likes (relation returns collection of Like models).
  • Retrieve users: $post->likers (returns User collection with mark data as pivot).
  • Filter models: Post::whereHasLike($user)->get() or whereHasReaction($user, 'heart').
• Metadata usage: Pass an array as third argument to add()/toggle() for extra context (e.g., ['topic' => 'php']).

Gotchas and Tips

• Table naming: Migrations must include the configured table_prefix (markable_ by default) + mark name (e.g., markable_likes). Mismatched names cause relationship failures.
• Nullable value column: If allowed_values is empty or missing for a mark type, value remains NULL (e.g., likes don’t use values). When defining custom marks, remember to set allowed_values for value-based semantics.
• Wildcard values: Use 'reaction' => '*' to allow arbitrary values at runtime—useful for emoji reactions or dynamic user inputs.
• Performance: Each mark type uses a separate table (not a polymorphic single table), so queries like whereHasReaction() are fast—but avoid overusing many mark types if you’re constrained on migrations.
• Avoiding implicit_nullable deprecations: Use PHP 8.4+ only with v2.3.1+ (this version fixes the issue).
• Trait order matters: Ensure Markable trait is loaded before any custom scope overriding (whereHasLike, etc.). If needed, call parent::boot() in your model’s boot() method.
• Clear marks on deletion: The package auto-cleans marks when the marked model is deleted—no extra action needed, but verify in logs ifSoftDeletes are involved.