Installation and setup.

Use this setup when an application is ready to store customer health data in its own database.

Laravel Customer Health requires PHP 8.3 or later and Laravel 12 or 13.

1. Install the package

composer require byrcsc/laravel-customer-health

Laravel discovers CustomerHealthServiceProvider automatically.

2. Publish the configuration

php artisan vendor:publish --tag="customer-health-config"

This creates config/customer-health.php. The default configuration writes inline to the application's default database connection and keeps raw events forever.

Configure table names and database connections before running the migrations. Changing either after data exists requires an application migration.

3. Publish and run the migrations

php artisan vendor:publish --tag="customer-health-migrations"
php artisan migrate

The published migrations create four tables:

All four table names are configurable under table_names.

4. Make the subject trackable

The customer, account, team, workspace, or other model whose health you measure must implement Trackable:

namespace App\Models;

use ByRcsc\LaravelCustomerHealth\Concerns\TracksCustomerHealth;
use ByRcsc\LaravelCustomerHealth\Contracts\Trackable;
use Illuminate\Database\Eloquent\Model;

final class Team extends Model implements Trackable
{
    use TracksCustomerHealth;
}

TracksCustomerHealth is optional. It adds the productEvents() and milestones() relations plus lastProductActivity() and hasAdopted() helpers. Implementing Trackable is the requirement for facade methods.

The model must be saved before you track an event or compute a score. Integer and string model keys are supported. Polymorphic identities use Laravel's morph class, so an enforced morph map is respected.

5. Register declarations

Events, checklists, and health scores are classes registered in configuration:

use App\CustomerHealth\CustomerHealthScore;
use App\CustomerHealth\Events\TeammateInvited;
use App\CustomerHealth\Events\WorkflowCreated;
use App\CustomerHealth\Onboarding;

return [
    // ...
    'events' => [
        WorkflowCreated::class,
        TeammateInvited::class,
    ],
    'checklists' => [
        Onboarding::class,
    ],
    'scores' => [
        CustomerHealthScore::class,
    ],
];

The package validates these declarations when their registries resolve. Missing event registration fails before an event is written.

Configuration caching

Rebuild Laravel's configuration cache after deployment changes:

php artisan config:cache

Long-running workers must also restart before they see new event, checklist, score, connection, or queue configuration.

What to read next

• Quick start to create the declarations shown above and produce a first score.
• Configuration for every key and default.
• Database storage for columns, indexes, connections, and readable models.