Laravel Love

https://github.com/cybercog/laravel-love
Admin
Laravel Love is a package for Laravel Eloquent models that adds emotional reaction functionality...
Tokens:60,704
Snippets:464
Trust Score:8.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### love:setup-reactable command example

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Example shell command to run the `love:setup-reactable` artisan command with a model option.

```shell
php artisan love:setup-reactable --model="App\Article"
```

--------------------------------

### Install Doctrine DBAL and run upgrade command

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Shell commands to install the doctrine/dbal package and run the love:upgrade-v7-to-v8 artisan command.

```shell
composer require doctrine/dbal
php artisan love:upgrade-v7-to-v8
```

--------------------------------

### Run love:setup-reacterable command

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Executes the setup command for reacterable models. Requires the --model option to specify the target model.

```shell
php artisan love:setup-reacterable --model="App\User"
```

--------------------------------

### love:recount command example

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Example shell command to run the `love:recount` artisan command with model, type, and queue connection options.

```shell
php artisan love:recount --model="App\Article" --type="Like" --queue-connection=sync
```

--------------------------------

### Run Laravel Love database migrations

Source: https://github.com/cybercog/laravel-love/blob/master/README.md

Run database migrations after installing the package.

```shell script
$ php artisan migrate
```

--------------------------------

### Development CLI Commands

Source: https://github.com/cybercog/laravel-love/blob/master/AGENTS.md

Common Docker-based commands for building the environment, installing dependencies, running tests, and performing static analysis.

```bash
# Build and start containers
docker compose up -d --build

# Install dependencies
docker compose exec php85 composer install

# Run all tests (uses in-memory SQLite)
docker compose exec php85 composer test

# Run a single test file
docker compose exec php85 vendor/bin/phpunit tests/Unit/Reactant/Models/ReactantTest.php

# Run a single test method
docker compose exec php85 vendor/bin/phpunit --filter test_method_name

# Static analysis
docker compose exec php85 composer phpstan
```

--------------------------------

### Usage: Making a Model Reactable

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

Example of making a model reactable using the Reactable trait and using the facade to get reaction counters.

```APIDOC
## Usage: Making a Model Reactable

### Description
Basic example of making a model reactable and using the facade.

### Code Example
```php
use Cog\Contracts\Love\Reactable\Models\Reactable as ReactableContract;
use Cog\Laravel\Love\Reactable\Models\Traits\Reactable;

final class Article extends Model implements ReactableContract
{
    use Reactable;
    // ...
}

// In your service/controller:
$article = Article::query()->whereKey(42)->firstOrFail();

// Register manually (usually done automatically by the observer on create):
if ($article->isNotRegisteredAsLoveReactant()) {
    $article->registerAsLoveReactant();
}

// Use the facade:
$count = $article->viaLoveReactant()->getReactionCounters()->count();
```
```

--------------------------------

### Install Laravel Love via Composer

Source: https://github.com/cybercog/laravel-love/blob/master/README.md

Pull in the package through Composer using the require command.

```shell script
$ composer require cybercog/laravel-love
```

--------------------------------

### Error Handling and Opt-out

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

Example of disabling auto-registration on create and handling the AlreadyRegisteredAsLoveReactant exception.

```APIDOC
## Error Handling and Opt-out

### Description
Example of disabling auto-registration on create and handling the `AlreadyRegisteredAsLoveReactant` exception.

### Code Example
```php
use Cog\Contracts\Love\Reactable\Exceptions\AlreadyRegisteredAsLoveReactant;

final class Article extends Model implements ReactableContract
{
    use Reactable;

    // Disable auto-registration on create:
    public function shouldRegisterAsLoveReactantOnCreate(): bool
    {
        return false;
    }
}

// $article->registerAsLoveReactant() throws when already registered:
try {
    $article->registerAsLoveReactant();
} catch (AlreadyRegisteredAsLoveReactant $e) {
    // handle: model already has a Reactant record
}
```
```

--------------------------------

### Custom storage configuration in config/love.php

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/configuration.md

Example of overriding default database connection and table names in the application's love.php configuration file. Setting load_default_migrations to false prevents the package from loading its default migration files.

```php
// config/love.php (application copy)
return [
    'storage' => [
        'database' => [
            'connection' => env('DB_CONNECTION', 'mysql'),
            'tables' => [
                'love_reacters' => 'reactions_actors',
                'love_reactants' => 'reactions_targets',
                'love_reaction_types' => 'reactions_types',
                'love_reactions' => 'reactions',
                'love_reactant_reaction_counters' => 'reactions_per_type_totals',
                'love_reactant_reaction_totals' => 'reactions_grand_totals',
            ],
        ],
    ],
    'load_default_migrations' => false,
];
```

--------------------------------

### Error handling when rebuilding aggregates

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/AggregateServices.md

Wrap the rebuild in a try-catch to handle LoveThrowable exceptions. Ensure relations are loaded before rebuilding to avoid null attributes. Example catches ReactionCounterDuplicate if counters were partially created.

```php
try {
    // ensure relations are loaded before rebuilding
    $reactant->load(['reactions', 'reactionCounters']);
    (new RebuildReactionAggregatesJob($reactant))->handle();
} catch (LoveThrowable $e) {
    // e.g. ReactionCounterDuplicate if counters were partially created
}
```

--------------------------------

### love:setup-reactable command class signature

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

The `SetupReactable` command class with the `#[AsCommand]` attribute and handle method signature. It accepts optional `--model` and `--not-nullable` options.

