Getting Started

Minimal Setup

Installation:

composer require maize-tech/laravel-markable
php artisan markable:install

Publish only the migrations you need (e.g., bookmark, like, reaction):

php artisan vendor:publish --tag="markable-migration-like"
php artisan migrate

Configure User Model: Update config/markable.php to specify your user model:
```
'user_model' => App\Models\User::class,
```

First Use Case: Add the Markable trait to a model (e.g., Post) and define supported marks:

use Maize\Markable\Markable;
use Maize\Markable\Models\Like;

class Post extends Model
{
    use Markable;

    protected static $marks = [
        Like::class,
    ];
}

Basic Usage:

$post = Post::first();
$user = auth()->user();

Like::add($post, $user);       // Add like
Like::toggle($post, $user);    // Toggle like
Like::has($post, $user);       // Check if liked
Like::count($post);            // Count likes

Implementation Patterns

Core Workflows

Model Integration:
- Use the Markable trait in Eloquent models to enable marks.
- Define supported marks in $marks (e.g., Like, Bookmark, custom marks).
Mark Management:
- Add/Remove/Toggle: Use static methods (Like::add(), Like::remove(), Like::toggle()).
- Metadata: Pass custom metadata (e.g., Like::add($post, $user, ['topic' => 'Laravel'])).
Querying Marks:
- Count Marks: Like::count($post).
- Check Existence: Like::has($post, $user).
- Dynamic Scopes: Use Eloquent scopes like Post::whereHasLike($user).

Custom Marks:

Extend Maize\Markable\Mark and override markableRelationName()/markRelationName().

Example:

class Bookmark extends Mark {
    public static function markableRelationName(): string { return 'bookmarkers'; }
}

Value-Based Marks (e.g., Reactions):
- Configure allowed values in config/markable.php:
```
'allowed_values' => [
    'reaction' => ['heart', 'thumbs-up'],
],
```
- Use methods like Reaction::add($post, $user, 'heart').

BackedEnum Support:

Define an enum (e.g., ReactionType) and set it in config:

'allowed_values' => [
    'reaction' => \App\Enums\ReactionType::class,
],

Pass enum cases directly:

Reaction::add($post, $user, ReactionType::Heart);

Integration Tips

API Endpoints: Create routes for mark actions (e.g., POST /posts/{post}/like). Example controller:

public function like(Post $post) {
    Like::toggle($post, auth()->user());
    return response()->json(['status' => 'success']);
}

Frontend Integration: Use JavaScript to toggle marks (e.g., fetch /posts/{post}/like). Example Blade:

<button onclick="toggleLike({{ $post->id }})">
    {{ Like::has($post, auth()->user()) ? 'Unlike' : 'Like' }}
</button>

Eager Loading: Optimize queries with with():

Post::with(['likes', 'reacters'])->get();

Caching: Cache mark counts/metadata (e.g., Cache::remember()) for performance.

Gotchas and Tips

Pitfalls

Migration Conflicts:
- Ensure table names match the table_prefix in config (default: markable_).
- Avoid naming conflicts with existing tables.
Null User Checks:
- Always validate $user before calling mark methods (e.g., auth()->user() may return null).
Value Validation:
- If allowed_values is configured, passing invalid values (e.g., Reaction::add($post, $user, 'invalid')) will throw an exception.
- Wildcard (*) allows any value but bypasses validation.
Enum Type Safety:
- When using BackedEnum, ensure the enum’s backing type matches the database column (e.g., string for value column).
Relation Naming:
- Custom markableRelationName() must match the pivot table’s relation name in the model.
- Default relation names are pluralized (e.g., Like → likes).
Mass Assignment:
- Avoid mass-assigning marks directly to models. Use the package’s static methods.

Debugging

Query Logs: Enable Laravel’s query logging to debug pivot table queries:
```
DB::enableQueryLog();
Like::add($post, $user);
dd(DB::getQueryLog());
```
Common Errors:
- ClassNotFound: Ensure mark classes (e.g., Like) are autoloaded.
- TableNotFound: Run migrations or check table_prefix.
- CallToUndefinedMethod: Verify relation names in custom marks.

Extension Points

Custom Mark Logic: Override methods in Maize\Markable\Mark (e.g., boot() for model events).
Event Listeners: Listen for mark events (e.g., MarkAdded, MarkRemoved) via Laravel’s event system.

Policy Integration: Use Laravel’s policies to authorize mark actions:

public function toggleLike(User $user, Post $post) {
    $this->authorize('like', $post);
    Like::toggle($post, $user);
}

Testing: Use Markable trait in tests:

public function test_like_toggle() {
    $post = new Post();
    $user = new User();
    Like::toggle($post, $user);
    $this->assertTrue(Like::has($post, $user));
}

Performance:
- Batch Operations: Use chunk() for bulk mark updates.
- Indexing: Add indexes to user_id and markable_id in pivot tables.

Configuration Quirks

Table Prefix: Changing table_prefix after initial setup requires updating all migrations and existing data.
Allowed Values: Empty arrays ([]) disable values entirely. Use * for wildcards.
User Model: Ensure the configured user_model implements Illuminate\Contracts\Auth\Authenticatable.

Pro Tips

Dynamic Mark Registration: Register marks dynamically in a service provider:

public function boot() {
    if (!app()->runningInConsole()) {
        Mark::extend('DynamicMark', function () {
            return new class extends Mark { /* ... */ };
        });
    }
}

Soft Deletes: Extend marks to support soft deletes by adding SoftDeletes trait to the Mark model.

API Resources: Create custom resources for marks (e.g., LikeResource) to shape responses:

public function toArray($request) {
    return [
        'user' => $this->user,
        'metadata' => $this->metadata,
    ];
}

Validation: Validate mark values in Form Requests:

public function rules() {
    return [
        'reaction' => ['required', Rule::in(['heart', 'thumbs-up'])],
    ];
}

Laravel Markable Laravel Package