Fields

This cheat sheet provides an overview of commonly used methods, classes, and interfaces for content entities.

Download

/sites/default/files/drupal-content-entity-8.0.pdf

Content entities inherit much of their behavior from entities. See Working with the Entity API for these shared features.

Managing Field Values

Create custom fields using the baseFieldDefinitions method for your content entity.

• Load a custom entity instance into a local variable $Custom_Entity
• Define a custom field named "custom_field"
• Store some data

Code Example

$custom_field_value = $Custom_Entity->custom_field->value;
// Perform some kind of data manipulation
$Custom_Entity->custom_field->value = $custom_field_value;
$Custom_Entity->save();

Example content entities:

• node
• comment
• user

Configuration entities use the Entity API to store configuration in the database.

Differences from Content Entities

• Integrates with the CMI API for export capabilities
• No fields
• Uses schema file (Content Entities use hook_schema())

Tutorials

• Drupal example: Creating a configuration entity type in Drupal 8
• Change record: https://www.drupal.org/node/1818734

In Drupal 8, bundles are a type of container for information that holds field definitions or settings. They are sometimes referred to as "subtypes." Bundles are optional and sit below entity types in the hierarchy of information containers.

• Entity variants (content and configuration; many entities are paired, e.g., blocks)

- Entity Types
- Bundles or subtypes (optional)

Examples of these container types:

• Entity variants:

1) Content
Content entity types:
1. Node:
- Node bundles, also known as content types:
* Article
* Basic Page

2. Taxonomy
- Taxonomy bundles, also known as vocabularies:

* <Vocabulary A>
* <Vocabulary B>
* <Vocabulary Etc.>

3. Blocks
- Custom Block Bundles, also known as Block Types:

* <Block Type L>
* <Block Type M>
* <Block Type Etc.>

4. User (no child bundles)
5. <Custom content entity type X>
6. <Custom content entity type Y>
7. <Custom content entity type Etc.>

2) Configuration
Configuration entity types:
* Custom Block types (no child bundles)
* View (no child bundles)
* Menu (no child bundles)
* Role (no child bundles)
* <Custom config entity type I>
* <Custom config entity type II>
* <Custom config entity type Etc.>

Add a Field

To add a field to a Select query, use the addField() method:

$title_field = $query->addField('n', 'title', 'my_title');

The code above tells the query to select the "title" field from the table aliased as "n" and give it the alias "my_title". If no alias is specified, one will be automatically generated. In most cases, the generated alias will just be the field name. In this example, that would be "title". If that alias is already in use, the alias will be "n_title". If that is also in use, a counter will be appended until an unused alias is found, such as "n_title_2".

Note that if you're building and populating a query yourself and do not specify an alias, and the default alias is not available, there is almost certainly a bug in your code. However, if you're writing a hook_query_alter() implementation, you can't know which aliases are already in use, so you should always use the generated alias.

Add Multiple Fields

To select multiple fields, call addField() multiple times in the desired order. Note that in most cases, field order should not matter, and if it does, there may be a flaw in the module's business logic.

Alternatively, you can use the fields() method to add multiple fields at once.

$query->fields('n', ['nid', 'title', 'created', 'uid']);

The method above is equivalent to calling addField() four times, once for each field. However, fields() does not support specifying an alias for the field. It also returns the query object itself, so the method can be chained and does not return any generated aliases. If you need the generated alias, use addField() or getFields() to access the raw internal field structure.

Calling fields() without a list of fields results in a "SELECT *" query.

$query->fields('n');

This will cause "n.*" to be included in the query's field list. Note that aliases will not be created. If the table using SELECT * contains a field that is also referenced directly from another table, a name collision may occur in the result set. In this case, the result set will contain only one of the fields with the common name. For this reason, using SELECT * is discouraged.

Return Only One Field Using fetchField

Use the fetchField method to return only one field with the query, for example the following (somewhat silly) example:

$query = $connection->select('node', 'n');
$query->condition('n.nid', 123);
$query->addField('n', 'title');
$result = $query->execute();
return $result->fetchField();