Entity traits don't show descriptions in their entity form fields.

Created on 18 June 2025, about 2 months ago

Description of issue

When an entity trait creates a field definition with a description, the description value isn't propagated to the field instance when the trait is attached to an entity.
This means that module developers that provide a field added thru trait are unable to provide help text on the corresponding form fields (to help content editors understand the behaviour of the field).

Reproducing

e.g. a trait created this way:

class MaximumOrderQuantity extends EntityTraitBase {

  /**
   * {@inheritdoc}
   */
  public function buildFieldDefinitions() {
    $fields = [];
    $fields['maximum_order_quantity'] = BundleFieldDefinition::create('integer')
      ->setLabel(t('Maximum quantity per order'))
      // Field description added here.
      ->setDescription(t('Leave blank to allow unlimited quantity.'))
      ->setSettings([
        'size' => 'normal',
        'unsigned' => TRUE,
      ])
      ->setDisplayOptions('form', [
        'type' => 'number',
        'weight' => 1,
      ]);

    return $fields;
  }

}

Analysis

The field definition created by the trait makes its way through to \Drupal\commerce\EntityTraitManager::installTrait(), then to \Drupal\commerce\ConfigurableFieldManager::createField(), where the field config is created in this snippet:

    $field = FieldConfig::create([
      'field_storage' => $field_storage,
      'bundle' => $bundle,
      'label' => $field_definition->getLabel(),
      // Missing description.
      'required' => $field_definition->isRequired(),
      'settings' => $field_definition->getSettings(),
      'translatable' => $field_definition->isTranslatable(),
      'default_value' => $field_definition->getDefaultValueLiteral(),
      'default_value_callback' => $field_definition->getDefaultValueCallback(),
    ]);
    $field->save();

Suggestion

Add one line, 'description' => $field_definition->getDescription() ?? '',

Feature request
Status

Active

Version

3.0

Component

User experience

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

Production build 0.71.5 2024