Defining a custom entity with annotationsfor Drupal 8 , 9 , 10 , and 11

Introduction

Building on our understanding of Drupal entities and the entity_type.manager service, this lesson focuses on defining a custom entity. Custom entities allow you to tailor Drupal's storage and data structure to fit unique needs within your site architecture. We'll employ annotations to define these entities, a common and powerful tool in Drupal's ecosystem, enabling the automatic recognition of new entity types by the system.

Understanding Annotations

Annotations in Drupal are a way of adding metadata to your code, which helps Drupal understand what the code reflects and how it should behave:

• Metadata: Informational tags that define the properties and behaviors of your entity.
• Drupal Discovery: Annotations allow Drupal to autodiscover entity types without additional configuration.

Setting Up Your Custom Entity

For this tutorial, we'll create a simple Contact Message entity. Follow these steps to define the entity using annotations:

Step 1: Create Required Files

Ensure you have a custom module setup as discussed in previous lessons. In your module's folder structure, create:

• src/Entity/ContactMessage.php

Step 2: Define the Entity with Annotations

Open ContactMessage.php and use the following code:

namespace Drupal\custom_module\Entity;

use Drupal\Core\Entity\ContentEntityBase;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Field\BaseFieldDefinition;

/**
 * Defines the Contact Message entity.
 *
 * @ContentEntityType(
 *   id = "contact_message",
 *   label = @Translation("Contact Message"),
 *   handlers = {
 *     "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
 *     "list_builder" = "Drupal\custom_module\ContactMessageListBuilder",
 *     "views_data" = "Drupal\views\EntityViewsData",
 *     "form" = {
 *       "default" = "Drupal\custom_module\Form\ContactMessageForm",
 *       "add" = "Drupal\custom_module\Form\ContactMessageForm",
 *       "edit" = "Drupal\custom_module\Form\ContactMessageForm",
 *       "delete" = "Drupal\custom_module\Form\ContactMessageDeleteForm",
 *     },
 *   },
 *   base_table = "contact_message",
 *   admin_permission = "administer contact message entity",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "name",
 *   },
 *   links = {
 *     "canonical" = "/admin/structure/contact_message/{contact_message}",
 *     "edit-form" = "/admin/structure/contact_message/{contact_message}/edit",
 *     "delete-form" = "/admin/structure/contact_message/{contact_message}/delete",
 *     "collection" = "/admin/structure/contact_message",
 *   },
 *   field_ui_base_route = "contact_message.settings"
 * )
 */
class ContactMessage extends ContentEntityBase {
  public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
    $fields = parent::baseFieldDefinitions($entity_type);

    $fields['name'] = BaseFieldDefinition::create('string')
      ->setLabel(t('Name'))
      ->setDescription(t('The name of the Contact Message.'))
      ->setRequired(TRUE)
      ->setSettings([
        'max_length' => 50,
      ]);

    $fields['email'] = BaseFieldDefinition::create('email')
      ->setLabel(t('Email'))
      ->setDescription(t('Contact email address.'))
      ->setRequired(TRUE);

    $fields['message'] = BaseFieldDefinition::create('text_long')
      ->setLabel(t('Message'))
      ->setDescription(t('The message content.'));

    return $fields;
  }
}

Here's a brief description of what's happening in the code:

• @ContentEntityType annotation describes the entity's type and provides key metadata.
• Entity Handlers: Specify how to build views, handle forms, etc.
• Base Table: Specifies the database table for entity storage.
• Field Definitions: Default fields for the entity such as name, email, and message are defined with types and settings.

Conclusion

In this lesson, you defined a custom entity using annotations, establishing a unique structure for data management in your Drupal site. Custom entities empower developers to extend Drupal beyond its out-of-the-box capabilities, offering tailor-made solutions tailored to specific application needs.

Teaser for the Next Lesson

In our next lesson, we will cover adding storage, access, and form handlers to further enrich our custom entity. These elements are essential for ensuring complete integration and functional entity management within Drupal. Make sure not to miss it!