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:

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