Documentation Search Laravel Package

Getting Started

This assessment reflects v2.0.0. The release notes are terse, so confirm details against the package README and source before rolling out.

• Requirements: v2 targets Statamic 6, which means a modern Laravel baseline (Laravel 11+) and PHP 8.2+. Check the addon's composer.json for the exact statamic/cms and laravel/framework constraints. Do not upgrade in place on a Statamic 5 site.
• Install/upgrade: composer require <vendor>/<package>:"^2.0", then run any documented publish/install command (php artisan vendor:publish --tag=...). Clear caches afterwards: php artisan config:clear && php artisan cache:clear.
• Where to look first: the addon's service provider and the class whose provider method now returns references. Search for the method named in the release notes and inspect its declared return type. Then grep your app for every call site of that method.
• First use case: resolve a reference explicitly. If the provider previously returned an Entry/Asset object, it now returns a reference value (ID/handle or reference object). Hydrate only where you need the object:

$reference = $provider->resolve($key);       // now a reference, not an object
$entry = \Statamic\Facades\Entry::find($reference);

If your first use is in Antlers/Blade, check whether the tag/modifier now emits an ID; you may need to resolve it through the corresponding Statamic tag or a small view composer.

Implementation Patterns

• Separate lookup from hydration. Treat the provider as a reference resolver. Keep IDs/handles in your domain layer, queues, and API payloads; hydrate to Entry/Asset objects only at the boundary (controller, Blade/Antlers, API resource).
• Adapter service. Wrap the provider behind a small application service so call sites do not depend on the new return shape:

final class EntryResolver
{
    public function __construct(private Provider $provider) {}

    public function entry(string $key): ?Entry
    {
        $ref = $this->provider->resolve($key);
        return $ref ? Entry::find($ref) : null;
    }
}

This is also your migration shim: preserve object semantics temporarily while you refactor call sites.

• API/JSON resources. Return references in payloads and resolve on the next request or in the client. This keeps responses small and avoids serializing hydrated Statamic objects.
• Templates. If the addon exposes a tag, verify whether it now returns a reference. Resolve with Statamic's entry/asset tags or pass hydrated values from the controller. Test with unpublished and missing entries, not just happy-path content.
• Testing. Use Statamic's addon test harness where available. Assert that the provider returns stable references and that your adapter returns null for stale references. Add a regression test that calls every previously object-returning call site.
• Upgrade workflow. Branch, bump the constraint, run the full suite, then grep for the provider method. Replace object-style access (->title(), ->url(), property access) with reference extraction followed by re-resolution.

Gotchas and Tips

• This is a breaking return-type change. Any code doing $provider->resolve($key)->title() or similar will fail with "call to a member function on string/int" errors. Static analysis (PHPStan/Larastan) will catch it only if return types are declared; otherwise grep is your friend.
• Stale references are normal. A reference can point to a deleted or unpublished entry. Entry::find($id) returns null; handle it explicitly. Reserve findOrFail for places where a missing reference truly is an error.
• Statamic 6 compatibility is the headline feature. Confirm the addon constraint includes ^6.0. If it also supports ^5.0, test both majors, because Statamic 6's Laravel/PHP baseline and control-panel changes can surface issues that the addon's own tests miss.
• Config and binding caches. If reference resolution is config-driven, production config caching can hide new bindings or published config. Always clear config after upgrading.
• Extension point: bind your own implementation of the provider contract in a service provider. This lets you restore object semantics temporarily or add caching/logging around reference resolution without forking the addon.
• Debugging: log the raw reference and its type before hydrating. The signature failure mode of this release is type confusion between "reference" and "hydrated object," so ray($ref)/ddd($ref) at the boundary saves time.
• Pin the major. Because v2 changes a public return shape, use ^2.0, not *, and review the addon's changelog for any follow-up patch releases that adjust reference handling.