```php
#[AsCommand(name: 'love:setup-reactable', description: 'Set up reactable model')]
final class SetupReactable extends Command
{
    public function handle(
        Filesystem $files,
        MigrationCreator $creator,
        Composer $composer,
    ): int
```

--------------------------------

### Create Reaction and Read Values

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reaction.md

Demonstrates creating a reaction record and accessing its rate, weight, and reacter verification.

```php
use Cog\Laravel\Love\Reaction\Models\Reaction;

$reaction = Reaction::query()->create([
    'reaction_type_id' => ReactionType::fromName('Like')->getId(),
    'reactant_id'      => $reactant->getId(),
    'reacter_id'       => $reacter->getId(),
    // 'rate' omitted → defaults to RATE_DEFAULT (1.0)
]);

$reaction->getRate();   // 1.0
$reaction->getWeight(); // mass * rate
$reaction->isByReacter($reacter); // true
```

--------------------------------

### Basic Reactable Implementation and Usage

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

Demonstrates implementing the Reactable trait on a model and using the facade to interact with reaction counters.

```php
use Cog\Contracts\Love\Reactable\Models\Reactable as ReactableContract;
use Cog\Laravel\Love\Reactable\Models\Traits\Reactable;

final class Article extends Model implements ReactableContract
{
    use Reactable;
    // ...
}

// In your service/controller:
$article = Article::query()->whereKey(42)->firstOrFail();

// Register manually (usually done automatically by the observer on create):
if ($article->isNotRegisteredAsLoveReactant()) {
    $article->registerAsLoveReactant();
}

// Use the facade:
$count = $article->viaLoveReactant()->getReactionCounters()->count();
```

--------------------------------

### Basic reaction lifecycle with facades

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Facades.md

Shows the full reaction lifecycle: reacting with a type name and optional rate, inspecting reactions from the reactable side, and removing a reaction. Uses User and Article models with viaLoveReacter() and viaLoveReactant().

```php
$user = User::query()->whereKey(7)->firstOrFail();
$article = Article::query()->whereKey(42)->firstOrFail();

// Reacting: reacterable → reactable, by type name
$user->viaLoveReacter()->reactTo($article, 'Like');
$user->viaLoveReacter()->reactTo($article, 'Rating', 4.5);

// Inspecting: reactable side
$article->viaLoveReactant()->isReactedBy($user, 'Like');          // true
$article->viaLoveReactant()->isReactedBy($user, 'Rating', 4.5);   // true
$article->viaLoveReactant()->getReactionCounterOfType('Like')->getCount(); // 1
$article->viaLoveReactant()->getReactionTotal()->getWeight();      // float

// Removing
$user->viaLoveReacter()->unreactTo($article, 'Like');
```

--------------------------------

### Basic react, check, and unreact usage

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reacter.md

Shows how to react to a reactant with a named reaction type and an optional rate, check reactions with rate filtering, and unreact. Assumes 'Like' and 'Rating' reaction types exist.

```php
$user = User::query()->whereKey(7)->firstOrFail();
$article = Article::query()->whereKey(42)->firstOrFail();

$reacter = $user->getLoveReacter();   // Reacter model (or NullReacter)

$reacter->reactTo($article->getLoveReactant(), ReactionType::fromName('Like'));
$reacter->reactTo($article->getLoveReactant(), ReactionType::fromName('Rating'), 4.5);

$reacter->hasReactedTo($article->getLoveReactant(), ReactionType::fromName('Like')); // true
$reacter->hasReactedTo($article->getLoveReactant(), null, 4.5);                      // true (rate filter)

$reacter->unreactTo($article->getLoveReactant(), ReactionType::fromName('Like'));
```

--------------------------------

### Run love:recount with sync queue connection

Source: https://github.com/cybercog/laravel-love/blob/master/UPGRADING.md

To force synchronous statistics recount, use the --queue-connection=sync option with the love:recount command.

```shell
php artisan love:recount --model="App\User" --queue-connection=sync
```

--------------------------------

### Run PHPUnit tests

Source: https://github.com/cybercog/laravel-love/blob/master/CONTRIBUTING.md

Use the vendor/bin/phpunit script to execute the project's test suite.

```shell
$ vendor/bin/phpunit
```

--------------------------------

### UpgradeV5ToV6 command class definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Defines the love:upgrade-v5-to-v6 command using PHP attributes. The handle method accepts a Builder instance and returns an int.

```php
#[AsCommand(name: 'love:upgrade-v5-to-v6', description: 'Upgrade Love package from v5 to v6')]
final class UpgradeV5ToV6 extends Command
{
    public function handle(
        Builder $queryBuilder,
    ): int
```

--------------------------------

### Migration base class with config-driven connection

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/DatabaseSupport.md

Abstract base class for package migrations. It binds the schema builder to the configured connection from 'love.storage.database.connection' and provides a getConnection() method. Extend this class and use $this->schema->create() or dropIfExists() in your migrations.

```php
abstract class Migration extends IlluminateMigration
{
    /**
     * The database schema.
     *
     * @var \Illuminate\Database\Schema\Builder
     */
    protected $schema;

    public function __construct()
    {
        $this->schema = Schema::connection($this->getConnection());
    }

    /**
     * Get the migration connection name.
     */
    public function getConnection(): ?string
    {
        return Config::get('love.storage.database.connection');
    }
}
```

--------------------------------

### Run love:register-reactants command

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Registers specific Reactable models as Reactants using the --model and --ids options.

