How to name fields in Drupal

The hardest thing in software development - is naming. Whether it is a variable, class name, or field naming in Drupal, it might be complicated. By naming, I write about the machine name itself. I'll write about my naming convention in Drupal that I will use daily basis and what are the benefits. I really like consistency in my work and I have used one specific pattern that I currently like. Maybe you already use it, maybe not, but I'll try to explain it in my own words.

Let's start with what kind of fields we have in Drupal - base fields on entities and fields created by Field API. I would break Field API into half - there are single and reusable fields. The same naming pattern will apply to other machine names as well (views, paragraph types, etc where it seems reasonable). The reusability is limited to entity type.

Field API fields

We have two types of fields here - single-use and reusable. Whether it is reusable or not, it needs some planning - is it possible to share it or is it only specific to that one component?  If there is a chance that it could be reused then consider it as reusable.

The common pattern for single-use fields I create is that I prefix them with specific components, whether it is a content type, paragraph type, etc. So, for example, if I have a content type called article and I need a field for a thumbnail, I would name it like field_article_thumbnail. Assuming I have an accordion created as a Paragraph, it most likely is nested and the naming would be something like - create 2 paragraph types - accordion and accordion_item. The field I attached accordion itself would be named as field_accordion_item. The name for the accordion item title would be field_accordion_item_title. If there is a title for the accordion component itself, it will be attached to the accordion paragraph and the title will be field_accordion_title.

For reusable fields I use similar logic as for base fields - they are based on functionality - for example I have two or more content types that need a media field for the hero area, I would name it field_media or field_hero_media. In the case of media fields, I would use generic naming as it is possible that you may need to use images and videos and it is more logical to attach them to field_media than field_image or something.

Base fields

Base field naming is quite easy - they are not reusable and are attached to specific entities only. I mostly name them based on what they are. As an example, if  I have an entity called Employee, and need to add an employee photo to it, I would simply use the name avatar or photo. They are acting like reusable fields - they are available to all entity bundles.

Benefits

For me the most beneficial is consistency and predictability - I know what the field is related to and its purpose - reusable or not. This is useful on bigger projects where things can go messy over time. 

You may find It useful if you are building some distro where the functionality is divided into modules - it is hard to separate configuration if the fields are reused - the storage configuration is the same and you need to put them under /config/optional to make sure these modules can be enabled independently or at the same time (it can throw an error about field storage already exists).

If you integrate this pattern into your project, other devs can follow it and instead of a mess, you have consistent naming on your project.

It can help with debugging - if there are errors you can quickly associate it with some specific functionality.

Downsides

There are downsides. If you need to make it reusable, either accept the unrelated name prefix or create a new field, migrate things over, and delete the old field.

Creating single-use fields instead of reusing fields adds additional tables to the database. Reusing them could be one goal - you can't reuse field_event_location but you can reuse field_article_media as field_media.

Similar fields have similar templates and you need to create their own - twig has extend you can use or use components (SDC for example).

Issues with machine names that are too long - the length is limited. Most of the time it is caused by the longer prefix, that you could shorten (but should be consistent with other fields to use the same prefix) or use a different name instead of field_article_content, use field_article_body

Buy Me a Coffee at ko-fi.com

Add new comment