Fieldtypes
Extending fieldtypes
The package knows the wire format of Statamic's built-in fieldtypes. It cannot know the ones an addon adds, and an unknown fieldtype gets two things wrong:
- No format guidance.
statamic-blueprints getreports no_format_specfor the field, so a client has to guess at the shape from the handle alone. - No input coercion. The guessed value reaches the fieldtype's own
process(), which was written for Control Panel input and may not survive contact with it.
aerni/advanced-seo is the worked example. Its seo fieldtype stores
['source' => ..., 'value' => ...]; a plain string dies inside its process()
with Cannot access offset of type string on string — an error that names
neither the field nor the expected shape.
FieldtypeExtensions lets you supply both halves.
Registering
Register from a service provider's boot():
use Cboxdk\StatamicMcp\Mcp\Support\FieldtypeExtensions;
use Statamic\Fields\Field;
public function boot(): void
{
FieldtypeExtensions::spec('seo', fn (Field $field): array => [
'wire_format' => 'object',
'shape' => 'seo_value',
'rules' => ['Object with "source" ("custom" or "default") and "value".'],
'example' => ['source' => 'custom', 'value' => 'Page title'],
]);
FieldtypeExtensions::sanitizer('seo', fn (mixed $value): mixed => is_string($value)
? ['source' => 'custom', 'value' => $value]
: $value);
}
Registrations are keyed by fieldtype handle, so a later one replaces an earlier one. Registering only a spec, or only a sanitizer, is fine — they are independent.
Specs
A spec resolver receives the Field and returns the same structure the built-in
specs use, or null to say nothing. Because it receives the field, a spec can
vary with configuration:
FieldtypeExtensions::spec('seo', fn (Field $field): array => [
'wire_format' => 'object',
'shape' => $field->get('multiple') ? 'seo_value_list' : 'seo_value',
]);
The keys are advisory text for the client, not a schema the server enforces.
wire_format and shape are the two every built-in spec carries; rules,
examples and common_mistakes are all read by clients when present.
Sanitizers
A sanitizer runs on the incoming value before validation and before the
fieldtype's own process(). It receives the value, the Field, and the dot
path to the field within the payload. Return the coerced value, or throw
FieldFormatException to reject the write:
use Cboxdk\StatamicMcp\Mcp\Exceptions\FieldFormatException;
FieldtypeExtensions::sanitizer('seo', function (mixed $value, Field $field, string $path): mixed {
if (is_string($value)) {
return ['source' => 'custom', 'value' => $value];
}
if (! is_array($value) || ! array_key_exists('source', $value)) {
throw new FieldFormatException(
"Field [{$path}] expects an object with \"source\" and \"value\"."
);
}
return $value;
});
The path matters: it is what turns "something in this entry was the wrong shape" into a message a client can act on. Include it in every error you throw.
Sanitizers run wherever field data is sanitized, so they apply inside replicator sets, grid rows, bard sets and groups as well as at the top level.
The string fieldtypes — text, textarea, slug, markdown, color, link
and video — already have a built-in check: a string passes, a number is cast
to one, and anything else is refused. Registering a sanitizer for one of them
replaces that check rather than running after it, so your sanitizer decides
what the field accepts.
Introspection and tests
FieldtypeExtensions::registered() lists the handles that have a spec or a
sanitizer. FieldtypeExtensions::flush() drops every registration — the
registry is static, so a test that registers should flush in setUp() and
tearDown() to avoid leaking into other tests.
SEO Pro
When statamic/seo-pro is installed, entries and terms accept its stored SEO
format. For example, an update with "data": {"seo": {"title": "New title"}}
changes the title and preserves other stored SEO handles. Each supplied handle
replaces its complete value, including arrays; omitted handles are preserved.
Use "@seo:title" to reference another field, null to inherit a value, or
false for an individual source that SEO Pro marks as disableable. Use
"seo": false to disable SEO for the whole record. An SEO object enables SEO
unless it explicitly contains "enabled": false. Control Panel input with
{ "source": "custom", "value": "New title" } is also accepted; omitting
enabled no longer disables SEO. Invalid objects and unknown SEO handles are
rejected before saving. A whole-field "seo": null is rejected: set individual
handles to null to restore inheritance. Empty strings, zero values and empty
lists remain explicit overrides. Creating an entry or term without an SEO
payload leaves SEO unset so section defaults apply.
statamic-blueprints get includes runtime SEO fields and their format guidance.
statamic-entries get and statamic-terms get return stored values that can be
sent back in an update.
The real-addon integration tests run in the SEO Pro CI job. To run them in an
isolated checkout, install statamic/seo-pro:7.16.0 as a dev dependency with
Composer's -W option, then run
vendor/bin/pest tests/Feature/Routers/SeoProWritesTest.php. SEO Pro remains an
optional runtime dependency.