```shell
php artisan love:register-reactants --model="App\Article" --ids=1,2,16,34
```

--------------------------------

### UpgradeV7ToV8 command class definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Defines the love:upgrade-v7-to-v8 command using PHP attributes. The handle method takes no arguments and returns an int.

```php
#[AsCommand(name: 'love:upgrade-v7-to-v8', description: 'Upgrade Love package from v7 to v8')]
final class UpgradeV7ToV8 extends Command
{
    public function handle(): int
```

--------------------------------

### Perform and Query Reactions via Facades

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/README.md

Use the viaLoveReacter facade to perform a reaction and the viaLoveReactant facade to retrieve reaction counts for a specific type.

```php
$user->viaLoveReacter()->reactTo($article, 'Like');
$article->viaLoveReactant()->getReactionCounterOfType('Like')->getCount();
```

--------------------------------

### Reactant facade class definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Facades.md

Shows the class definition and constructor of the Reactant facade. The constructor takes a ReactantInterface instance and stores it in a private property.

```php
// src/Reactant/Facades/Reactant.php:19
final class Reactant implements
    ReacterFacadeInterface
{
    private ReactantInterface $reactant;

    public function __construct(
        ReactantInterface $reactant,
    ) {
        $this->reactant = $reactant;
    }
```

--------------------------------

### Reactable Opt-out and Error Handling

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

Shows how to disable automatic registration on create and handle the AlreadyRegisteredAsLoveReactant exception.

```php
use Cog\Contracts\Love\Reactable\Exceptions\AlreadyRegisteredAsLoveReactant;

final class Article extends Model implements ReactableContract
{
    use Reactable;

    // Disable auto-registration on create:
    public function shouldRegisterAsLoveReactantOnCreate(): bool
    {
        return false;
    }
}

// $article->registerAsLoveReactant() throws when already registered:
try {
    $article->registerAsLoveReactant();
} catch (AlreadyRegisteredAsLoveReactant $e) {
    // handle: model already has a Reactant record
}
```

--------------------------------

### Run v5 to v6 upgrade command

Source: https://github.com/cybercog/laravel-love/blob/master/UPGRADING.md

Execute the artisan command to perform the database migration after preparing your models and database tables. Ensure you have a backup of your production database before running this command.

```shell
php artisan love:upgrade-v5-to-v6
```

--------------------------------

### Resolve and create ReactionType

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ReactionType.md

Demonstrates resolving a reaction type by name and creating a new reaction type record.

```php
use Cog\Laravel\Love\ReactionType\Models\ReactionType;

$like = ReactionType::fromName('Like');

$like->getName();  // 'Like'
$like->getMass();  // 1

// Query usage:
ReactionType::query()->create([
    'name' => 'Star',
    'mass' => 5,
]);
```

--------------------------------

### Handle Reaction Rate Constraints

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reaction.md

Shows how to catch RateOutOfRange and RateInvalid exceptions when modifying reaction rates.

```php
use Cog\Contracts\Love\Reaction\Exceptions\RateInvalid;
use Cog\Contracts\Love\Reaction\Exceptions\RateOutOfRange;

// Out-of-range assignment throws when the model is saved:
try {
    $reaction->setAttribute('rate', 100.0); // > RATE_MAX 99.99
} catch (RateOutOfRange $e) {
    // "Must be between 0.01 and 99.99"
}

// Changing to the same value:
try {
    $reaction->changeRate($reaction->getRate());
} catch (RateInvalid $e) {
    // "Can not change to same value."
}
```

--------------------------------

### PHP: Config to prevent loading default migrations

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ServiceProviders.md

Shows how to configure the package to prevent it from loading its own migrations by setting 'load_default_migrations' to false in config/love.php.

```php
// config/love.php — prevent the package from loading its own migrations
return [
    'load_default_migrations' => false,
    // ...
];
```

--------------------------------

### Run database migration for v7 to v8 upgrade

Source: https://github.com/cybercog/laravel-love/blob/master/UPGRADING.md

Run this Artisan command to perform the automated database migration. It requires the doctrine/dbal composer package and should only be run after all code preparations are done. Create a backup of your production database before running.

```shell script
php artisan love:upgrade-v7-to-v8
```

--------------------------------

### AddForeignColumnStub constructor definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/DatabaseSupport.md

The constructor initializes the filesystem and migration parameters required to populate the foreign column stub template.

```php
final class AddForeignColumnStub
{
    private Filesystem $files;

    private string $table;

    private string $referencedTable;

    private string $foreignColumn;

    private bool $isForeignColumnNullable;

    private string $referencedColumn;

    public function __construct(
        Filesystem $files,
        string $table,
        string $referencedTable,
        string $foreignColumn,
        string $referencedColumn,
        bool $isForeignColumnNullable,
    ) {
```

--------------------------------

### Reactant::__construct(ReactantInterface $reactant)

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Facades.md

Constructor for the Reactant facade. Accepts a Reactant model instance (or NullReactant) to wrap.

```APIDOC
## Reactant::__construct(ReactantInterface $reactant)

### Description
Constructor for the Reactant facade. Accepts a Reactant model instance (or NullReactant) to wrap.

### Method
Constructor

### Parameters
- **$reactant** (`Cog\Contracts\Love\Reactant\Models\Reactant`) - Required - The Reactant model (or NullReactant).

### Return Type
void
```

--------------------------------

### PHP: LoveEventServiceProvider class skeleton

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ServiceProviders.md

The LoveEventServiceProvider extends ServiceProvider and its boot() method calls registerListeners().

