Introduction.

Customer health becomes difficult to explain when onboarding progress, product activity, and score calculations live in separate systems. Laravel Customer Health records those inputs against your Eloquent models and keeps the derived history in your application database.

You declare the events that matter, group milestone events into onboarding checklists, and combine signals into health scores. The package then answers questions such as:

• Has this customer adopted a feature?
• When did they last use the product?
• Where did onboarding stop?
• What is their current score and state?
• Why did the score receive that value?

The package supports Laravel 12 and 13 on PHP 8.3 or later.

The shortest example

Imagine Acme is setting up its account. Taylor creates the team's first approval workflow. That action shows that Acme has moved from signing in to using the workflow feature.

Describe that action with a product event:

namespace App\CustomerHealth\Events;

use ByRcsc\LaravelCustomerHealth\Events\ProductEvent;

final class WorkflowCreated extends ProductEvent
{
    // Group this event with other workflow activity.
    public static string $feature = 'workflows';

    // Preserve the first workflow as a lasting sign of adoption.
    public static bool $milestone = true;
}

Read the declaration as: when a customer creates a workflow, count it as workflow activity and remember the first occurrence as an adoption milestone. Later workflow creations are still recorded as raw product events.

Register the event in config/customer-health.php. When the create-workflow operation succeeds, track who performed it and which template they used:

use App\CustomerHealth\Events\WorkflowCreated;
use ByRcsc\LaravelCustomerHealth\Facades\CustomerHealth;

CustomerHealth::track(new WorkflowCreated(
    subject: $team,
    actor: $user,
    properties: ['template' => 'approval'],
));

Here, $team is Acme, the customer whose health you measure. $user is Taylor, the person who created the workflow.

The subject must be a persisted Eloquent model that implements Trackable. The actor is optional, but when present it must be a persisted authenticatable Eloquent model.

What gets stored

Every call to track() writes a raw product event. A milestone event also writes its first occurrence to the milestones table.

Raw events answer time-window and frequency questions. Milestones remain after raw events are pruned, so adoption and onboarding completion do not disappear with retention cleanup.

All event times are stored and returned in UTC as CarbonImmutable values.

What health scores contain

A health score combines one or more signals. Each signal returns an integer from 0 through 100 and carries a positive weight.

Each computation stores:

• the final integer value;
• the state selected from your thresholds;
• every signal's raw value, normalized weight, and contribution; and
• the UTC computation time.

Computing a score appends history. It also updates one compact summary row for the subject and score, which is the table to query for current state.

What the package does not do

The package does not decide which events, onboarding steps, signals, weights, or state thresholds fit your business. You declare them in application code.

It does not ingest analytics from a browser or third-party platform. Your application calls CustomerHealth::track() when a verified business event occurs.

It also does not schedule score recomputation or raw-event pruning. It provides Artisan commands that you add to Laravel's scheduler at the cadence your application needs.

What to read next

• Installation and setup to publish the four storage migrations and configure your subject model.
• Quick start to track an event and compute a first score.
• Product events to understand event identity, actors, properties, and timestamps.