Change record status: 
Project: 
Introduced in branch: 
11.5.x
Introduced in version: 
11.5.0
Description: 

When an entity_reference autocomplete field autocreates a new target entity, Drupal now fully validates the target entity through form validation before saving it to be referenced.

Previously, the onus was on site builders to make sure that autocreated entities are populated with the values they need.

An autocreated target entity may fail entity validation when a required field in the target bundle:

  1. cannot be populated by autocomplete,
  2. doesn't come with a default value, and
  3. isn't populated otherwise.

It may also fail when an entity- or field-level constraint rejects the submitted label.

In either case, autocomplete triggers the same no-match error as it would were autocreation disabled in the handler in the first place.

UI examples:

Tags: required Summary
An article’s Tags field autocreates taxonomy terms. The target vocabulary has a required Summary field with no default. Entering "Climate policy" and clicking Save now shows:

There are no taxonomy terms matching "Climate policy".

Content item: minimum Title length
A custom constraint requires a node title to be at least eight characters long. Entering "Drupal" in an autocomplete field configured to autocreate nodes, when no existing node matches, now shows:

There are no content items matching "Drupal".

API usage:

When creating references programmatically, call validate() on the referencing entity and handle any violations before saving.

Technical background:

Creation hooks such as hook_taxonomy_term_create() can still populate required values, normalize the label or otherwise make sure the target entity passes validation. Core validates the resulting entity after those hooks run. If it passes validation, the entity form saves and references the new target as usual. Note that values supplied in hook_entity_presave() will arrive too late.

This applies to both Field API's entity reference autocomplete widgets and to Form API's standalone entity_autocomplete form element. Standalone elements validate references by default. If your form sets #validate_reference to FALSE, validate the extracted references yourself, including any autocreated targets.

When you call $article->validate(), the ValidReference constraint checks whether the selection handler accepts each new target, then runs the accepted target’s entity-level and field-level constraints. The returned violation list includes the target’s detailed errors. In the first example, the missing summary is reported at field_tags.0.entity.field_summary.

API change:

FieldableEntityInterface now requires implementing the isValidationRunning(): bool method. Drupal uses isValidationRunning() to avoid validating the same entity object again through a circular reference.

PHP will fail to load any concrete class that implements the interface, directly or through a derived interface such as ContentEntityInterface, if the class lacks a compatible implementation. ContentEntityBase, however, does provide the required implementation and tracks the validation state in validate(), so classes inheriting this base class are covered.

If your class overrides or implements validate() without calling ContentEntityBase::validate(), and you prefer to keep it that way, your class must track its own validation state. isValidationRunning() must return TRUE while validation is running on that object, and the validation state must be cleared in a finally block that runs even if validation were to throw.

Impacts: 
Site builders, administrators, editors
Module developers
Site templates, recipes and distribution developers