```php
final class LoveEventServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap the application events.
     */
    public function boot(): void
    {
        $this->registerListeners();
    }
```

--------------------------------

### Handle ReactionType errors and caching

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ReactionType.md

Shows how to catch ReactionTypeInvalid exceptions and notes the static process-lifetime caching behavior.

```php
use Cog\Contracts\Love\ReactionType\Exceptions\ReactionTypeInvalid;

try {
    ReactionType::fromName('UnknownType');
} catch (ReactionTypeInvalid $e) {
    // "ReactionType with name `UnknownType` not exists."
}

// Cache note: name lookup results are cached in a static array for the process lifetime
// and are invalidated by the model's saved/deleted lifecycle hooks.
ReactionType::fromName('Like') === ReactionType::fromName('Like'); // typically true (cached)
```

--------------------------------

### Basic aggregate data reading with Reactant

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactant.md

Shows direct query usage and reading through a Reactable model. Use getReactionCounterOfType() to fetch a counter and getReactionTotal() for totals. The counter and total provide getCount() (int) and getWeight() (float).

```php
use Cog\Laravel\Love\Reactant\Models\Reactant;

$reactant = new Reactant();

// Direct query usage:
Reactant::query()->where('type', 'App\Article')->get();

// Through a Reactable model:
$article = Article::query()->with('viaLoveReactant')->whereKey(42)->firstOrFail();
$reactant = $article->getLoveReactant();

$counter = $reactant->getReactionCounterOfType(ReactionType::fromName('Like'));
$counter->getCount();   // int
$counter->getWeight();  // float

$total = $reactant->getReactionTotal();
$total->getCount();     // int
$total->getWeight();    // float
```

--------------------------------

### ReactionTotalService constructor

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/AggregateServices.md

Service that maintains the reaction total for a reactant. Constructor resolves and lazily creates the total via reactant->createReactionTotal(). Used in the aggregate pipeline to apply deltas.

```php
final class ReactionTotalService
{
    private ReactionTotalInterface $reactionTotal;

    public function __construct(
        ReactantInterface $reactant,
    ) {
        $this->reactionTotal = $this->findOrCreateReactionTotalFor($reactant);
    }
```

--------------------------------

### RegisterReactants command class definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

The class definition for the love:register-reactants command.

```php
#[AsCommand(name: 'love:register-reactants', description: 'Register Reactable models as Reactants')]
final class RegisterReactants extends Command
{
    public function handle(): int
```

--------------------------------

### Handle MigrationCreator exceptions

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/DatabaseSupport.md

Catch FileNotFoundException when the stub template is missing or InvalidArgumentException when the migration class already exists.

```php
use Illuminate\Contracts\Filesystem\FileNotFoundException;
use InvalidArgumentException;

try {
    (new MigrationCreator($files))->create($migrationsPath, $stub);
} catch (FileNotFoundException $e) {
    // stub template missing
} catch (InvalidArgumentException $e) {
    // migration class already exists
}
```

--------------------------------

### Run love:register-reacters command

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Registers Reacterable models as Reacters. This command mirrors the functionality of RegisterReactants.

```shell
php artisan love:register-reacters --model="App\User"
```

--------------------------------

### Config-driven base model class

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/DatabaseSupport.md

Defines the base model that all package models extend. It overrides getConnectionName() to use the configured 'love.storage.database.connection' and getTable() to resolve table names via 'love.storage.database.tables'.

```php
abstract class Model extends IlluminateModel
{
    /**
     * Get the current connection name for the model.
     */
    public function getConnectionName(): ?string
    {
        return Config::get('love.storage.database.connection');
    }

    public function getTable(): string
    {
        return Config::get("love.storage.database.tables.{$this->table}")
            ?? $this->table;
    }
}
```

--------------------------------

### Create a migration with AddForeignColumnStub

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/DatabaseSupport.md

Directly instantiate MigrationCreator and AddForeignColumnStub to generate a migration file for adding a foreign column to a database table.

```php
use Cog\Laravel\Love\Support\Database\MigrationCreator;
use Cog\Laravel\Love\Support\Database\AddForeignColumnStub;
use Illuminate\Filesystem\Filesystem;

$files = new Filesystem();

$stub = new AddForeignColumnStub(
    $files,
    'articles',
    'love_reactants',
    'love_reactant_id',
    'id',
    true, // nullable
);

(new MigrationCreator($files))
    ->create(database_path('migrations'), $stub);
```

--------------------------------

### Add timestamps to love_like_counters table

Source: https://github.com/cybercog/laravel-love/blob/master/UPGRADING.md

Add nullable created_at and updated_at columns to the love_like_counters table.

```mysql
ALTER TABLE `love_like_counters` 
 ADD COLUMN `created_at` TIMESTAMP NULL DEFAULT NULL AFTER `count`,
 ADD COLUMN `updated_at` TIMESTAMP NULL DEFAULT NULL AFTER `created_at`;
```

--------------------------------

### Add reaction type with love:reaction-type-add

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

Adds a reaction type. With --default, creates the default Like (mass 1) and Dislike (mass -1) reactions, skipping existing ones. Otherwise, resolves the name and mass from options or interactive prompts, sanitizes the name, and validates it against the pattern ^[A-Z][a-zA-Z0-9_]*$.

```shell
php artisan love:reaction-type-add --default
```

```shell
php artisan love:reaction-type-add --name=Clap --mass=2
```

--------------------------------

### Error handling for duplicate and missing reactions

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reacter.md

