Field type plugins extend the lower-level TypedData API to create a unique way of not only representing data (within the context of entities), but also storing it to the database (and other stuff as well). They are primarily known as the type of fields site builders can add to an entity type bundle. For example a plain text field or a select list with multiple options. Nothing can be more common than that in a CMS.

However, they are also used as entity base field types. If you remember our product entity type's name field definition, we actually did use these plugin types:

$fields['name'] = BaseFieldDefinition::create('string') 
  ->setLabel(t('Name')) 
  ->setDescription(t('The name of the Product.')) 
  ->setSettings([ 
    'max_length' => 255, 
    'text_processing' => 0, 
  ]) 
  ->setDefaultValue('') 
  ->setDisplayOptions('view', [ 
    'label' => 'hidden', 
    'type' => 'string', 
    'weight' => -4, 
  ]) 
  ->setDisplayOptions('form', [ 
    'type' => 'string_textfield', 
    'weight' => -4, 
  ]) 
  ->setDisplayConfigurable('form', TRUE) 
  ->setDisplayConfigurable('view', TRUE);

The create() method of the definition class accepts a FieldType plugin ID. Also, the type of the view display option provided a bit below in the code is a FieldFormatter plugin ID, whereas the type of the form display option provided even lower in the code is a FieldWidget plugin ID.

A crucial lesson from this recap that I insist you retain: when defining your custom entities, think about the types of fields you need. If there are bundles that need to have different sets of fields, configurable fields are your choice. Otherwise, base fields are perhaps more appropriate. They sit tightly with your Entity type class, appear on all bundles (if that's something you need), and encourage you to explore the Drupal code base and understand the existing field types, widgets, and formatters better (as well as relevant settings they come with).

Also, when you define base fields, think the same way as you would if adding them through the UI—which field type do I want (find a FieldType plugin), how do I want users to interact with it (find a FieldWidget plugin), and how do I want its values to be shown (find a FieldFormatter plugin). Then, inspect the relevant classes to determine the right settings that will go with them.

In this chapter, we will take a look at how we can create our own custom field type with its own default widget and formatter. To provide a bit of continuity, I am going to ask you to think back to the more complex example we used when talking about the TypedData API—the license plate. We will create a field type designed specifically to store license plates in the following format: CODE NUMBER (just as we saw with the example New York plate). Why?

At the moment, there is no field type that can represent this accurately. Of course, we have the simple text field, but that implies having to add both pieces of data that make up a license plate into the same field, stripping them of its meaning. When we were discussing the TypedData API, we saw that one of its core principles is the ability to apply meaning to a piece of data so as to understand that $license_plate (for example) is actually a license plate from which we can ask its code and its number (as well as a general description if we want to). Similar to this (or actually building on top of this), fields are also about storing this data. So, apart from understanding it in code, we also need to persist it in the same way. That is, placing the individual pieces of data in separate meaningful table columns in order to also persist that meaning.

An example from Drupal core that does the same thing is the Text (formatted) field. Apart from its string value, this field also stores a format for each value, which is used upon rendering. Without that format, the string value loses its meaning, and Drupal is no longer able to reliably render it in the way it was intended upon creation. So you can now see that fields take the idea of meaning from TypedData and also apply it to storage as needed. So, in this chapter, you will learn how these three types of plugin work by creating your own license plate type field. Let's get started.