[6.x] Support reference updates for custom fieldtypes and working copies

[morhi]

Problem

Statamic's DataReferenceUpdater delegates asset reference updates to AssetReferenceUpdater, which only supports Statamic's built-in fieldtypes. Custom fieldtypes referencing assets or containing nested fields (including nested Statamic Asset fields) don't receive reference updates when assets are renamed, moved, or deleted. This causes broken references.

Because of this, I had to disable renaming and moving files entirely in all of my projects.

Also, while working on this PR I noticed, that working copies don't receive any data updates, which makes assets and terms disappear if the entry has a working copy that you are working on. The PR also fixes that issue.

Solution

This PR moves reference update logic into the fieldtypes themselves via the UpdatesReferences trait. Since only the fieldtype knows its internal data structure, it's best positioned to locate and replace references.

All built-in fieldtypes (Assets, Link, Bard, Markdown, Grid, Group, Replicator, Terms) now use this trait, serving as reference implementations for addon developers. The updater classes (AssetReferenceUpdater, TermReferenceUpdater, DataReferenceUpdater) are simplified to generic loops that delegate to fieldtype methods, with a one-time cached Blink lookup to detect which fieldtypes participate.

The trait provides three no-op methods to override:

Method	Purpose
replaceAssetReferences($data, $newValue, $oldValue, $container)	Replace direct asset references
replaceTermReferences($data, $newValue, $oldValue, $taxonomy)	Replace direct term references
iterateReferenceFields($data, NestedFieldUpdater $updater)	Traverse nested sub-fields for recursion

Plus three helpers: replaceValue(), replaceValuesInArray(), replaceStatamicUrls().

Examples

Custom fieldtype with asset references

class MyLinkFieldtype extends Fieldtype
{
    use UpdatesReferences;

    public function replaceAssetReferences($data, ?string $newValue, string $oldValue, string $container)
    {
        if ($this->config('container') !== $container) {
            return $data;
        }

        return $this->replaceValue($data, $newValue, $oldValue);
    }
}

Custom fieldtype with term references

class MyTagsFieldtype extends Fieldtype
{
    use UpdatesReferences;

    public function replaceTermReferences($data, ?string $newValue, string $oldValue, string $taxonomy)
    {
        return $this->replaceValuesInArray($data, $newValue, $oldValue);
    }
}

Custom fieldtype with nested sub-fields

use Statamic\Data\NestedFieldUpdater;
use Statamic\Fields\Fields;
use Statamic\Fields\Fieldtype;
use Statamic\Fieldtypes\UpdatesReferences;

class ColumnsFieldtype extends Fieldtype
{
    use UpdatesReferences;

    public function iterateReferenceFields($data, NestedFieldUpdater $updater): void
    {
        if (! is_array($data)) {
            return;
        }

        $fields = new Fields($this->config('fields'));

        foreach (array_keys($data) as $idx) {
            $updater->update($fields, "{$idx}.");
        }
    }
}

Closes statamic/ideas#698

[daun]

This would be amazing to have! We developed a custom asset fieldtype to better manage contextual metadata. While great for using custom fieldtype components, it also disables automatic reference updates for those fields. This PR would really help make this possible without re-implementing the logic of the reference updater classes in our addon.

[morhi]

Thanks @daun Do you have any thoughts or concerns about the implementation I suggested?

[daun]

@morhi No concerns here, looks logical to me :) An approach we explored previously was to create a new AssetReferencesUpdating event that fires for every item/entry and field during the update, but that ended up firing an endless amount of events, even for no-ops. So your solution looks much more efficient.

[morhi]

@morhi No concerns here, looks logical to me :) An approach we explored previously was to create a new AssetReferencesUpdating event that fires for every item/entry and field during the update, but that ended up firing an endless amount of events, even for no-ops. So your solution looks much more efficient.

Yea, I developed something similar too. It works, but it requires going through all fields twice.

I was just thinking if there is a solution that would be easier to integrate in custom fieldtypes. Currently, you have to use the trait and implement the given methods.

[morhi]

Hey @ryanmitchell @jasonvarga @jacksleight @marcorieser ! Would love to hear your opinion on this PR. I am quite sure that all of us came across this issue at some point and it would be super cool to have this fixed :)