Captures ReactionAlreadyExists and ReactionNotExists exceptions for duplicate and missing reactions. Shows suggested handling: use unreactTo() or pass a rate to re-rate; for missing reactions, no-op handling.

```php
use Cog\Contracts\Love\Reaction\Exceptions\ReactionAlreadyExists;
use Cog\Contracts\Love\Reaction\Exceptions\ReactionNotExists;

// Duplicate reaction without a rate (explicit toggle semantics):
try {
    $reacter->reactTo($reactant, ReactionType::fromName('Like')); // already exists
} catch (ReactionAlreadyExists $e) {
    // use unreactTo() to remove, or pass a $rate to re-rate instead
}

// Removing a reaction that doesn't exist:
try {
    $reacter->unreactTo($reactant, ReactionType::fromName('Dislike')); // never reacted
} catch (ReactionNotExists $e) {
    // no-op handling
}
```

--------------------------------

### Querying Reactable Models

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/BuilderTraits.md

Perform queries to find reacted items, users who reacted to items within a timeframe, or retrieve aggregated reaction counts and weights.

```php
use Illuminate\Support\DateTime;

// Articles reacted by a user (optionally filtered by type):
$articles = Article::query()
    ->whereReactedBy($user, 'Like')
    ->get();

// Reacterable side: users who reacted to an article within a timeframe:
$users = User::query()
    ->whereReactedToBetween(
        $article,
        DateTime::now()->subDays(7),
        DateTime::now(),
        'Like',
    )
    ->get();

// Aggregated listing with virtual count/weight columns:
$articles = Article::query()
    ->joinReactionCounterOfType('Like')       // selects reaction_like_count, reaction_like_weight
    ->joinReactionTotal()                     // selects reaction_total_count, reaction_total_weight
    ->orderByDesc('reaction_like_count')
    ->get();
```

--------------------------------

### ReactionCounterService constructor

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/AggregateServices.md

Service that maintains reaction counters for a reactant. Constructor accepts a ReactantInterface and stores it. Used in the aggregate pipeline to increment/decrement counters when reactions are added or removed.

```php
final class ReactionCounterService
{
    private ReactantInterface $reactant;

    public function __construct(
        ReactantInterface $reactant,
    ) {
        $this->reactant = $reactant;
    }
```

--------------------------------

### Error handling for reactions

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Facades.md

Demonstrates handling exceptions when reacting: ReactionAlreadyExists when reacting twice without a rate, and ReactionTypeInvalid for unknown type names. Also shows nullable reacterable guards returning false/true.

```php
use Cog\Contracts\Love\Reaction\Exceptions\ReactionAlreadyExists;
use Cog\Contracts\Love\ReactionType\Exceptions\ReactionTypeInvalid;

// Double react without rate → ReactionAlreadyExists
try {
    $user->viaLoveReacter()->reactTo($article, 'Like');
    $user->viaLoveReacter()->reactTo($article, 'Like');
} catch (ReactionAlreadyExists $e) {
    // re-react only via rate, or unreactTo() first
}

// Unknown type name → ReactionTypeInvalid
try {
    $user->viaLoveReacter()->reactTo($article, 'NotAType');
} catch (ReactionTypeInvalid $e) {
    // add the type via `php artisan love:reaction-type-add --default`
}

// Nullable reacterable guards:
$article->viaLoveReactant()->isReactedBy(null);        // false
$article->viaLoveReactant()->isNotReactedBy(null);     // true
```

--------------------------------

### MigrationCreator class constructor

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/DatabaseSupport.md

Constructor for the MigrationCreator class. It accepts an Illuminate\Filesystem\Filesystem instance and stores it for later use when writing migration files.

```php
final class MigrationCreator
{
    private Filesystem $files;

    public function __construct(
        Filesystem $files,
    ) {
        $this->files = $files;
    }
```

--------------------------------

### ReactableObserver Class Definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

The ReactableObserver class handles automatic registration of models as reactants upon creation, unless explicitly opted out.

```php
final class ReactableObserver
{
    public function created(
        ReactableInterface $reactable,
    ): void {
        if (
            $this->shouldRegisterAsReactantOnCreate($reactable)
            && $reactable->isNotRegisteredAsLoveReactant()
        ) {
            $reactable->registerAsLoveReactant();
        }
    }

    private function shouldRegisterAsReactantOnCreate(
        ReactableInterface $reactable,
    ): bool {
        return !method_exists($reactable, 'shouldRegisterAsLoveReactantOnCreate')
            || $reactable->shouldRegisterAsLoveReactantOnCreate();
    }
}
```

--------------------------------

### PHP: LoveServiceProvider class skeleton

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ServiceProviders.md

The LoveServiceProvider extends Illuminate\Support\ServiceProvider with an empty register() method.

```php
final class LoveServiceProvider extends ServiceProvider
{
    /**
     * Register the service provider.
     */
    public function register(): void
    {
    }
```

--------------------------------

### love:recount command class signature

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ConsoleCommands.md

The `Recount` command class with the `#[AsCommand]` attribute and handle method signature. It accepts optional `--model`, `--type`, and `--queue-connection` options.

```php
#[AsCommand(name: 'love:recount', description: 'Recount reactions of the reactable models')]
final class Recount extends Command
{
    public function handle(
        DispatcherInterface $dispatcher,
        AppConfigRepositoryInterface $appConfigRepository,
    ): int
```

--------------------------------

### reactTo(ReactantInterface $reactant, ReactionTypeInterface $reactionType, ?float $rate = null): void

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reacter.md

