Laravel Acquaintances Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require multicaret/laravel-acquaintances
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Multicaret\Acquaintances\AcquaintancesServiceProvider" --tag="config"
   

2. Basic Usage Add traits to your Eloquent models:

   use Multicaret\Acquaintances\Traits\HasFollowers;
   use Multicaret\Acquaintances\Traits\HasLikes;
   use Multicaret\Acquaintances\Traits\HasRatings;
   
   class Post extends Model
   {
       use HasFollowers, HasLikes, HasRatings;
   }
   

3. First Interaction

   // Follow a user
   $user->follow($post->user);
   
   // Like a post
   $post->like($currentUser);
   
   // Rate a post (1-5 stars)
   $post->rate($currentUser, 4);
   

Where to Look First

• Config File: config/acquaintances.php (caching, morph keys, table names)
• Macros: Built-in query macros like withAcquaintanceCounts()
• Events: AcquaintanceCreated, AcquaintanceDeleted for custom logic

Implementation Patterns

Core Workflows

1. Friendships & Groups

// Create a friendship
$friendship = $user->becomeFriendsWith($otherUser);

// Add to a group
$group = $user->createGroup('Colleagues');
$group->addMember($otherUser);

// Check membership
if ($user->isFriendsWith($otherUser)) { ... }

2. Interactions (Likes, Follows, etc.)

// Bulk operations
$post->like([$user1, $user2]);
$post->unlike([$user1]);

// Check interactions
if ($post->isLikedBy($user)) { ... }

// Pagination with counts
$posts = Post::withAcquaintanceCounts()->paginate(10);

3. Ratings System

// Rate with metadata
$post->rate($user, 5, ['comment' => 'Great post!']);

// Get average rating
$average = $post->averageRating();

// Filter by rating
$topPosts = Post::ratedAbove(4)->get();

4. Verification

// Verify a user
$verifier->verify($user, 'email');

// Check verification
if ($user->isVerified('email')) { ... }

Integration Tips

• Caching: Enable Redis for interaction checks:

  'cache' => [
      'enabled' => env('ACQUAINTANCES_CACHE_ENABLED', true),
      'driver' => 'redis',
  ],
  

• Morph Maps: Customize polymorphic keys:

  'morphs' => [
      'user' => 'users',
      'post' => 'posts',
  ],
  

• Scopes: Use built-in scopes like likedBy(), followedBy() in queries.

Gotchas and Tips

Pitfalls

1. Counter Cache Mismatch

   • Ensure increment/decrement calls match your counter columns (e.g., likes_count).
   • Fix: Use HasAcquaintanceCounters trait or manually sync counters.

2. UUID/ULID Conflicts

   • If using UUIDs/ULIDs, configure uuidMorphs or ulidMorphs in the config to avoid key errors.

3. Cache Invalidation

   • Persistent cache (Redis) requires manual invalidation for bulk operations:

     Acquaintance::clearCacheFor($post);
     

4. Event Overhead

   • Disabling events in tests:

     $this->withoutEvents(function () {
         $post->like($user);
     });
     

Debugging Tips

• Query Logging: Enable Laravel’s query log to inspect generated SQL for interactions.
• Cache Debugging: Check cached interactions with:

  Acquaintance::getCachedInteractions($post);
  

• Morph Key Issues: Verify morphMap in your models and the package config.

Extension Points

1. Custom Interactions Create a new interaction type by extending Multicaret\Acquaintances\Contracts\Interaction:

   class Report implements Interaction { ... }
   

   Register it in config/acquaintances.php under interactions.

2. Custom Verification Types Extend Multicaret\Acquaintances\Contracts\Verification and add to the verifications config array.

3. Macros Extend the HasAcquaintances macro for reusable query logic:

   \Multicaret\Acquaintances\HasAcquaintances::macro('trending', function () {
       return $this->orderByDesc('likes_count')->limit(10);
   });
   

Performance Quirks

• N+1 Queries: Always use withAcquaintanceCounts() or with() for related models.
• Bulk Operations: Prefer bulk methods (like(), follow()) over loops for performance.
• Rating Precision: Use decimal(3,2) for rating columns to avoid floating-point errors.