Problem/Motivation

There's a entity_builders used a lot by core modules to extend entity forms but this api is undocumented

\Drupal\Core\Entity\EntityForm::buildEntity()
    $entity = clone $this->entity;
    $this->copyFormValuesToEntity($entity, $form, $form_state);

    // Invoke all specified builders for copying form values to entity
    // properties.
    if (isset($form['#entity_builders'])) {
      foreach ($form['#entity_builders'] as $function) {
        call_user_func_array($function, array($entity->getEntityTypeId(), $entity, &$form, &$form_state));
      }
    }

    return $entity;

Proposed resolution

Define what that for and document somehow

Remaining tasks

User interface changes

API changes

Data model changes

Comments

andypost created an issue. See original summary.

andypost’s picture

andypost
he/him
Primary language Russian
commented

Actual usage

core8$ git grep entity_builders
core/lib/Drupal/Core/Entity/ContentEntityForm.php:124:    $form['#entity_builders']['update_form_langcode'] = '::updateFormLangcode';
core/lib/Drupal/Core/Entity/EntityForm.php:295:    if (isset($form['#entity_builders'])) {
core/lib/Drupal/Core/Entity/EntityForm.php:296:      foreach ($form['#entity_builders'] as $function) {
core/modules/book/book.module:162:    $form['#entity_builders'][] = 'book_node_builder';
core/modules/contact/tests/modules/contact_storage_test/contact_storage_test.module:57:  $form['#entity_builders'][] = 'contact_storage_test_contact_form_form_builder';
core/modules/content_moderation/src/Plugin/Field/FieldWidget/ModerationStateWidget.php:208:    $form['#entity_builders']['update_moderation_state'] = [get_called_class(), 'updateStatus'];
core/modules/content_translation/src/ContentTranslationHandler.php:480:    $form['#entity_builders'][] = array($this, 'entityFormEntityBuild');
core/modules/menu_ui/menu_ui.module:437:  $form['#entity_builders'][] = 'menu_ui_form_node_type_form_builder';
core/modules/node/src/NodeForm.php:150:    $form['#entity_builders']['update_status'] = '::updateStatus';
core/modules/user/src/AccountForm.php:264:    $form['#entity_builders']['sync_user_langcode'] = '::syncUserLangcode';

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

andypost’s picture

andypost
he/him
Primary language Russian
commented
Version: 8.4.x-dev » 8.5.x-dev
Assigned: Unassigned » tim.plunkett

@Tim any idea where to put this docs?

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

danielveza’s picture

danielveza
he/him
Location Brisbane, AU
commented

Just bumping this up. Looking into these and not finding much info.

tim.plunkett’s picture

tim.plunkett
he/him
Primary language English
Location Philadelphia
commented
Assigned: tim.plunkett » Unassigned
Issue tags: +Documentation, +Entity Field API

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

ultrabob’s picture

ultrabob commented

Hi Daniel, I was looking for some documentation, but this is all I could find.

sime’s picture

sime
any/any
Location Melbourne
commented

I was also looking for this, and the signature for the callback is not documented for any core implementations that I can see. (No @param doxygen.)

anybody’s picture

anybody
Primary language German
Location Porta Westfalica
commented

Just found it in this article: https://www.heididev.com/how-alter-configuration-entity-data-drupal-8-or...

I guess it would make sense to document it on the same page where other form callbacks like
#validate
or
#submit
are documented?

That's at least where I'd expect it.

anybody’s picture

anybody
Primary language German
Location Porta Westfalica
commented
Title: Document entity_builders » Document #entity_builders EntityForm callbacks

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

rp7’s picture

rp7 commented

I'm having a hard time figuring out when to use an #entity_builder callback and when to use an #element_validate callback to alter (or clear) a submitted value. Anyone that can provide some insights?

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

mxr576’s picture

mxr576
Primary language Hungarian
Location Hungary
commented
Related issues: +#2799637: Document that #entity_builders and overrides of EntityForm::copyFormValuesToEntity() must be idempotent

Most probably also covering #2799637: Document that #entity_builders and overrides of EntityForm::copyFormValuesToEntity() must be idempotent here is a good idea.

joachim’s picture

joachim commented

> I guess it would make sense to document it on the same page where other form callbacks like #validate or #submit are documented?

#entity_builders is specific to the EntityForm class though, not a general FormAPI thing.

EntityForm::entityFormEntityBuild() is the thing that consumes these, so that's the logical place to put some documentation.

Maybe the class docs for EntityForm can mention it too. Probably sensible to put the bulk of it there, as it's more immediately visible if you're reading up about that class.

grevil’s picture

grevil commented

Bumping once again, as I am not sure when and why to use this, for example when hooking into a form.

I just found it being used in "field_permissions", for setting third party field storage settings, see (https://git.drupalcode.org/project/field_permissions/-/blob/8.x-1.x/fiel...). Is it not possible to just use a submit Form handler here instead?

geek-merlin’s picture

geek-merlin
Primary language German
Location Freiburg, Germany
commented

@Grevil: It's the standardized way of extracting form values / building the entity, and used not only in submit.

grevil’s picture

grevil commented

@geek-merlin Thanks for the clear-up! I could have realized, that this is the use case from the description of "EntityForm::entityFormEntityBuild()". But I thought it might do something else.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Issue tags: -Documentation

(I am removing a tag, since tags should not duplicate what already selected for the Component field. I apologize for bumping this issue.)

jwilson3’s picture

jwilson3
Primary language English
Location Ecuador
commented
Issue tags: +Entity Builders Callback

Bump. I've inherited the Label Help contrib module some time ago and at least two completely separate bugs have been filed which I suspect may be related to the Entity Builders Callback usage in the module. I'm currently trying to figure out why the original author who is no longer around used #entity_builders in code from 7 years ago to set third-party settings.

https://git.drupalcode.org/project/label_help/-/blob/376c641da6a72eb868d...

It seems like this could be done in a #form_submit, but I'm not entirely certain.

I'm creating a tag to group such issues.

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.

anybody’s picture

anybody
Primary language German
Location Porta Westfalica
commented

We're now experiencing taxonomy term overview page order changes not being saved any more if several modules are enabled that implement submit callbacks instead of entity builders for handling additional third party settings on the taxonomy term overview pages.

For us this happens in the combination of

  • tvi
  • simplify
  • rabbit_hole

being enabled.
Only if I remove the submit callbacks of all three, the form is saving again, while other modules that use Entity Builders can stay enabled and everything works fine!

No idea if this happens since we upgraded to Drupal 11.3 or what's the root cause, yet. If anyone has an idea, that would be great.
For me, this is just another good reason to replace submit callbacks by Entity Builders wherever it is used to add third party settings altering an existing form!