Creates a reaction of the given type to the reactant, or updates the rate if a reaction already exists and a rate is provided.

```APIDOC
## reactTo(ReactantInterface $reactant, ReactionTypeInterface $reactionType, ?float $rate = null): void

### Description
Creates a reaction of the specified type to the given reactant. If a reaction of that type already exists and a rate is provided, updates the rate instead.

### Method
`reactTo(ReactantInterface $reactant, ReactionTypeInterface $reactionType, ?float $rate = null)`

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$reactant` | `Cog\Contracts\Love\Reactant\Models\Reactant` (interface) | yes | — | The Reactant to react to. |
| `$reactionType` | `Cog\Contracts\Love\ReactionType\Models\ReactionType` (interface) | yes | — | The reaction type. |
| `$rate` | float | no | `null` | Optional rate (must be within `[0.01, 99.99]` when provided). |

### Return Type
`void`

### Exceptions
- `Cog\Contracts\Love\Reactant\Exceptions\ReactantInvalid::notExists()` when the reactant `isNull()`.
- `Cog\Contracts\Love\Reaction\Exceptions\ReactionAlreadyExists::ofType($reactionType)` when a reaction of that type already exists for the reactant **and** `$rate === null`.
- `RateInvalid`/`RateOutOfRange` (via `changeRate`) when rate is invalid.

### Behavior
Looks up an existing reaction of the type for the reactant. If none exists, creates one via `reactions()->create(['reaction_type_id' => ..., 'reactant_id' => ..., 'rate' => $rate])`. If one exists and `$rate` is given, calls `$reaction->changeRate($rate)`.

### Source
`src/Reacter/Models/Reacter.php:80-102`
```

--------------------------------

### Reacter::__construct(ReacterInterface $reacter)

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Facades.md

Constructor for the Reacter facade. Accepts a Reacter model instance (or NullReacter) to be used for all operations.

```APIDOC
## Reacter::__construct(ReacterInterface $reacter)

### Description
Initializes the Reacter facade with a Reacter model instance.

### Method
Constructor

### Parameters
- `$reacter` (Cog\Contracts\Love\Reacter\Models\Reacter) - Required - The Reacter model (or NullReacter).

### Return
No return value.
```

--------------------------------

### Reactant facade contract

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/types.md

Interface for the Reactant facade, providing methods to retrieve reactions, reaction counters, and check reaction status.

```APIDOC
## Reactant facade contract

### Description
Interface for the Reactant facade, providing methods to retrieve reactions, reaction counters, and check reaction status.

### Methods

#### getReactions()
Returns an iterable of reactions for the reactant.

#### getReactionsBy(Reacterable $reacterable)
Returns an iterable of reactions by a specific reacterable.

#### getReactionCounters()
Returns an iterable of reaction counters for the reactant.

#### getReactionCounterOfType(string $reactionTypeName)
Returns the reaction counter for a given reaction type name.

#### getReactionTotal()
Returns the total reaction count for the reactant.

#### isReactedBy(?Reacterable $reacterable = null, ?string $reactionTypeName = null, ?float $rate = null)
Checks if the reactant is reacted by the given reacterable, optionally filtered by reaction type and rate. Returns false if reacterable is null.

#### isNotReactedBy(?Reacterable $reacterable = null, ?string $reactionTypeName = null, ?float $rate = null)
Checks if the reactant is not reacted by the given reacterable, optionally filtered by reaction type and rate. Returns true if reacterable is null.

### Implementation
Implemented by: Cog\Laravel\Love\Reactant\Facades\Reactant
```

--------------------------------

### isNull(): bool / isNotNull(): bool

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reacter.md

Checks whether the Reacter is null (does not exist) or not null (exists).

```APIDOC
## isNull(): bool / isNotNull(): bool

### Description
`isNull()` returns `true` if the Reacter does not exist (i.e., `!$this->exists`). `isNotNull()` returns the opposite.

### Methods
- `isNull()`
- `isNotNull()`

### Return Type
`bool`

### Parameters
None

### Source
`src/Reacter/Models/Reacter.php:154-161`
```

--------------------------------

### Basic Reacterable usage

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reacterable.md

Implement the Reacterable trait on a model to enable reactions, then use the viaLoveReacter method to perform actions like liking an article.

```php
use Cog\Contracts\Love\Reacterable\Models\Reacterable as ReacterableContract;
use Cog\Laravel\Love\Reacterable\Models\Traits\Reacterable;

final class User extends Authenticatable implements ReacterableContract
{
    use Reacterable;
    // ...
}

// In your service/controller:
$user = User::query()->whereKey(7)->firstOrFail();
$article = Article::query()->whereKey(42)->firstOrFail();

$user->viaLoveReacter()->reactTo($article, 'Like');
```

--------------------------------

### ReactionHasBeenAdded Event Class

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reaction.md

The ReactionHasBeenAdded event class stores a reaction and provides a getter to retrieve it.

```php
final class ReactionHasBeenAdded
{
    private ReactionInterface $reaction;

    public function __construct(
        ReactionInterface $reaction,
    ) {
        $this->reaction = $reaction;
    }

    public function getReaction(): ReactionInterface
    {
        return $this->reaction;
    }
}
```

--------------------------------

### Sync updated_at with created_at in love_likes

Source: https://github.com/cybercog/laravel-love/blob/master/UPGRADING.md

Optionally sync the updated_at column with the created_at column for existing records in the love_likes table.

```mysql
UPDATE `love_likes`
   SET `updated_at` = `created_at`
 WHERE `updated_at` IS NULL
   AND id > 0;
