Download the PHP package ritechoice23/laravel-followable without Composer

Laravel Followable

The only fully polymorphic follow package that handles mixed follower types elegantly with metadata support.

A modern Laravel package that adds follow/unfollow functionality to Eloquent models with true bidirectional polymorphism. Any model can follow any other model, with intelligent handling of mixed-type relationships and optimized queries.

Why This Package?

While other popular packages like overtrue/laravel-follow and rennokki/laravel-eloquent-interactions offer basic follow functionality, they often force you to hardcode the User model or require complex workarounds for heterogeneous relationships.

Laravel Followable was built to solve real-world challenges in complex applications where:

• Organizations follow other organizations
• Teams follow users and other teams
• Mixed-type followers need to be handled elegantly (Users + Teams + Organization following the same post)
• You need metadata for analytics (tracking follow sources, campaigns, referrers)
• Mutual relationships and bidirectional queries are essential
• Performance matters (optimized queries, no N+1 problems)

What Makes It Unique

✅ True Bidirectional Polymorphism - Both follower AND followable can be ANY model type (User→Team, Team→Team, Organization→User, etc.)

✅ Intelligent Mixed-Type Handling - Smart MixedModelsCollection for when followers are of different types (Users + Teams + Organizations)

✅ Rich Metadata Support - Attach JSON metadata to track source, campaign data, referrer, or any custom attributes

✅ Flexible Query API - Separate optimized methods for single-type (followers()) vs multi-type (followersGrouped()) scenarios

✅ Mutual Relationships - Built-in support for identifying mutual follows and connections

✅ Full MorphMap Support - Works seamlessly with Laravel's Relation::morphMap() for cleaner database storage

✅ Modern Architecture - Uses latest Laravel features with 100+ comprehensive tests using Pest PHP

Features

• Fully Polymorphic: Any model can follow any other model (User → Team, User → User, Team → Team, etc.)
• Simple API: Intuitive methods like follow(), unfollow(), toggleFollow(), isFollowing()
• Expressive Scopes: Chainable query scopes like whereFollowing() and whereFollowers()
• Metadata Support: Attach custom JSON metadata to follows
• Zero Configuration: Works out of the box with sensible defaults
• Full Test Coverage: Comprehensive Pest PHP test suite included

Installation

Install the package via composer:

Publish and run the migrations:

Optionally, publish the config file:

Configuration

The published config file (config/follow.php) includes:

Usage

Setup Models

Add traits to your models:

Basic Operations

Working with Followers

Get Actual Follower Models

The followers() method returns actual follower models (User, Team, etc.), not Follow pivot records:

Handling Mixed Follower Types

When a model has followers of different types (e.g., both Users and Teams), use followersGrouped():

Counting Followers

Access Follow Pivot Records

When you need the actual Follow records (e.g., for metadata):

Follow with Metadata

Attach custom data to follows:

Query Scopes

Find models based on follow relationships:

Polymorphic Follows

Follow any model type:

Relationships

Access follow relationships:

Working with Followings

The CanFollow trait provides powerful methods to query what models a user is following.

Get Actual Followable Models

The followings() method returns actual followable models (User, Team, etc.), not Follow pivot records:

Handling Mixed Followable Types

When a user follows different types of models (e.g., both Users and Teams), use followingsGrouped():

Counting Followings

Access Following Records

When you need the actual Follow records (e.g., for metadata):

Important Notes

Use Cases for Different Methods

For Followers (HasFollowers trait):

Use followers() when:

• All followers are of the same type (e.g., only Users)
• You're filtering by a specific type
• You need to chain Eloquent query methods
• You're working with pagination

Use followersGrouped() when:

• A model has followers of multiple different types
• You need followers organized by their model type
• You want to iterate through each type separately

Use followRecords when:

• You need access to the Follow pivot records
• You want to work with follow metadata
• You need the follow timestamps or other pivot data

For Followings (CanFollow trait):

Use followings() when:

• Following models of the same type (e.g., only Teams)
• You're filtering by a specific type
• You need to chain Eloquent query methods
• You're working with pagination

Use followingsGrouped() when:

• Following multiple different types of models
• You need followings organized by their model type
• You want to iterate through each type separately

Use followingRecords when:

• You need access to the Follow pivot records
• You want to work with follow metadata
• You need the follow timestamps or other pivot data

Performance Considerations

The package uses optimized database queries with negligible overhead:

• Single type queries: Both followers() and followings() use efficient JOIN queries (1 query instead of N+1)
• Multiple types: followersGrouped() and followingsGrouped() fetch all types efficiently with batch queries
• Smart Collection Wrapping: MixedModelsCollection adds ~0.006ms overhead per operation (tested with 100 items)
• Counting: Direct COUNT queries on indexed columns
• All queries leverage database indexes for fast lookups
• MorphMap Compatible: Works seamlessly with morphMap for cleaner storage and better performance

Benchmark Results (50 followings, mixed types):

• Single type query: ~1.1ms
• Mixed types (2 types): ~16-20ms (includes multiple type queries + sorting)
• Grouped query: ~3.8ms (most efficient for mixed types)

💡 Pro Tip: For mixed-type scenarios, followingsGrouped() is 4x faster than followings()->get()

Working with Mixed Follower Types

If your model can be followed by different types (polymorphic scenario):

Advanced Usage

Prevent Self-Following

By default, models cannot follow themselves. Enable it in config if needed:

Idempotent Operations

Following an already-followed model returns false without creating duplicates:

Database Indexes

The migration includes optimized indexes for performance:

• Unique composite index on follower and followable (prevents duplicates)
• Index on followable_type and followable_id (for lookups)
• Index on follower_type and follower_id (for reverse lookups)
• Index on created_at (for trending queries)

Testing

Run the test suite:

Run tests with coverage:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Daramola Babatunde Ebenezer
• All Contributors

License

The MIT License (MIT). Please see License File for more information.