Syncing generated classes

• Introduction
• Checking for drift
• Understanding reports
• Writing safe updates
• When to update manually

Introduction

The expressive:sync command compares an existing Expressive class against the class that would be generated from the current Eloquent model shape. It is useful in CI or during refactors when generated classes should stay aligned with their models.

The command does not change files unless you pass --write.

Checking for drift

Run expressive:sync with the Expressive class name and mapped model:

php artisan expressive:sync User --model="App\Models\User"

The --model option is required. You may also pass --namespace and --suffix when the target class should be resolved differently for a single run:

php artisan expressive:sync User \
    --model="App\Models\User" \
    --namespace="App\Data" \
    --suffix="Expressive"

The command returns a successful exit code when the class is in sync.

Understanding reports

When drift is detected, the command prints one line per difference. Reports include the difference kind, model class, Expressive class, property, mapped key, expected type, actual type, and a suggestion.

Common difference kinds include:

Difference	Meaning
missing_attribute	The generated shape expects an attribute property that is not present.
stale_attribute	The class contains an attribute property that no longer appears in the generated shape.
missing_relationship	The generated shape expects a relationship property that is not present.
stale_relationship	The class contains a relationship property that no longer appears in the generated shape.
invalid_type	The property exists, but its declared type differs from the generated type.

Use these reports as review input. A difference may be intentional if the Expressive class has been customized beyond the generated model shape.

Writing safe updates

Pass --write when you want Expressive to update a safely generated class:

php artisan expressive:sync User --model="App\Models\User" --write

Write mode replaces the class only when Expressive determines that the existing file is still safe to regenerate. This is intended for generated classes that have not been meaningfully edited by hand.

When to update manually

If the command detects user edits, it refuses the rewrite and prints an error. Update the class manually when it contains custom methods, custom property decisions, or other changes that the generator should not overwrite.

You may also regenerate with make:expressive --force after reviewing the current class and deciding that overwriting it is correct.