```

--------------------------------

### Composer JSON: register Laravel Love service providers

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ServiceProviders.md

Lists the two Illuminate service providers that the framework discovers automatically through composer.json's extra.laravel.providers key.

```json
"providers": [
    "Cog\\Laravel\\Love\\LoveServiceProvider",
    "Cog\\Laravel\\Love\\LoveEventServiceProvider"
]
```

--------------------------------

### Reacter facade class definition

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Facades.md

The Reacter facade class implements ReacterFacadeInterface and wraps a ReacterInterface instance. The constructor accepts a Reacter model or NullReacter.

```php
// src/Reacter/Facades/Reacter.php:18
final class Reacter implements
    ReacterFacadeInterface
{
    private ReacterInterface $reacter;

    public function __construct(
        ReacterInterface $reacter,
    ) {
        $this->reacter = $reacter;
    }
```

--------------------------------

### Rebuild reaction aggregates with RebuildReactionAggregatesJob

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/AggregateServices.md

Directly invoke RebuildReactionAggregatesJob to rebuild all aggregates for a reactant, or only a specific counter like 'Like' by passing a ReactionType. Used for testing or one-off repairs.

```php
use Cog\Laravel\Love\Reactant\Jobs\RebuildReactionAggregatesJob;

// Rebuild all aggregates of one reactant:
(new RebuildReactionAggregatesJob($reactant))->handle();

// Rebuild only the 'Like' counter:
(new RebuildReactionAggregatesJob(
    $reactant,
    ReactionType::fromName('Like'),
))->handle();
```

--------------------------------

### Reaction class declaration

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reaction.md

The Reaction model definition including constants for rate limits and table configuration.

```php
// src/Reaction/Models/Reaction.php:26
final class Reaction extends Model implements
    ReactionInterface
{
    use HasFactory;

    public const RATE_DEFAULT = 1.0;
    public const RATE_MIN = 0.01;
    public const RATE_MAX = 99.99;

    protected $table = 'love_reactions';

    protected static $unguarded = true;

    /**
     * @var array<string, float>
     */
    protected $attributes = [
        'rate' => self::RATE_DEFAULT,
    ];
```

--------------------------------

### Retrieve ReactionType by name using fromName

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ReactionType.md

Retrieves a ReactionType instance by its name, utilizing internal caching to optimize performance. Throws a ReactionTypeInvalid exception if the specified name does not exist in the database.

```php
// src/ReactionType/Models/ReactionType.php:81-98
public static function fromName(
    string $name,
): ReactionTypeInterface {
    if (isset(self::$nameCache[$name])) {
        return self::$nameCache[$name];
    }

    /** @var \Cog\Laravel\Love\ReactionType\Models\ReactionType|null $type */
    $type = self::query()->where('name', $name)->first();

    if ($type === null) {
        throw ReactionTypeInvalid::nameNotExists($name);
    }

    self::$nameCache[$name] = $type;

    return $type;
}
```

--------------------------------

### Reacter facade contract

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/types.md

Interface for the Reacter facade, providing methods to react to a reactable, unreact, and check reaction status.

```APIDOC
## Reacter facade contract

### Description
Interface for the Reacter facade, providing methods to react to a reactable, unreact, and check reaction status.

### Methods

#### getReactions()
Returns an iterable of reactions for the reacter.

#### reactTo(Reactable $reactable, string $reactionTypeName, ?float $rate = null)
Adds a reaction of the given type to the reactable.

#### unreactTo(Reactable $reactable, string $reactionTypeName)
Removes a reaction of the given type from the reactable.

#### hasReactedTo(Reactable $reactable, ?string $reactionTypeName = null, ?float $rate = null)
Checks if the reacter has reacted to the reactable, optionally filtered by reaction type and rate.

#### hasNotReactedTo(Reactable $reactable, ?string $reactionTypeName = null, ?float $rate = null)
Checks if the reacter has not reacted to the reactable, optionally filtered by reaction type and rate.

### Implementation
Implemented by: Cog\Laravel\Love\Reacter\Facades\Reacter
```

--------------------------------

### Read reaction total

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ReactionTotal.md

Basic usage to read the reaction total for an article. The total is never null; getCount() returns 0 and getWeight() returns 0.0 when no total row exists.

```php
$article = Article::query()->whereKey(42)->firstOrFail();
$total = $article->viaLoveReactant()->getReactionTotal();

$total->getCount();   // int — never null; 0 when no total row exists
$total->getWeight();  // float — 0.0 when no total row exists
```

--------------------------------

### Custom Eloquent Builder with ReactableEloquentBuilderTrait

Source: https://github.com/cybercog/laravel-love/blob/master/UPGRADING.md

To use the new local scopes, create a custom Eloquent builder class that uses the ReactableEloquentBuilderTrait and declare it as the default query builder in your model's newEloquentBuilder method.

```php
/**
 * @method static UserEloquentBuilder query()
 */
class User extends Model
{
    public function newEloquentBuilder($query): UserEloquentBuilder
    {
        return new UserEloquentBuilder($query);
    }
}

class UserEloquentBuilder extends \Illuminate\Database\Eloquent\Builder
{
    use \Cog\Laravel\Love\Reactable\ReactableEloquentBuilderTrait;

    // Other User model local query scopes
}
```

--------------------------------

### Reacterable error handling and opt-out

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reacterable.md

Disable automatic registration by defining shouldRegisterAsLoveReacterOnCreate, and handle potential registration exceptions or null Reacter states.

```php
use Cog\Contracts\Love\Reacterable\Exceptions\AlreadyRegisteredAsLoveReacter;

final class User extends Authenticatable implements ReacterableContract
{
    use Reacterable;

    // Disable auto-registration on create:
    public function shouldRegisterAsLoveReacterOnCreate(): bool
    {
        return false;
    }
}

try {
    $user->registerAsLoveReacter();
} catch (AlreadyRegisteredAsLoveReacter $e) {
    // model already has a Reacter record
}

// Guard reads on unregistered models — getLoveReacter() never returns null:
if ($user->getLoveReacter()->isNull()) {
    // no registered Reacter; read methods return neutral values,
    // reactTo()/unreactTo() throw ReacterInvalid::notExists()
}
```

--------------------------------

### Error handling for Reactant operations

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactant.md

Covers three error scenarios: NotAssignedToReactable when the polymorphic owner is missing, ReactionCounterDuplicate when creating a duplicate counter, and guarding against null reactants before calling getId().

```php
use Cog\Contracts\Love\Reactant\Models\Reactant as ReactantContract;
use Cog\Contracts\Love\Reactant\Exceptions\NotAssignedToReactable;
use Cog\Contracts\Love\Reactant\ReactionCounter\Exceptions\ReactionCounterDuplicate;

// 1. Reactant not assigned to a Reactable:
try {
    $orphanReactant->getReactable();
} catch (NotAssignedToReactable $e) {
    // polymorphic owner missing
}

// 2. Duplicate counter creation:
try {
    $reactant->createReactionCounterOfType(ReactionType::fromName('Like'));
} catch (ReactionCounterDuplicate $e) {
    // a counter for 'Like' already exists — use getReactionCounterOfType() instead
}

// 3. Never dereference a null reactant's id:
if ($reactant->isNull()) {
    // getId() would throw TypeError; guard first
}
```

--------------------------------

### Handle ReactionTotalInvalid exception

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ReactionTotal.md

Error handling when mutating a missing total. Calling incrementWeight() on a NullReactionTotal throws ReactionTotalInvalid with message "ReactionTotal not exists." Create the total first via createReactionTotal().

```php
use Cog\Contracts\Love\Reactant\ReactionTotal\Exceptions\ReactionTotalInvalid;

try {
    $total->incrementWeight(2.5); // total row does not exist
} catch (ReactionTotalInvalid $e) {
    // "ReactionTotal not exists." — create it first via createReactionTotal()
}
```

--------------------------------

### PHP: Event listeners for aggregate updates

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ServiceProviders.md

Registers event listeners that wire the aggregate pipeline: ReactionHasBeenAdded increments aggregates and ReactionHasBeenRemoved decrements them.

```php
// src/LoveEventServiceProvider.php:36-43
Event::listen(ReactionHasBeenAdded::class, IncrementAggregates::class);
Event::listen(ReactionHasBeenRemoved::class, DecrementAggregates::class);
```

--------------------------------

### Reacter facade contract

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/types.md

Defines the interface for the Reacter facade, which accepts a Reactable model and a reaction type name. The facade internally resolves the reaction type and the corresponding Reactant.

```php
interface Reacter
{
    public function getReactions(): iterable;

    public function reactTo(
        Reactable $reactable,
        string $reactionTypeName,
        ?float $rate = null,
    ): void;

    public function unreactTo(
        Reactable $reactable,
        string $reactionTypeName,
    ): void;

    public function hasReactedTo(
        Reactable $reactable,
        ?string $reactionTypeName = null,
        ?float $rate = null,
    ): bool;

    public function hasNotReactedTo(
        Reactable $reactable,
        ?string $reactionTypeName = null,
        ?float $rate = null,
    ): bool;
}
```

--------------------------------

### Reactable trait bootReactable method

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

The bootReactable method registers the ReactableObserver on the model, ensuring the model is registered as a Reactant upon creation.

```php
// src/Reactable/Models/Traits/Reactable.php:18
/**
 * @mixin \Cog\Contracts\Love\Reactable\Models\Reactable
 */
trait Reactable
{
    protected static function bootReactable(): void
    {
        // TODO: Remove the else block when minimum Laravel version is 13.
        if (method_exists(static::class, 'whenBooted')) {
            static::whenBooted(fn () => static::observe(ReactableObserver::class));
        } else {
            static::observe(ReactableObserver::class);
        }
    }
    // ...methods below
}
```

--------------------------------

### Read reaction counter via Reactant

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/ReactionCounter.md

Reads a reaction counter of type 'Like' from a Reactant and retrieves its count and weight. The count is always an integer (0 when no counter exists) and the weight is a float (0.0 when no counter exists).

```php
$article = Article::query()->whereKey(42)->firstOrFail();
$likeCounter = $article->viaLoveReactant()->getReactionCounterOfType('Like');

$likeCounter->getCount();   // int — never null; 0 when no counter exists
$likeCounter->getWeight();  // float — 0.0 when no counter exists
```

--------------------------------

### Reactable isRegisteredAsLoveReactant method

Source: https://github.com/cybercog/laravel-love/blob/master/_autodocs/api-reference/Reactable.md

Checks if the model is currently registered as a Reactant by verifying the registration status.

```php
public function isRegisteredAsLoveReactant(): bool
{
    return !$this->isNotRegisteredAsLoveReactant();
}
```
Tokens:
Raw