Drupal Core documentation summarised for easy consumption by LLMs

README.md

Drupal AI-Optimized Documentation

This collection of documents is designed to provide AI language models (LLMs) with an in-depth, structured understanding of Drupal's architecture, systems, and design patterns. The documentation is formatted to maximize the AI's ability to comprehend Drupal's complex interconnected systems while providing concrete examples and relationship mappings.

Documentation Purpose

The primary goals of this AI-optimized documentation are to:

1. Enable Better Code Understanding: Help AI models understand the purpose, relationships, and patterns used in Drupal code
2. Improve Suggestion Quality: Provide context for AI to make better recommendations when working with Drupal code
3. Enhance Problem Solving: Give AI models the proper architectural knowledge to identify solutions that align with Drupal best practices
4. Reduce Hallucinations: Provide explicit facts and relationships to minimize AI generating incorrect information about Drupal
5. Speed Up Development: Allow developers to get accurate Drupal-specific help from AI assistants

Documentation Structure

Each document follows a consistent format optimized for AI comprehension:

1. High-Level Overview: Conceptual explanation of the component or system
2. Purpose in Architecture: The role and importance in Drupal's overall design
3. Hierarchical Breakdown: Organized decomposition of internal concepts
4. Concrete Examples: Real code showing implementation patterns
5. Relationships: Explicit connections to other Drupal components
6. Common Patterns and Edge Cases: Typical usage patterns and special situations
7. Concept Map: Visual representation of relationships
8. Quick Reference: Key facts for rapid retrieval
9. AI Recommendation: Guidance on how to apply the knowledge

Core Architecture Topics

• Drupal Kernel and Bootstrap Process
• Service Container Architecture
• Plugin System
• Entity System
• Routing System
• Theme System
• Configuration System
• Cache System

Module Documentation

• Node Module
• Field Module
• Views Module

Development Workflows

• Custom Module Development
• Custom Entity Type Development

Integration Patterns

• Entity-Field Integration
• Form-Entity Integration

How to Use This Documentation

For AI Models:

These documents provide authoritative context about Drupal's architecture. When analyzing Drupal codebases or generating Drupal-related code, reference this documentation to understand the design patterns, relationships between components, and best practices.

For Developers:

When asking AI assistants about Drupal concepts, refer to these documents to give the AI better context for your questions. For example: "Based on the Drupal AI documentation, how would I implement a new plugin type for my module?"

Contributing to AI Documentation

To improve this documentation:

1. Follow the established format for consistency
2. Include concrete code examples from actual Drupal code
3. Explicitly state relationships between components
4. Add concept maps for visual representation
5. Focus on architectural understanding rather than API documentation
6. Update documentation when Drupal's architecture evolves

License

This AI-optimized documentation is available under the same license as Drupal core documentation.

cache-system.md

Drupal Cache System

Tags: Architecture, Core, Performance, Caching, Invalidation

High-Level Overview

The Cache API is Drupal's comprehensive framework for storing and retrieving computed data to improve performance. It provides a cache-friendly architecture based on cache bins, tags, contexts, and max-age metadata that allows for precise invalidation strategies. The system supports multiple storage backends, dynamic cache rebuilding, and granular invalidation while maintaining a consistent API across different caching layers.

Purpose in Drupal Architecture

The Cache System serves as a critical performance layer by:

1. Providing a unified API for all caching operations
2. Supporting multiple backend storage mechanisms
3. Enabling precise cache invalidation through tags
4. Defining cache variations through contexts
5. Setting time-based invalidation with max-age
6. Facilitating cache rebuilding with auto-placeholders
7. Promoting a cache-friendly architecture in modules
8. Creating a multilayer cache strategy from static caches to CDNs

By implementing a sophisticated caching strategy, Drupal provides optimal performance while ensuring content freshness and preventing stale data, which is especially important for dynamic, personalized content.

Hierarchical Breakdown

1. Cache Storage Architecture

• CacheBackendInterface: Core interface for cache operations
• Cache Bins: Separate storage pools for different types of data
• MemoryBackend: In-memory caching for the request lifecycle
• DatabaseBackend: Default database storage backend
• ChainedFastBackend: Combining multiple backends for efficiency
• PhpStorageFactory: Compiled PHP storage
• NullBackend: Non-caching implementation for development
• APCu/Redis/Memcached: External cache backends

2. Cache Metadata System

• CacheableMetadata: Object containing cache metadata
• Cache Tags: Identifiers for invalidating sets of cache items
• Cache Contexts: Variations of cached content based on context
• Max-Age: Time-based expiration strategy
• Bubbling: Combining cache metadata up the render tree
• Merging: Combining metadata from multiple sources
• RefinableCacheableDependencyInterface: Allows refining metadata

3. Cache Invalidation

• CacheTagsInvalidator: Service for invalidating by tag
• DatabaseCacheTagsChecksum: Checksum mechanism for tags
• Cache Collector: Gathers cache items for operations
• Cache Stampede Protection: Prevents concurrent rebuilds
• Garbage Collection: Cleaning expired cache items
• Bin Flushing: Clearing entire cache bins
• Tag-based Invalidation: Invalidating by tag pattern

4. Render Caching

• RenderCache: Specialized cache for render arrays
• Dynamic Page Cache: Caching at the page level
• Big Pipe: Streaming cached parts while computing uncacheable parts
• Lazy Builder: Deferred rendering of expensive elements
• Auto-placeholdering: Automatic handling of uncacheable content
• Render Context: Context for the current rendering operation

5. Internal Page Cache

• PageCache Middleware: Full page caching for anonymous users
• PageCacheRequest: Specialized request handling
• PageCacheResponse: Specialized response handling
• Cache Policy Rules: Determining cacheability of requests

Concrete Examples

1. Using the Cache API

// Get a cache backend for a specific bin
$cache = \Drupal::cache('data');

// Store an item in cache with tags and expiration
$cache->set(
  'my_module:computed_data:123',  // Cache ID
  $computed_data,                 // Data to cache
  CacheBackendInterface::CACHE_PERMANENT, // No time-based expiration
  ['node:123', 'my_module:data']  // Cache tags
);

// Retrieve an item from cache
$cached = $cache->get('my_module:computed_data:123');
if ($cached && $cached->data) {
  $computed_data = $cached->data;
}
else {
  // Cache miss: compute the data and store it.
  $computed_data = expensive_computation();
  $cache->set(/* ... */);
}

// Delete a specific cache item
$cache->delete('my_module:computed_data:123');

// Delete multiple cache items by prefix
$cache->deleteAll('my_module:computed_data:');

// Invalidate cache items by tag
\Drupal::service('cache_tags.invalidator')->invalidateTags(['node:123']);

2. Creating a Custom Cache Bin

// In a module's services.yml file
services:
  cache.my_custom_bin:
    class: Drupal\Core\Cache\CacheBackendInterface
    tags:
      - { name: cache.bin }
    factory: ['@cache_factory', 'get']
    arguments: ['my_custom_bin']

// Using the custom cache bin
$cache = \Drupal::service('cache.my_custom_bin');
$cache->set('my_key', $data);

3. Working with Cache Metadata in Render Arrays

// Creating a render array with cache metadata
$build = [
  '#theme' => 'my_theme_hook',
  '#data' => $data,
  '#cache' => [
    'tags' => ['node:' . $node->id(), 'node_list'],
    'contexts' => ['user.permissions', 'languages:language_interface'],
    'max-age' => 3600,  // 1 hour
    'bin' => 'render',
  ],
];

// Adding cache metadata to an existing array
$build['#cache']['tags'][] = 'config:system.menu.main';
$build['#cache']['contexts'][] = 'user.roles';

// Merging cache metadata from multiple sources
$cache_metadata = new CacheableMetadata();
$cache_metadata->addCacheTags(['node:' . $node->id()]);
$cache_metadata->addCacheContexts(['user.permissions']);
$cache_metadata->mergeCacheMaxAge(600);  // 10 minutes

$other_metadata = new CacheableMetadata();
$other_metadata->addCacheTags(['taxonomy_term:' . $term->id()]);

// Merge the two metadata objects
$cache_metadata->merge($other_metadata);

// Apply to a render array
$cache_metadata->applyTo($build);

4. Implementing Cache-aware Services

namespace Drupal\my_module;

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Cache\CacheTagsInvalidatorInterface;

/**
 * Service that performs data processing with caching.
 */
class DataProcessor {

  /**
   * The cache backend.
   *
   * @var \Drupal\Core\Cache\CacheBackendInterface
   */
  protected $cache;

  /**
   * The cache tags invalidator.
   *
   * @var \Drupal\Core\Cache\CacheTagsInvalidatorInterface
   */
  protected $cacheTagsInvalidator;

  /**
   * Constructs a new DataProcessor.
   *
   * @param \Drupal\Core\Cache\CacheBackendInterface $cache
   *   The cache backend.
   * @param \Drupal\Core\Cache\CacheTagsInvalidatorInterface $cache_tags_invalidator
   *   The cache tags invalidator.
   */
  public function __construct(
    CacheBackendInterface $cache,
    CacheTagsInvalidatorInterface $cache_tags_invalidator
  ) {
    $this->cache = $cache;
    $this->cacheTagsInvalidator = $cache_tags_invalidator;
  }

  /**
   * Process data with caching.
   *
   * @param string $input
   *   Input data to process.
   *
   * @return array
   *   Processed data.
   */
  public function processData($input) {
    $cid = 'my_module:processed:' . hash('sha256', $input);
    
    // Try to get from cache first.
    if ($cached = $this->cache->get($cid)) {
      return $cached->data;
    }
    
    // Cache miss, process the data.
    $result = $this->doExpensiveProcessing($input);
    
    // Store in cache.
    $this->cache->set(
      $cid, 
      $result, 
      CacheBackendInterface::CACHE_PERMANENT, 
      ['my_module:processed_data']
    );
    
    return $result;
  }

  /**
   * Invalidate all processed data.
   */
  public function invalidateAll() {
    $this->cacheTagsInvalidator->invalidateTags(['my_module:processed_data']);
  }

  /**
   * Expensive processing operation.
   *
   * @param string $input
   *   Input data.
   *
   * @return array
   *   Processed result.
   */
  protected function doExpensiveProcessing($input) {
    // Simulate expensive operation.
    return [
      'processed' => $input,
      'timestamp' => time(),
    ];
  }
}

5. Using Lazy Builders for Uncacheable Content

// Render array with a lazy builder for dynamic content
$build = [
  '#type' => 'container',
  '#attributes' => ['class' => ['wrapper']],
  
  // Cacheable part
  'cacheable' => [
    '#markup' => '<p>This content is cacheable.</p>',
    '#cache' => [
      'tags' => ['node:1'],
      'contexts' => ['languages:language_interface'],
      'max-age' => 3600,
    ],
  ],
  
  // Uncacheable part as lazy builder
  'dynamic' => [
    '#lazy_builder' => [
      'my_module.lazy_builders:buildDynamicContent', 
      [$current_user->id()]
    ],
    '#create_placeholder' => TRUE,
  ],
];

namespace Drupal\my_module;

/**
 * Lazy builders for dynamic content.
 */
class LazyBuilders {

  /**
   * Builds dynamic, uncacheable content.
   *
   * @param int $user_id
   *   User ID to build content for.
   *
   * @return array
   *   A render array.
   */
  public function buildDynamicContent($user_id) {
    // Load user-specific data that shouldn't be cached.
    $user_data = $this->getUserData($user_id);
    
    return [
      '#markup' => '<div class="dynamic-content">' . $user_data . '</div>',
      '#cache' => [
        'max-age' => 0,  // Never cache
      ],
    ];
  }
  
  /**
   * Get user-specific data.
   */
  protected function getUserData($user_id) {
    // Fetch real-time personalized data...
    return 'Personalized content for user ' . $user_id;
  }
}

Relationships to Other Components

• Render System: Close integration for caching rendered output
• Page Cache Middleware: HTTP-level caching for anonymous users
• Dynamic Page Cache: Per-route caching for all users
• Big Pipe: Streaming cached components with dynamic placeholders
• Database System: Default storage for cache data
• Container/Services: Cache services injection
• Events: Cache invalidation events
• State System: Runtime state vs cached data
• Config System: Configuration entities impact caching
• Plugin System: Plugin discovery caching
• Entity System: Entity caching and cache tag generation
• Theme System: Template renders and preprocessing caching

Common Patterns and Edge Cases

Common Patterns

• Tag-based Invalidation: Using entity-specific tags
• Cache Contexts: User role/permission-based variations
• Hierarchical Tags: Using prefix patterns for related content
• Permanent with Tags: Setting permanent caches with tags for invalidation
• Max-age Combinations: Setting max-age with tags as fallback
• Lazy Loading: Deferring expensive operations with lazy builders
• Cache Bin Segmentation: Separate bins for different types of data
• Stampede Protection: Preventing multiple rebuilds
• Early Returns: Exiting with cached data before expensive operations

Edge Cases

• Personalized Content: Handling user-specific content
• Cache Warming: Pre-populating cache for performance
• Race Conditions: Managing concurrent cache reads/writes
• Large Cache Items: Handling serialization limits
• Multilingual Content: Language as a cache context
• Cache Size Management: Preventing cache storage overload
• Debugging Cache Issues: Finding invalidation problems
• Uncacheable Edge Cases: Truly dynamic content
• Cache Tag Proliferation: Managing large numbers of tags
• Backend Failures: Fallback strategies when cache backends fail

Concept Map

                           ┌─────────────────┐
                           │  Cache System   │
                           └────────┬────────┘
                                    │
         ┌──────────────────┬──────┼──────┬───────────────────┐
         │                  │      │      │                   │
┌────────▼────────┐ ┌───────▼────┐ │ ┌────▼───────┐ ┌─────────▼────────┐
│   Cache API      │ │Cache       │ │ │Cache       │ │  Cache Storage   │
│                  │ │Metadata    │ │ │Invalidation│ │                  │
└──┬───────────────┘ └───────┬────┘ │ └────┬───────┘ └─────────┬────────┘
   │                         │      │      │                   │
┌──▼─────────────┐   ┌──────▼────┐ │ ┌────▼───────┐  ┌────────▼────────┐
│CacheBackendInterface│Cache Tags   │ │Tag-based   │  │Database Backend │
└──────────────────┘   │           │ │Invalidation│  └─────────────────┘
                      ┌▼──────────┐│ └──────┬─────┘
                      │Cache       ││        │         ┌──────────────────┐
                      │Contexts    ││ ┌──────▼─────┐   │Memory Backend    │
                      └───────────┘││ │Check Sum   │   └──────────────────┘
                                   ││ │Mechanism   │
                      ┌───────────┐││ └────────────┘   ┌──────────────────┐
                      │Max-Age    │││                  │Chain Backend     │
                      └───────────┘││                  └──────────────────┘
                                   ││
                                   ││                  ┌──────────────────┐
                       ┌──────────▼▼─────────┐        │Redis/APCu/Memcache│
                       │   Render Caching    │        └──────────────────┘
                       └─────────┬───────────┘
                                 │
                  ┌──────────────┼───────────────┬───────────────┐
                  │              │               │               │
           ┌──────▼─────┐  ┌─────▼────┐   ┌──────▼─────┐  ┌──────▼──────┐
           │Render Cache │  │Big Pipe  │   │Lazy Builders│  │Page Cache   │
           └─────────────┘  └──────────┘   └────────────┘  └─────────────┘

Quick Reference

• Primary Interfaces:

  • CacheBackendInterface: Core caching operations
  • CacheTagsInvalidatorInterface: Tag-based invalidation
  • RefinableCacheableDependencyInterface: Metadata refinement

• Primary Services:

  • cache_factory: Creates backend instances
  • cache.default: Default cache bin
  • cache_tags.invalidator: Invalidates by tag
  • render_cache: Specialized for render arrays
  • page_cache: Full page caching

• Common Cache Bins:

  • bootstrap: Core bootstrap data
  • config: Configuration objects
  • data: Generic module data
  • discovery: Plugin and annotation discovery
  • render: Rendered output
  • dynamic_page_cache: Per-route page caching

• Important Cache Contexts:

  • url: Based on complete URL
  • route: Based on route name
  • languages: Language variations
  • user.roles: User role variations
  • user.permissions: Permission-based variations

• Default Cache Tags Patterns:

  • config:*: Configuration changes
  • node:*: Node content
  • taxonomy_term:*: Taxonomy term
  • user:*: User changes
  • library_info: Frontend asset changes

AI Recommendation

When working with Drupal's Cache API, consider these approaches:

1. Design with Cache in Mind: Structure your code to separate cacheable and uncacheable parts from the beginning.

// Good: Separate cacheable metadata collection
function getNodes($criteria) {
  $cache = \Drupal::cache();
  $cid = 'my_module:nodes:' . hash('sha256', serialize($criteria));
  
  if ($cached = $cache->get($cid)) {
    return $cached->data;
  }
  
  $result = $this->nodeStorage->loadByProperties($criteria);
  
  // Collect cache tags from all loaded entities
  $tags = ['node_list'];
  foreach ($result as $node) {
    $tags[] = 'node:' . $node->id();
  }
  
  $cache->set($cid, $result, CacheBackendInterface::CACHE_PERMANENT, $tags);
  return $result;
}

2. Use Appropriate Cache Contexts: Only include contexts that actually vary the content.

// Proper use of cache contexts
$build['#cache']['contexts'] = [];

// Always add language if content is translatable
if ($is_translatable) {
  $build['#cache']['contexts'][] = 'languages:language_interface';
}

// Only add user role context if display varies by role
if ($varies_by_role) {
  $build['#cache']['contexts'][] = 'user.roles';
}

// Route-specific caching only if needed
if ($depends_on_route_params) {
  $build['#cache']['contexts'][] = 'route';
}

3. Apply Granular Cache Tags: Use specific tags to prevent over-invalidation.

// Too broad - will invalidate too often
$broad_tags = ['node_list'];

// Better - more granular approach
$specific_tags = ['node_list:article', 'node_list:article:author:' . $author_id];

// Best - hierarchical with entity-specific tags
$build['#cache']['tags'] = [
  'node_list:article',
  'node_list:article:category:' . $category_id,
  'node:' . $node->id(),
  'user:' . $node->getOwnerId(),
];

4. Embrace Cache Bubbling: Let cache metadata bubble up through the render tree.

// Component-level caching with proper tag bubbling
$blog_teaser = [
  '#theme' => 'blog_teaser',
  '#blog' => $blog,
  // No explicit cache tags here - let them bubble up
];

// In the theme preprocess function
function template_preprocess_blog_teaser(&$variables) {
  $blog = $variables['blog'];
  
  // Add cache tags to the render array - these will bubble up
  $variables['#cache']['tags'] = $blog->getCacheTags();
  $variables['#cache']['contexts'] = ['languages:language_interface'];
  $variables['#cache']['max-age'] = 3600;
}

5. Use Lazy Builders for Uncacheable Content: Isolate dynamic content with lazy builders.

// Separate cacheable static content from dynamic user-specific content
$page = [
  'header' => [
    '#theme' => 'header',
    '#cache' => [
      'tags' => ['config:system.site'],
      'contexts' => ['languages:language_interface'],
    ],
  ],
  'content' => [
    '#theme' => 'content',
    '#nodes' => $nodes,
    '#cache' => [
      'tags' => ['node_list'],
      'contexts' => ['languages:language_interface'],
    ],
  ],
  'user_info' => [
    '#lazy_builder' => [
      'my_module.lazy_builders:buildUserInfo',
      [$user->id()],
    ],
    '#create_placeholder' => TRUE,
  ],
];

6. Consider Cache Backend Selection: Choose the right backend for your use case.

// In settings.php for production
$settings['cache']['bins']['render'] = 'cache.backend.redis';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.redis';
$settings['cache']['bins']['page'] = 'cache.backend.redis';

// For frequently accessed data that benefits from in-memory caching
$settings['cache']['bins']['bootstrap'] = 'cache.backend.chainedfast';

7. Implement Cache Stampede Protection: Prevent multiple processes from rebuilding the same cache.

/**
 * Gets cached data with stampede protection.
 */
public function getCachedData($key) {
  $cid = 'my_module:' . $key;
  
  // First try - look for valid cache
  if ($cache = $this->cache->get($cid)) {
    return $cache->data;
  }
  
  // Set a temporary lock while rebuilding
  $lock_key = 'rebuild:' . $cid;
  if (!$this->lock->acquire($lock_key, 30)) {
    // Another process is rebuilding, wait a bit and check again
    sleep(1);
    if ($cache = $this->cache->get($cid)) {
      return $cache->data;
    }
    // Wait for lock to be released or time out
    $this->lock->wait($lock_key, 10);
    if ($cache = $this->cache->get($cid)) {
      return $cache->data;
    }
  }
  
  try {
    // Rebuild the cache
    $data = $this->rebuildCacheData($key);
    $this->cache->set($cid, $data, CacheBackendInterface::CACHE_PERMANENT, ['my_module:' . $key]);
    return $data;
  }
  finally {
    // Always release lock
    $this->lock->release($lock_key);
  }
}

The Cache System is one of Drupal's most important performance features. Understanding its architecture allows you to create efficient, scalable applications that properly balance performance with content freshness. Remember that caching is not just about speed—it's about providing the right data at the right time while efficiently using system resources.

configuration-system.md

Drupal Configuration System

Tags: Architecture, Core, Configuration, Storage, Deployment

High-Level Overview

The Configuration System is Drupal's framework for managing site settings, preferences, and structural elements in a deployment-friendly way. It provides a standardized API for storing and retrieving configuration data, supporting import/export between environments, and managing configuration dependencies. Unlike the Variables system in earlier Drupal versions, the Configuration system stores settings in a structured, typed, and translatable format that can be easily tracked, versioned, and deployed.

Purpose in Drupal Architecture

The Configuration System serves as the foundation for Drupal's deployment capabilities by:

1. Providing a unified API for handling site configuration
2. Separating configuration from content for deployment workflows
3. Supporting schema validation for configuration integrity
4. Enabling configuration overrides for environment-specific settings
5. Facilitating configuration translation for multilingual sites
6. Managing dependencies between configuration objects
7. Supporting staged configuration changes and synchronization
8. Ensuring consistent configuration across environments

By centralizing these capabilities, the Configuration system allows Drupal to provide a robust platform for managing settings across development, staging, and production environments while maintaining the flexibility to customize configuration for specific needs.

Hierarchical Breakdown

1. Configuration Storage

• Storage Interface: Defines methods for reading/writing configuration
• FileStorage: Stores configuration in YAML files
• DatabaseStorage: Stores configuration in database tables
• StorageTransformer: Transforms storage between formats
• StorageComparer: Compares configurations between sources
• CachedStorage: Caches configuration for performance
• ReadOnlyStorage: Prevents modification of configuration

2. Configuration Entities

• ConfigEntityInterface: Interface for configuration entities
• ConfigEntityBase: Base class for configuration entities
• ConfigEntityType: Entity type for configuration
• ConfigEntityStorage: Storage handler for config entities
• ConfigImporter: Handles configuration entity imports
• ConfigManager: Manages configuration entities

3. Configuration Schema

• TypedConfigManager: Manages configuration schemas
• Schema Definitions: YAML files defining configuration structure
• Data Types: Primitive and complex configuration types
• SchemaCheckTrait: Validates configuration against schema
• Configuration Mapping: Maps configuration to schema types
• Schema Discovery: Finds schema definitions for configuration

4. Configuration Override System

• ConfigFactoryInterface: Provides configuration with overrides
• ConfigFactory: Default implementation of factory interface
• OverrideableConfigFactoryInterface: Supports configuration overrides
• ConfigCrudEvent: Events for configuration lifecycle
• LanguageConfigFactoryOverride: Language-specific overrides
• ModuleOverrideOverrideConfigFactoryProxy: Module overrides
• SettingsConfigFactoryOverride: Settings.php overrides

5. Configuration Synchronization

• ConfigImporter: Handles configuration import/export
• StorageComparer: Compares source and target configurations
• ConfigDiffer: Finds differences between configurations
• ConfigReverter: Reverts configuration changes
• ConfigSorter: Sorts configuration for dependencies
• ConfigSyncInterface: Handles synchronization operations
• ConfigEvents: Events for synchronization lifecycle

Concrete Examples

1. Defining a Simple Configuration

// my_module.settings.yml (default configuration)
example_setting: 'default value'
complex_setting:
  key1: value1
  key2: value2
boolean_setting: true
numeric_setting: 42

// Creating a schema for the configuration
// config/schema/my_module.schema.yml
my_module.settings:
  type: config_object
  label: 'My module settings'
  mapping:
    example_setting:
      type: string
      label: 'Example setting'
    complex_setting:
      type: mapping
      label: 'Complex setting'
      mapping:
        key1:
          type: string
          label: 'Key 1'
        key2:
          type: string
          label: 'Key 2'
    boolean_setting:
      type: boolean
      label: 'Boolean setting'
    numeric_setting:
      type: integer
      label: 'Numeric setting'

2. Using Simple Configuration

// Getting configuration values
$config = \Drupal::config('my_module.settings');
$value = $config->get('example_setting');
$complex = $config->get('complex_setting');
$key1_value = $config->get('complex_setting.key1');

// Setting configuration values
$config = \Drupal::configFactory()->getEditable('my_module.settings');
$config->set('example_setting', 'new value');
$config->set('complex_setting.key1', 'updated value');
$config->save();

3. Defining a Configuration Entity Type

namespace Drupal\my_module\Entity;

use Drupal\Core\Config\Entity\ConfigEntityBase;

/**
 * Defines the Example configuration entity.
 *
 * @ConfigEntityType(
 *   id = "example",
 *   label = @Translation("Example"),
 *   handlers = {
 *     "list_builder" = "Drupal\my_module\ExampleListBuilder",
 *     "form" = {
 *       "add" = "Drupal\my_module\Form\ExampleForm",
 *       "edit" = "Drupal\my_module\Form\ExampleForm",
 *       "delete" = "Drupal\my_module\Form\ExampleDeleteForm"
 *     }
 *   },
 *   config_prefix = "example",
 *   admin_permission = "administer site configuration",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label",
 *     "uuid" = "uuid"
 *   },
 *   links = {
 *     "canonical" = "/admin/structure/example/{example}",
 *     "add-form" = "/admin/structure/example/add",
 *     "edit-form" = "/admin/structure/example/{example}/edit",
 *     "delete-form" = "/admin/structure/example/{example}/delete",
 *     "collection" = "/admin/structure/example"
 *   },
 *   config_export = {
 *     "id",
 *     "label",
 *     "description",
 *     "settings",
 *   }
 * )
 */
class Example extends ConfigEntityBase {

  /**
   * The Example ID.
   *
   * @var string
   */
  protected $id;

  /**
   * The Example label.
   *
   * @var string
   */
  protected $label;

  /**
   * The Example description.
   *
   * @var string
   */
  protected $description;

  /**
   * The Example settings.
   *
   * @var array
   */
  protected $settings = [];

}

4. Using Configuration Entities

// Creating a configuration entity
$example = \Drupal\my_module\Entity\Example::create([
  'id' => 'my_example',
  'label' => 'My Example',
  'description' => 'An example configuration entity',
  'settings' => [
    'foo' => 'bar',
    'baz' => true,
  ],
]);
$example->save();

// Loading a configuration entity
$example = \Drupal\my_module\Entity\Example::load('my_example');

// Updating a configuration entity
$example->set('settings', ['foo' => 'updated']);
$example->save();

// Deleting a configuration entity
$example->delete();

5. Implementing Configuration Schema Validation

// In a form validation handler
public function validateForm(array &$form, FormStateInterface $form_state) {
  // Get the submitted values.
  $values = $form_state->getValues();
  
  // Create a configuration object with the submitted values.
  $config = $this->configFactory->getEditable('my_module.settings');
  $config->set('example_setting', $values['example_setting']);
  
  // Validate the configuration against its schema.
  $validator = \Drupal::service('config.typed');
  $typed_config = $validator->createFromNameAndData(
    'my_module.settings', 
    $config->getRawData()
  );
  
  // Check for schema errors.
  $schema_errors = $typed_config->validateData();
  if (!empty($schema_errors)) {
    foreach ($schema_errors as $error) {
      $form_state->setErrorByName('example_setting', $error);
    }
  }
}

Relationships to Other Components

• Entity System: Configuration entities are a type of entity
• Typed Data API: Used for configuration schema validation
• Module System: Modules define configuration objects and schema
• Translation System: Configuration can be translated
• Form API: Used to create forms for editing configuration
• Services: ConfigFactory and other services provide access
• Database API: Used for DatabaseStorage implementation
• YAML Serialization: Used for configuration import/export
• Event System: ConfigEvents allow reacting to configuration changes

Common Patterns and Edge Cases

Common Patterns

• Default Configuration: Modules provide default configuration
• Configuration Form: Forms for editing configuration
• Configuration Translation: Translating configuration
• Configuration Dependencies: Managing dependencies between configurations
• Configuration Export: Exporting configuration for deployment
• Configuration Override: Overriding configuration in settings.php
• Configuration Collections: Grouping related configurations

Edge Cases

• Circular Dependencies: Configuration objects depending on each other
• Missing Schema: Configuration without schema definitions
• Schema Mismatch: Configuration not matching its schema
• Partial Import: Importing only some configuration objects
• Configuration Entity Conflicts: Conflicts during synchronization
• Environment-Specific Configuration: Managing environment differences
• Configuration in Code: Hard-coded configuration in PHP
• Uninstallation Cleanup: Removing configuration on uninstallation

Concept Map

                             ┌─────────────────┐
                             │ Configuration   │
                             │ System          │
                             └────────┬────────┘
                                      │
          ┌────────────────────┬──────┼──────┬────────────────────┐
          │                    │      │      │                    │
┌─────────▼──────────┐ ┌──────▼──────┐│┌────▼────────┐ ┌─────────▼──────────┐
│ Config Storage     │ │Config Entity││Config Schema │ │ Config Factory      │
└─────────┬──────────┘ └──────┬──────┘│└────┬────────┘ └─────────┬──────────┘
          │                   │       │     │                    │
┌─────────▼──────────┐ ┌──────▼──────┐│┌────▼────────┐ ┌─────────▼──────────┐
│FileStorage        │ │ConfigEntityBase││SchemaMapping│ │Override System     │
└─────────┬──────────┘ └──────┬──────┘│└──────────────┘ └────────────────────┘
          │                   │       │
┌─────────▼──────────┐ ┌──────▼──────┐│
│DatabaseStorage     │ │ConfigStorage ││
└────────────────────┘ └─────────────┘│
                                      │
                          ┌───────────▼────────┐
                          │ Config Synchronizer │
                          └──────────┬─────────┘
                                     │
                        ┌────────────┼────────────┐
                        │            │            │
               ┌────────▼───┐ ┌──────▼─────┐ ┌────▼────────┐
               │ConfigImporter│ │ConfigDiffer│ │ConfigEvents │
               └──────────────┘ └────────────┘ └─────────────┘

Quick Reference

• Primary Interfaces:

  • ConfigFactoryInterface: Access to configuration objects
  • StorageInterface: Storage operations for configuration
  • ConfigEntityInterface: Interface for configuration entities
  • TypedConfigManagerInterface: Configuration schema validation

• Primary Services:

  • config.factory: Configuration objects with overrides
  • config.storage: Active configuration storage
  • config.storage.sync: Synchronization directory storage
  • config.typed: Schema-validated configuration
  • config.manager: Manages configuration entities

• Key Files:

  • core/modules/config/config.services.yml: Service definitions
  • core/lib/Drupal/Core/Config/: Core configuration classes
  • MODULE/config/schema/MODULE.schema.yml: Schema definitions
  • MODULE/config/install/: Default configuration
  • MODULE/config/optional/: Optional configuration

• Common Operations:

  • \Drupal::config('name'): Get configuration object
  • \Drupal::configFactory()->getEditable('name'): Get editable configuration
  • $config->get('key'): Get configuration value
  • $config->set('key', value): Set configuration value
  • $config->save(): Save configuration changes

AI Recommendation

When working with Drupal's Configuration System, consider these approaches:

1. Use Schema Validation: Always define schema for your configuration to ensure integrity.

# Define clear schemas for configuration
my_module.settings:
  type: config_object
  label: 'My module settings'
  mapping:
    timeout:
      type: integer
      label: 'Timeout in seconds'
    api_key:
      type: string
      label: 'API key'

2. Separate Simple and Configuration Entities: Use simple configuration for module settings and configuration entities for content structures.

// Simple configuration for module settings
$config = \Drupal::config('my_module.settings');
$timeout = $config->get('timeout');

// Configuration entities for content structures
$content_type = ContentType::load('article');

3. Handle Dependencies Correctly: Specify dependencies to ensure proper ordering during import/export.

# In a configuration entity YAML file
dependencies:
  module:
    - node
    - taxonomy
  config:
    - field.storage.node.field_tags
    - user.role.editor

4. Use Configuration Factory Correctly: Request editable configuration only when necessary.

// For reading (most common)
$config = \Drupal::config('my_module.settings');
$value = $config->get('some_setting');

// For writing (less common)
$config = \Drupal::configFactory()->getEditable('my_module.settings');
$config->set('some_setting', 'new value')->save();

5. Implement Configuration Forms Properly: Use the configuration form base class.

/**
 * Configuration form for module settings.
 */
class MyModuleSettingsForm extends ConfigFormBase {
  
  /**
   * {@inheritdoc}
   */
  public function getFormId() {
    return 'my_module_settings';
  }
  
  /**
   * {@inheritdoc}
   */
  protected function getEditableConfigNames() {
    return ['my_module.settings'];
  }
  
  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
    $config = $this->config('my_module.settings');
    
    $form['timeout'] = [
      '#type' => 'number',
      '#title' => $this->t('Timeout'),
      '#default_value' => $config->get('timeout'),
    ];
    
    return parent::buildForm($form, $form_state);
  }
  
  /**
   * {@inheritdoc}
   */
  public function submitForm(array &$form, FormStateInterface $form_state) {
    $this->config('my_module.settings')
      ->set('timeout', $form_state->getValue('timeout'))
      ->save();
      
    parent::submitForm($form, $form_state);
  }
}

6. Use Configuration Collections for Isolation: Group related configuration in collections when appropriate.

// Using a configuration collection
$storage = \Drupal::service('config.storage');
$collection_storage = $storage->createCollection('mymodule.collection');
$collection_storage->write('some.config', $data);

7. Provide Sensible Defaults: Always include default configuration in your module.

// config/install/my_module.settings.yml
enabled: true
timeout: 30
display_mode: 'default'
features:
  feature1: true
  feature2: false

The Configuration System is a cornerstone of Drupal's architecture, particularly for site building and deployment. Understanding it thoroughly allows you to create maintainable, deployable modules with proper configuration handling and validation.

custom-entity-type.md

Drupal Custom Entity Type Development

Tags: Development, Entity, API, Extension

High-Level Overview

Custom entity type development is the process of creating new data structures in Drupal that integrate with the Entity API. Custom entities allow developers to define specialized content objects with specific fields, behaviors, and interfaces. By implementing the Entity API, custom entities gain built-in support for CRUD operations, field management, revisions, translations, form handling, rendering, and access control. Custom entity types can serve as configuration objects, content objects, or hybrid structures, and provide a robust foundation for complex data modeling in Drupal applications.

Purpose in Drupal Architecture

Custom entity types serve as a foundational extension point by:

1. Providing a structured way to define and manage specialized data
2. Enabling integration with Drupal's field system for flexible data modeling
3. Supporting standardized operations through the Entity API
4. Creating consistent interfaces for data manipulation
5. Allowing granular access control at the entity and field level
6. Supporting translations and revisions when needed
7. Integrating with Views, REST, JSON:API and other core systems
8. Enabling consistent caching and invalidation through cache tags

By creating custom entity types, developers can build specialized applications on top of Drupal's infrastructure while maintaining compatibility with the rest of the ecosystem. This approach provides the flexibility of custom data structures with the advantages of Drupal's mature entity handling capabilities.

Hierarchical Breakdown

1. Entity Type Definition Components

• Entity Type Interface: Core behavior contract
• Entity Interface: Methods specific to the entity type
• Entity Type Annotation/Attribute: Metadata and configuration
• Entity Class: Implementation of entity behavior
• Entity Keys: Special properties with specific meanings
• Entity Links: Paths to entity operations
• Entity Handlers: Controller classes for specific operations
• Bundle Configuration: Support for subtypes
• Field Mapping: Required and optional fields
• Entity Storage Schema: Database structure

2. Entity Type Handler Classes

• Storage Handler: Entity CRUD operations
• Storage Schema Handler: Database schema definitions
• Access Control Handler: Permission checking
• View Builder: Content rendering
• List Builder: Administrative listings
• Form Handlers: Edit, create, delete operations
• Route Provider: URL path generation
• Translation Handler: Multilingual support
• Revision Handler: Version management
• View Handler: Entity display management

3. Entity Storage and Data Management

• Field Definitions: Structured entity properties
• Base Fields: Fields defined in code
• Bundle Fields: User-configurable fields
• Computed Fields: Dynamically generated values
• Entity Queries: Finding and filtering entities
• Entity References: Relationships between entities
• Entity Collections: Working with multiple entities
• Schema Management: Database table structure
• Cache Integration: Entity and field caching
• Validation: Data constraint enforcement

4. Entity API Integration Points

• Entity Hooks: Core event notifications
• Entity Events: Event dispatcher notifications
• Entity Constraints: Validation rules
• Entity Access: Permission system
• Entity Displays: View and form modes
• Entity UI Routes: Administrative paths
• REST/JSON:API Integration: Web service exposure
• Views Integration: Query and display support
• Search Integration: Content indexing
• Entity Operations: Standard actions

Concrete Examples

1. Basic Content Entity Type Definition

namespace Drupal\my_module\Entity;

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

/**
 * Defines the Product entity.
 *
 * @ContentEntityType(
 *   id = "product",
 *   label = @Translation("Product"),
 *   label_collection = @Translation("Products"),
 *   label_singular = @Translation("product"),
 *   label_plural = @Translation("products"),
 *   label_count = @PluralTranslation(
 *     singular = "@count product",
 *     plural = "@count products",
 *   ),
 *   handlers = {
 *     "view_builder" = "Drupal\my_module\ProductViewBuilder",
 *     "list_builder" = "Drupal\my_module\ProductListBuilder",
 *     "access" = "Drupal\my_module\ProductAccessControlHandler",
 *     "form" = {
 *       "default" = "Drupal\my_module\Form\ProductForm",
 *       "add" = "Drupal\my_module\Form\ProductForm",
 *       "edit" = "Drupal\my_module\Form\ProductForm",
 *       "delete" = "Drupal\Core\Entity\ContentEntityDeleteForm",
 *     },
 *     "route_provider" = {
 *       "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
 *     },
 *   },
 *   base_table = "product",
 *   data_table = "product_field_data",
 *   revision_table = "product_revision",
 *   revision_data_table = "product_field_revision",
 *   translatable = TRUE,
 *   revisionable = TRUE,
 *   show_revision_ui = TRUE,
 *   admin_permission = "administer products",
 *   entity_keys = {
 *     "id" = "id",
 *     "revision" = "vid",
 *     "label" = "title",
 *     "uuid" = "uuid",
 *     "langcode" = "langcode",
 *     "published" = "status",
 *   },
 *   revision_metadata_keys = {
 *     "revision_user" = "revision_uid",
 *     "revision_created" = "revision_timestamp",
 *     "revision_log_message" = "revision_log",
 *   },
 *   links = {
 *     "canonical" = "/product/{product}",
 *     "add-form" = "/product/add",
 *     "edit-form" = "/product/{product}/edit",
 *     "delete-form" = "/product/{product}/delete",
 *     "collection" = "/admin/content/products",
 *     "revision" = "/product/{product}/revisions/{product_revision}/view",
 *   },
 *   field_ui_base_route = "entity.product.admin_form",
 * )
 */
class Product extends ContentEntityBase implements ProductInterface {

  /**
   * {@inheritdoc}
   */
  public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
    $fields = parent::baseFieldDefinitions($entity_type);
    
    $fields['title'] = BaseFieldDefinition::create('string')
      ->setLabel(t('Title'))
      ->setRequired(TRUE)
      ->setTranslatable(TRUE)
      ->setRevisionable(TRUE)
      ->setSetting('max_length', 255)
      ->setDisplayOptions('view', [
        'label' => 'hidden',
        'type' => 'string',
        'weight' => -5,
      ])
      ->setDisplayOptions('form', [
        'type' => 'string_textfield',
        'weight' => -5,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
      
    $fields['status'] = BaseFieldDefinition::create('boolean')
      ->setLabel(t('Publishing status'))
      ->setDescription(t('A boolean indicating whether the product is published.'))
      ->setRevisionable(TRUE)
      ->setTranslatable(TRUE)
      ->setDefaultValue(TRUE)
      ->setDisplayOptions('form', [
        'type' => 'boolean_checkbox',
        'settings' => [
          'display_label' => TRUE,
        ],
        'weight' => 0,
      ])
      ->setDisplayConfigurable('form', TRUE);
      
    $fields['sku'] = BaseFieldDefinition::create('string')
      ->setLabel(t('SKU'))
      ->setDescription(t('The unique product identifier.'))
      ->setRequired(TRUE)
      ->setTranslatable(FALSE)
      ->setSetting('max_length', 50)
      ->addConstraint('UniqueField')
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'string',
        'weight' => -4,
      ])
      ->setDisplayOptions('form', [
        'type' => 'string_textfield',
        'weight' => -4,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
      
    $fields['price'] = BaseFieldDefinition::create('decimal')
      ->setLabel(t('Price'))
      ->setDescription(t('The product price.'))
      ->setRequired(TRUE)
      ->setTranslatable(TRUE)
      ->setRevisionable(TRUE)
      ->setSettings([
        'precision' => 10,
        'scale' => 2,
      ])
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'number_decimal',
        'weight' => -3,
      ])
      ->setDisplayOptions('form', [
        'type' => 'number',
        'weight' => -3,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
      
    $fields['description'] = BaseFieldDefinition::create('text_long')
      ->setLabel(t('Description'))
      ->setDescription(t('The product description.'))
      ->setTranslatable(TRUE)
      ->setRevisionable(TRUE)
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'text_default',
        'weight' => -2,
      ])
      ->setDisplayOptions('form', [
        'type' => 'text_textarea',
        'weight' => -2,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
      
    $fields['created'] = BaseFieldDefinition::create('created')
      ->setLabel(t('Created'))
      ->setDescription(t('The time the product was created.'))
      ->setTranslatable(FALSE)
      ->setRevisionable(TRUE);
      
    $fields['changed'] = BaseFieldDefinition::create('changed')
      ->setLabel(t('Changed'))
      ->setDescription(t('The time the product was last edited.'))
      ->setTranslatable(FALSE)
      ->setRevisionable(TRUE);
      
    return $fields;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getTitle() {
    return $this->get('title')->value;
  }
  
  /**
   * {@inheritdoc}
   */
  public function setTitle($title) {
    $this->set('title', $title);
    return $this;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getSku() {
    return $this->get('sku')->value;
  }
  
  /**
   * {@inheritdoc}
   */
  public function setSku($sku) {
    $this->set('sku', $sku);
    return $this;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getPrice() {
    return $this->get('price')->value;
  }
  
  /**
   * {@inheritdoc}
   */
  public function setPrice($price) {
    $this->set('price', $price);
    return $this;
  }
  
  /**
   * {@inheritdoc}
   */
  public function getDescription() {
    return $this->get('description')->value;
  }
  
  /**
   * {@inheritdoc}
   */
  public function setDescription($description) {
    $this->set('description', $description);
    return $this;
  }
  
  /**
   * {@inheritdoc}
   */
  public function isPublished() {
    return (bool) $this->get('status')->value;
  }
  
  /**
   * {@inheritdoc}
   */
  public function setPublished($published) {
    $this->set('status', $published ? TRUE : FALSE);
    return $this;
  }
}

2. Entity Interface Definition

namespace Drupal\my_module;

use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityChangedInterface;
use Drupal\user\EntityOwnerInterface;

/**
 * Provides an interface defining a Product entity.
 */
interface ProductInterface extends ContentEntityInterface, EntityChangedInterface {

  /**
   * Gets the product title.
   *
   * @return string
   *   The product title.
   */
  public function getTitle();

  /**
   * Sets the product title.
   *
   * @param string $title
   *   The product title.
   *
   * @return \Drupal\my_module\ProductInterface
   *   The called product entity.
   */
  public function setTitle($title);

  /**
   * Gets the product SKU.
   *
   * @return string
   *   The product SKU.
   */
  public function getSku();

  /**
   * Sets the product SKU.
   *
   * @param string $sku
   *   The product SKU.
   *
   * @return \Drupal\my_module\ProductInterface
   *   The called product entity.
   */
  public function setSku($sku);

  /**
   * Gets the product price.
   *
   * @return string
   *   The product price.
   */
  public function getPrice();

  /**
   * Sets the product price.
   *
   * @param float $price
   *   The product price.
   *
   * @return \Drupal\my_module\ProductInterface
   *   The called product entity.
   */
  public function setPrice($price);

  /**
   * Gets the product description.
   *
   * @return string
   *   The product description.
   */
  public function getDescription();

  /**
   * Sets the product description.
   *
   * @param string $description
   *   The product description.
   *
   * @return \Drupal\my_module\ProductInterface
   *   The called product entity.
   */
  public function setDescription($description);

  /**
   * Gets the product creation timestamp.
   *
   * @return int
   *   Creation timestamp of the product.
   */
  public function getCreatedTime();

  /**
   * Sets the product creation timestamp.
   *
   * @param int $timestamp
   *   The product creation timestamp.
   *
   * @return \Drupal\my_module\ProductInterface
   *   The called product entity.
   */
  public function setCreatedTime($timestamp);

  /**
   * Returns the product published status indicator.
   *
   * Unpublished products are only visible to restricted users.
   *
   * @return bool
   *   TRUE if the product is published.
   */
  public function isPublished();

  /**
   * Sets the published status of a product.
   *
   * @param bool $published
   *   TRUE to set this product to published, FALSE to set it to unpublished.
   *
   * @return \Drupal\my_module\ProductInterface
   *   The called product entity.
   */
  public function setPublished($published);
}

3. Access Control Handler Implementation

namespace Drupal\my_module;

use Drupal\Core\Entity\EntityAccessControlHandler;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Session\AccountInterface;
use Drupal\Core\Access\AccessResult;

/**
 * Access controller for the Product entity.
 */
class ProductAccessControlHandler extends EntityAccessControlHandler {

  /**
   * {@inheritdoc}
   */
  protected function checkAccess(EntityInterface $entity, $operation, AccountInterface $account) {
    /** @var \Drupal\my_module\ProductInterface $entity */
    switch ($operation) {
      case 'view':
        if (!$entity->isPublished()) {
          return AccessResult::allowedIfHasPermission($account, 'view unpublished products')
            ->addCacheableDependency($entity);
        }
        return AccessResult::allowedIfHasPermission($account, 'view published products')
          ->addCacheableDependency($entity);

      case 'update':
        return AccessResult::allowedIfHasPermission($account, 'edit products')
          ->addCacheableDependency($entity);

      case 'delete':
        return AccessResult::allowedIfHasPermission($account, 'delete products')
          ->addCacheableDependency($entity);
    }

    // Unknown operation, no opinion.
    return AccessResult::neutral();
  }

  /**
   * {@inheritdoc}
   */
  protected function checkCreateAccess(AccountInterface $account, array $context, $entity_bundle = NULL) {
    return AccessResult::allowedIfHasPermission($account, 'create products');
  }
}

4. List Builder Implementation

namespace Drupal\my_module;

use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Entity\EntityListBuilder;
use Drupal\Core\Url;

/**
 * Provides a list builder for the Product entity.
 */
class ProductListBuilder extends EntityListBuilder {

  /**
   * {@inheritdoc}
   */
  public function buildHeader() {
    $header['id'] = $this->t('ID');
    $header['title'] = $this->t('Title');
    $header['sku'] = $this->t('SKU');
    $header['price'] = $this->t('Price');
    $header['status'] = $this->t('Status');
    return $header + parent::buildHeader();
  }

  /**
   * {@inheritdoc}
   */
  public function buildRow(EntityInterface $entity) {
    /** @var \Drupal\my_module\ProductInterface $entity */
    $row['id'] = $entity->id();
    $row['title'] = [
      'data' => [
        '#type' => 'link',
        '#title' => $entity->getTitle(),
        '#url' => $entity->toUrl(),
      ],
    ];
    $row['sku'] = $entity->getSku();
    $row['price'] = [
      'data' => [
        '#markup' => number_format($entity->getPrice(), 2),
      ],
    ];
    $row['status'] = $entity->isPublished() ? $this->t('Published') : $this->t('Unpublished');
    return $row + parent::buildRow($entity);
  }

  /**
   * {@inheritdoc}
   */
  public function render() {
    $build = parent::render();
    $build['table']['#empty'] = $this->t('No products available.');
    return $build;
  }
}

5. Entity Form Implementation

namespace Drupal\my_module\Form;

use Drupal\Core\Entity\ContentEntityForm;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Language\LanguageInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Form controller for the Product entity edit forms.
 */
class ProductForm extends ContentEntityForm {

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
    /* @var $entity \Drupal\my_module\ProductInterface */
    $form = parent::buildForm($form, $form_state);
    
    $form['langcode'] = [
      '#title' => $this->t('Language'),
      '#type' => 'language_select',
      '#default_value' => $this->entity->getUntranslated()->language()->getId(),
      '#languages' => LanguageInterface::STATE_ALL,
    ];
    
    // Add a revision checkbox if the user has permission to create revisions.
    if ($this->currentUser->hasPermission('administer products')) {
      $form['revision_information'] = [
        '#type' => 'details',
        '#title' => $this->t('Revision information'),
        '#open' => TRUE,
        '#weight' => 20,
      ];
      
      $form['revision'] = [
        '#type' => 'checkbox',
        '#title' => $this->t('Create new revision'),
        '#default_value' => TRUE,
        '#group' => 'revision_information',
      ];
      
      $form['revision_log'] = [
        '#type' => 'textarea',
        '#title' => $this->t('Revision log message'),
        '#default_value' => '',
        '#group' => 'revision_information',
        '#states' => [
          'visible' => [
            ':input[name="revision"]' => ['checked' => TRUE],
          ],
        ],
      ];
    }
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function save(array $form, FormStateInterface $form_state) {
    $entity = $this->entity;
    
    // Save as a new revision if requested.
    if (!$form_state->isValueEmpty('revision')) {
      $entity->setNewRevision();
      
      // Set current user as revision author if the form was submitted by this user.
      if ($entity->getRevisionUser()->id() != $this->currentUser()->id()) {
        $entity->setRevisionUserId($this->currentUser()->id());
      }
      
      $entity->setRevisionLogMessage($form_state->getValue('revision_log'));
    }
    
    $status = parent::save($form, $form_state);

    $t_args = ['%title' => $entity->getTitle()];

    switch ($status) {
      case SAVED_NEW:
        $this->messenger()->addMessage($this->t('Created the product %title.', $t_args));
        break;

      default:
        $this->messenger()->addMessage($this->t('Saved the product %title.', $t_args));
    }
    
    $form_state->setRedirect('entity.product.canonical', ['product' => $entity->id()]);
  }
}

6. Configuration Schema for Entity Type

# config/schema/my_module.schema.yml
my_module.product_type.*:
  type: config_entity
  label: 'Product type'
  mapping:
    id:
      type: string
      label: 'ID'
    label:
      type: label
      label: 'Label'
    description:
      type: text
      label: 'Description'
    new_revision:
      type: boolean
      label: 'Create new revision'
    preview_mode:
      type: integer
      label: 'Preview mode'

7. Entity Type Registration in Module File

/**
 * @file
 * Contains hook implementations for my_module.
 */

/**
 * Implements hook_entity_type_build().
 */
function my_module_entity_type_build(array &$entity_types) {
  /** @var \Drupal\Core\Entity\EntityTypeInterface[] $entity_types */
  // Add a constraint to the product entity type.
  if (isset($entity_types['product'])) {
    $entity_types['product']->addConstraint('ProductConstraint', []);
  }
}

/**
 * Implements hook_theme().
 */
function my_module_theme() {
  return [
    'product' => [
      'render element' => 'elements',
    ],
  ];
}

/**
 * Prepares variables for product templates.
 *
 * Default template: product.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - elements: An array of elements to display in the template.
 */
function template_preprocess_product(array &$variables) {
  $variables['view_mode'] = $variables['elements']['#view_mode'];
  foreach (Element::children($variables['elements']) as $key) {
    $variables['content'][$key] = $variables['elements'][$key];
  }
}

Relationships to Other Components

• Entity API: Provides the foundation for entity types
• Field API: Fields attach to entity types
• Plugin API: Entity handlers are often plugins
• TypedData API: Data typing for entity field values
• Database API: Storage for entity data
• Access Control: Permissions and role-based access
• Form API: Form display for entity editing
• Routing System: URL paths for entity operations
• Menu System: Menu integration for entity links
• Views Module: Data visualization for entities
• REST/JSON:API: Web service endpoints for entities
• Cache System: Caching for entity data
• Theme System: Rendering entity data
• Configuration System: Entity type definitions
• Translation System: Multilingual entity support
• Search API: Content indexing and search

Common Patterns and Edge Cases

Common Patterns

• Entity Type Bundles: Subtypes of the main entity type
• Entity Reference Fields: Creating relationships
• Entity Constraints: Data validation
• Entity Hooks: Reacting to entity operations
• Field Definitions: Structured entity properties
• Entity Queries: Finding entities by criteria
• Entity Collections: Working with multiple entities
• Entity Operations: Standard CRUD operations
• View/Form Modes: Contextual display and editing
• Entity Access Control: Permission checking

Edge Cases

• Circular References: Entities referencing each other
• Field Cardinality Changes: Changing allowed values
• Entity Type Updates: Updating entity definitions
• Complex Access Rules: Advanced permission handling
• Translation Edge Cases: Language-specific behavior
• Revision Management: Historical version control
• Computed Field Dependencies: Dynamic field values
• Field Data Migration: Moving between field types
• Schema Updates: Modifying database structure
• Entity Indexing Performance: Handling large datasets

Concept Map

                            ┌─────────────────┐
                            │Custom Entity Type│
                            └────────┬────────┘
                                     │
         ┌───────────────────┬──────┼──────┬───────────────────────┐
         │                   │      │      │                       │
┌────────▼────────┐  ┌───────▼────┐ │ ┌────▼───────┐   ┌───────────▼────────┐
│Entity Definition │  │Entity Class│ │ │Entity      │   │Entity Storage      │
└────────┬────────┘  └───────┬────┘ │ │Handlers    │   └───────────┬────────┘
         │                   │      │ └────┬───────┘               │
┌────────▼────────┐  ┌───────▼────┐ │      │         ┌─────────────▼──────┐
│Content Entity   │  │Entity      │ │ ┌────▼───────┐ │SQL Storage Schema  │
│Configuration    │  │Interface   │ │ │Access      │ └────────────────────┘
└────────┬────────┘  └───────┬────┘ │ │Control     │
         │                   │      │ └────────────┘
┌────────▼────────┐          │      │              ┌────────────────────┐
│Entity Keys      │          │      │ ┌────────────►Form Handlers       │
└────────┬────────┘          │      │ │            └────────────────────┘
         │                   │      │ │
┌────────▼────────┐          │      │ │            ┌────────────────────┐
│Link Templates   │          └──────┼─┼────────────►List Builder        │
└─────────────────┘                 │ │            └────────────────────┘
                                    │ │
                                    │ │            ┌────────────────────┐
                            ┌───────▼─┼────────────►View Builder        │
                            │Field    │            └────────────────────┘
                            │System   │
                            └─────────┼────────────┐
                                      │            │
                             ┌────────▼───┐  ┌─────▼──────┐
                             │Base Fields │  │Bundle Fields│
                             └────────────┘  └────────────┘

Quick Reference

• Primary Classes:

  • ContentEntityBase: Base class for content entities
  • ConfigEntityBase: Base class for configuration entities

• Important Interfaces:

  • ContentEntityInterface: Content entity contract
  • ConfigEntityInterface: Configuration entity contract
  • EntityTypeInterface: Entity type definition contract

• Key Annotation Properties:

  • id: Unique machine name for the entity type
  • label: Human-readable name
  • handlers: Handler class definitions
  • entity_keys: Special properties with specific meaning
  • base_table: Primary database table
  • links: URL templates for entity operations

• Core Entity Keys:

  • id: Primary identifier
  • uuid: Universally unique identifier
  • bundle: Subtype identifier
  • label: Display name
  • langcode: Language code
  • revision: Revision identifier
  • published: Publication status

• Common Entity Handlers:

  • storage: Entity storage controller
  • view_builder: Rendering controller
  • list_builder: Administrative listing
  • form: Form controllers
  • access: Access control handler
  • route_provider: URL provider
  • views_data: Views integration

AI Recommendation

When developing custom entity types in Drupal, consider these approaches:

1. Choose the Right Entity Type: Determine whether your data should be a content entity (for field-able content) or a configuration entity (for site settings).

// Content entity for actual content with fields
/**
 * @ContentEntityType(
 *   id = "product",
 *   // Content entity configuration...
 * )
 */

// Configuration entity for admin-defined structures
/**
 * @ConfigEntityType(
 *   id = "product_type",
 *   // Config entity configuration...
 * )
 */

2. Plan Your Fields Carefully: Design your field structure before implementation, considering cardinality, field types, and storage requirements.

// Defining base fields thoughtfully
public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
  $fields = parent::baseFieldDefinitions($entity_type);
  
  // Consider field properties:
  // - Will it need translation?
  // - Should it be revisioned?
  // - What constraints should it have?
  // - What display options are needed?
  
  $fields['sku'] = BaseFieldDefinition::create('string')
    ->setLabel(t('SKU'))
    ->setRequired(TRUE)
    ->setTranslatable(FALSE) // SKU shouldn't be translated
    ->setRevisionable(FALSE) // SKU shouldn't change per revision
    ->addConstraint('UniqueField'); // Must be unique
  
  return $fields;
}

3. Implement Clean Access Control: Create granular, efficient access checking based on real use cases.

// Efficient access control
protected function checkAccess(EntityInterface $entity, $operation, AccountInterface $account) {
  // Combine context-specific checks with permission checks
  if ($operation === 'view' && $entity->isPublished()) {
    // For viewing published entities, just check permission
    return AccessResult::allowedIfHasPermission($account, 'view published entities')
      ->addCacheableDependency($entity);
  }
  
  // For more complex operations, combine multiple conditions
  if ($operation === 'update') {
    // Allow if user owns the entity AND has edit permission
    if ($account->id() === $entity->getOwnerId()) {
      return AccessResult::allowedIfHasPermission($account, 'edit own entities')
        ->addCacheableDependency($entity)
        ->cachePerUser();
    }
    
    // Or if they have the admin permission
    return AccessResult::allowedIfHasPermission($account, 'administer entities')
      ->addCacheableDependency($entity);
  }
  
  return AccessResult::neutral()->addCacheableDependency($entity);
}

4. Use Entity Queries for Performance: Leverage entity queries for efficient data retrieval.

// Efficient entity queries
$query = $this->entityTypeManager->getStorage('product')
  ->getQuery()
  ->condition('type', 'physical')
  ->condition('status', 1)
  ->condition('price', 100, '<')
  ->sort('created', 'DESC')
  ->accessCheck(TRUE)
  ->range(0, 10);

$entity_ids = $query->execute();
$entities = $this->entityTypeManager->getStorage('product')->loadMultiple($entity_ids);

5. Implement Proper Caching: Add appropriate cache tags and contexts to entity operations.

// Robust cache handling
public function view(array $build = []) {
  $build = parent::view($build);
  
  // Add cache tags for related entities
  if ($this->hasField('field_category') && !$this->get('field_category')->isEmpty()) {
    $category = $this->get('field_category')->entity;
    $build['#cache']['tags'] = Cache::mergeTags($build['#cache']['tags'] ?? [], $category->getCacheTags());
  }
  
  // Add cache contexts for variations
  $build['#cache']['contexts'][] = 'user.permissions';
  
  return $build;
}

6. Design for Translation: Set up translatable fields appropriately from the start.

// Translation-friendly field definitions
$fields['title'] = BaseFieldDefinition::create('string')
  ->setLabel(t('Title'))
  ->setTranslatable(TRUE)
  ->setRevisionable(TRUE);

$fields['sku'] = BaseFieldDefinition::create('string')
  ->setLabel(t('SKU'))
  ->setTranslatable(FALSE); // SKU should be the same across translations

7. Create Meaningful Templates: Design your entity rendering for theme flexibility.

// In template file: templates/product.html.twig
<article{{ attributes.addClass('product') }}>
  {% if content.field_image|render %}
    <div class="product__image">
      {{ content.field_image }}
    </div>
  {% endif %}
  
  <div class="product__content">
    <h2{{ title_attributes }}>{{ label }}</h2>
    
    <div class="product__sku">
      {{ content.sku }}
    </div>
    
    <div class="product__price">
      {{ content.price }}
    </div>
    
    <div class="product__description">
      {{ content.description }}
    </div>
  </div>
</article>

Custom entity types are one of Drupal's most powerful extension mechanisms, allowing developers to create tailored data structures that integrate seamlessly with Drupal's ecosystem. By following these practices, you can create entity types that are performant, maintainable, and leverage Drupal's robust infrastructure for fields, translations, access control, and UI generation.

custom-module-development.md

Drupal Custom Module Development

Tags: Development, Modules, Best Practices, Extension

High-Level Overview

Custom module development is the primary method for extending Drupal's functionality with new features and behaviors. A module is a self-contained package of code, configuration, and optional content that integrates with Drupal's core systems through standardized APIs and hooks. Custom modules allow developers to implement business-specific logic, create new content types, add functionality to existing features, alter system behavior, and integrate with external services while maintaining compatibility with the rest of the Drupal ecosystem.

Purpose in Drupal Architecture

Custom modules serve as the backbone of Drupal's extensibility model by:

1. Providing a structured way to add new functionality
2. Enabling code reuse and sharing between projects
3. Isolating custom logic for easier maintenance
4. Allowing selective enabling/disabling of features
5. Facilitating updates and migrations
6. Creating extension points for further customizations
7. Enabling interactions with core systems through standard interfaces
8. Organizing related functionality into logical units

By following Drupal's module development patterns, developers can create solutions that maintain compatibility with core updates, work well with other modules, and follow best practices for security, performance, and accessibility.

Hierarchical Breakdown

1. Module Architecture Components

• Info File: Defines metadata and dependencies
• Module File: Contains hooks and core functionality
• Services: Provides reusable business logic
• Controllers: Handles HTTP requests
• Plugins: Implements extensible components
• Forms: Creates user input interfaces
• Entity Types: Defines data structures
• Configuration: Stores module settings
• Routing: Maps URLs to controllers
• Permissions: Controls access to functionality
• Theme Integration: Renders content with templates

2. Module Development Workflow

• Scaffold Creation: Setting up initial files
• Dependency Management: Defining requirements
• API Implementation: Using core and contributed APIs
• Testing: Ensuring functionality works as expected
• Documentation: Providing usage instructions
• Packaging: Preparing code for distribution
• Maintenance: Updating for compatibility
• Security: Following secure coding practices

3. Module Integration Points

• Hooks: Integration points with core and other modules
• Events: Responding to system events
• Plugin Types: Implementing standard interfaces
• Services: Providing and consuming functionality
• Entity Types: Defining new content structures
• Configuration: Storing and accessing settings
• UI Components: Adding administrative interfaces
• Theme Layer: Defining output rendering
• Routing System: Handling HTTP requests
• Form System: Creating interactive forms

4. Development Standards

• Coding Standards: PSR and Drupal-specific conventions
• Documentation: PHPDoc and comments
• API Usage: Following established patterns
• Naming Conventions: Consistent identifiers
• File Organization: Standard directory structure
• Configuration Management: Exportable settings
• Dependency Injection: Proper service usage
• Error Handling: Graceful failure recovery
• Performance Considerations: Efficient implementation
• Security Best Practices: Input sanitization and access control

Concrete Examples

1. Basic Module Structure

my_module/
│
├── my_module.info.yml        # Module metadata
├── my_module.module          # Hook implementations
├── my_module.services.yml    # Service definitions
├── my_module.routing.yml     # URL routes
├── my_module.permissions.yml # Permission definitions
├── my_module.links.menu.yml  # Menu links
├── my_module.libraries.yml   # JS/CSS assets
│
├── src/                      # PHP class files
│   ├── Controller/           # Controller classes
│   ├── Form/                 # Form classes
│   ├── Plugin/               # Plugin implementations
│   ├── Entity/               # Entity type definitions
│   └── Service/              # Service classes
│
├── config/                   # Configuration files
│   ├── install/              # Configuration installed with module
│   ├── optional/             # Optional configuration
│   └── schema/               # Configuration schemas
│
├── templates/                # Theme templates
│
├── js/                       # JavaScript files
│
└── css/                      # CSS files

2. Core Files Implementation

# my_module.info.yml
name: My Module
type: module
description: 'Provides custom functionality for my website.'
core_version_requirement: ^10
package: Custom
dependencies:
  - drupal:node
  - drupal:views

// my_module.module

/**
 * @file
 * Contains hook implementations for My Module.
 */

/**
 * Implements hook_theme().
 */
function my_module_theme() {
  return [
    'my_module_display' => [
      'variables' => [
        'items' => [],
        'title' => NULL,
      ],
      'template' => 'my-module-display',
    ],
  ];
}

/**
 * Implements hook_cron().
 */
function my_module_cron() {
  \Drupal::logger('my_module')->notice('My Module cron executed.');
  
  // Execute periodic tasks.
  \Drupal::service('my_module.processor')->processPendingItems();
}

/**
 * Implements hook_entity_presave().
 */
function my_module_entity_presave(Drupal\Core\Entity\EntityInterface $entity) {
  if ($entity->getEntityTypeId() === 'node' && $entity->bundle() === 'article') {
    // Do something when an article node is saved.
    \Drupal::service('my_module.node_handler')->processArticle($entity);
  }
}

# my_module.services.yml
services:
  my_module.processor:
    class: Drupal\my_module\Service\Processor
    arguments: ['@entity_type.manager', '@logger.factory']

  my_module.node_handler:
    class: Drupal\my_module\Service\NodeHandler
    arguments: ['@config.factory', '@current_user']

# my_module.routing.yml
my_module.settings:
  path: '/admin/config/my-module/settings'
  defaults:
    _form: '\Drupal\my_module\Form\SettingsForm'
    _title: 'My Module Settings'
  requirements:
    _permission: 'administer my module'

my_module.data:
  path: '/my-module/data/{id}'
  defaults:
    _controller: '\Drupal\my_module\Controller\DataController::display'
    _title: 'My Module Data'
  requirements:
    _permission: 'access content'
    id: '\d+'

3. Implementing a Controller

namespace Drupal\my_module\Controller;

use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

/**
 * Controller for displaying custom data.
 */
class DataController extends ControllerBase {

  /**
   * The entity type manager.
   *
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected $entityTypeManager;

  /**
   * Constructs a new DataController.
   *
   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
   *   The entity type manager.
   */
  public function __construct(EntityTypeManagerInterface $entity_type_manager) {
    $this->entityTypeManager = $entity_type_manager;
  }

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container) {
    return new static(
      $container->get('entity_type.manager')
    );
  }

  /**
   * Displays data for a specific ID.
   *
   * @param \Symfony\Component\HttpFoundation\Request $request
   *   The request object.
   * @param int $id
   *   The ID of the item to display.
   *
   * @return array
   *   A render array.
   *
   * @throws \Symfony\Component\HttpKernel\Exception\NotFoundHttpException
   *   Thrown when the item does not exist.
   */
  public function display(Request $request, $id) {
    // Load a node with the given ID.
    $node = $this->entityTypeManager->getStorage('node')->load($id);
    
    if (!$node || $node->bundle() !== 'article') {
      throw new NotFoundHttpException('Article not found');
    }
    
    // Build a render array.
    $build = [
      '#theme' => 'my_module_display',
      '#title' => $node->label(),
      '#items' => $this->prepareItems($node),
      '#cache' => [
        'tags' => $node->getCacheTags(),
        'contexts' => ['url.path', 'user.permissions'],
      ],
    ];
    
    return $build;
  }

  /**
   * Prepares items for display.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node entity.
   *
   * @return array
   *   Prepared items.
   */
  protected function prepareItems($node) {
    $items = [];
    
    // Example: Extract field values from the node.
    if ($node->hasField('field_items') && !$node->get('field_items')->isEmpty()) {
      foreach ($node->get('field_items') as $item) {
        $items[] = [
          'value' => $item->value,
          'processed' => $this->processItemValue($item->value),
        ];
      }
    }
    
    return $items;
  }

  /**
   * Processes an item value.
   *
   * @param string $value
   *   The raw value.
   *
   * @return string
   *   The processed value.
   */
  protected function processItemValue($value) {
    // Example processing.
    return ucfirst($value);
  }
}

4. Creating a Service

namespace Drupal\my_module\Service;

use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Logger\LoggerChannelFactoryInterface;

/**
 * Processor service for handling batch operations.
 */
class Processor {

  /**
   * The entity type manager.
   *
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected $entityTypeManager;

  /**
   * The logger channel.
   *
   * @var \Drupal\Core\Logger\LoggerChannelInterface
   */
  protected $logger;

  /**
   * Constructs a new Processor.
   *
   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
   *   The entity type manager.
   * @param \Drupal\Core\Logger\LoggerChannelFactoryInterface $logger_factory
   *   The logger factory.
   */
  public function __construct(
    EntityTypeManagerInterface $entity_type_manager,
    LoggerChannelFactoryInterface $logger_factory
  ) {
    $this->entityTypeManager = $entity_type_manager;
    $this->logger = $logger_factory->get('my_module');
  }

  /**
   * Processes pending items.
   *
   * @return int
   *   The number of items processed.
   */
  public function processPendingItems() {
    $count = 0;
    
    try {
      // Query for nodes that need processing.
      $query = $this->entityTypeManager->getStorage('node')->getQuery()
        ->condition('type', 'article')
        ->condition('field_needs_processing', TRUE)
        ->accessCheck(TRUE)
        ->sort('created', 'ASC')
        ->range(0, 50);
      
      $nids = $query->execute();
      
      if (!empty($nids)) {
        $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($nids);
        
        foreach ($nodes as $node) {
          $this->processNode($node);
          $count++;
        }
        
        $this->logger->notice('@count items processed.', ['@count' => $count]);
      }
    }
    catch (\Exception $e) {
      $this->logger->error('Error processing items: @message', ['@message' => $e->getMessage()]);
    }
    
    return $count;
  }

  /**
   * Processes a single node.
   *
   * @param \Drupal\node\NodeInterface $node
   *   The node to process.
   */
  protected function processNode($node) {
    // Perform processing logic.
    $node->set('field_needs_processing', FALSE);
    $node->set('field_processed_date', time());
    $node->save();
  }
}

5. Implementing a Plugin

namespace Drupal\my_module\Plugin\Block;

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Provides a 'Recent Articles' block.
 *
 * @Block(
 *   id = "my_module_recent_articles",
 *   admin_label = @Translation("Recent Articles"),
 *   category = @Translation("Custom"),
 * )
 */
class RecentArticlesBlock extends BlockBase implements ContainerFactoryPluginInterface {

  /**
   * The entity type manager.
   *
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected $entityTypeManager;

  /**
   * Constructs a new RecentArticlesBlock.
   *
   * @param array $configuration
   *   A configuration array containing information about the plugin instance.
   * @param string $plugin_id
   *   The plugin ID for the plugin instance.
   * @param mixed $plugin_definition
   *   The plugin implementation definition.
   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
   *   The entity type manager.
   */
  public function __construct(
    array $configuration,
    $plugin_id,
    $plugin_definition,
    EntityTypeManagerInterface $entity_type_manager
  ) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
    $this->entityTypeManager = $entity_type_manager;
  }

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
    return new static(
      $configuration,
      $plugin_id,
      $plugin_definition,
      $container->get('entity_type.manager')
    );
  }

  /**
   * {@inheritdoc}
   */
  public function defaultConfiguration() {
    return [
      'max_items' => 5,
      'display_author' => TRUE,
    ] + parent::defaultConfiguration();
  }

  /**
   * {@inheritdoc}
   */
  public function blockForm($form, FormStateInterface $form_state) {
    $form = parent::blockForm($form, $form_state);
    
    $form['max_items'] = [
      '#type' => 'number',
      '#title' => $this->t('Maximum number of items'),
      '#default_value' => $this->configuration['max_items'],
      '#min' => 1,
      '#max' => 20,
    ];
    
    $form['display_author'] = [
      '#type' => 'checkbox',
      '#title' => $this->t('Display author'),
      '#default_value' => $this->configuration['display_author'],
    ];
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    $this->configuration['max_items'] = $form_state->getValue('max_items');
    $this->configuration['display_author'] = $form_state->getValue('display_author');
  }

  /**
   * {@inheritdoc}
   */
  public function build() {
    $max_items = $this->configuration['max_items'];
    $display_author = $this->configuration['display_author'];
    
    // Query for recent articles.
    $query = $this->entityTypeManager->getStorage('node')->getQuery()
      ->condition('type', 'article')
      ->condition('status', 1)
      ->accessCheck(TRUE)
      ->sort('created', 'DESC')
      ->range(0, $max_items);
    
    $nids = $query->execute();
    
    if (empty($nids)) {
      return [
        '#markup' => $this->t('No recent articles available.'),
      ];
    }
    
    $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($nids);
    
    $items = [];
    foreach ($nodes as $node) {
      $item = [
        'title' => $node->label(),
        'url' => $node->toUrl()->toString(),
        'created' => $node->getCreatedTime(),
      ];
      
      if ($display_author) {
        $author = $node->getOwner();
        $item['author'] = $author ? $author->label() : $this->t('Anonymous');
      }
      
      $items[] = $item;
    }
    
    $build = [
      '#theme' => 'my_module_recent_articles',
      '#items' => $items,
      '#display_author' => $display_author,
      '#cache' => [
        'tags' => ['node_list:article'],
        'contexts' => ['user.permissions'],
        'max-age' => 3600,
      ],
    ];
    
    return $build;
  }
}

Relationships to Other Components

• Hooks System: Integration points with core and other modules
• Plugin API: Extensible components with discovery
• Entity API: Creating and managing content and configuration
• Service Container: Defining and consuming services
• Configuration API: Storing and retrieving settings
• Cache API: Performance optimization for expensive operations
• State API: Storing runtime values
• Event System: Subscribing to and dispatching events
• Form API: Building interactive interfaces
• Theme System: Rendering output with templates
• Routing: Mapping URLs to controllers
• Database API: Storing and retrieving custom data
• Block System: Providing placeable content blocks
• Field System: Extending content with custom fields
• Access Control: Implementing permissions and restrictions

Common Patterns and Edge Cases

Common Patterns

• Service-Based Architecture: Organizing business logic in services
• Entity Type Plugins: Creating custom entity types
• Config Entities: Storing structured configuration
• Content Entities: Creating new content types
• Plugin Implementations: Extending existing systems
• Admin UI: Creating administrative interfaces
• Hook Implementations: Altering core behavior
• Dependency Injection: Accessing services properly
• Event Subscribers: Reacting to system events
• Form Workflow: Building multi-step forms

Edge Cases

• Upgrade Path Management: Handling version changes
• Dependency Changes: Adapting to API changes
• Module Interaction: Managing conflicts with other modules
• Access Edge Cases: Complex permission scenarios
• Internationalization: Multilingual considerations
• Migration Support: Helping users upgrade data
• Performance Bottlenecks: Heavy processing requirements
• Batch Processing: Handling large operations
• Error Recovery: Graceful failure handling
• Security Vulnerabilities: Sanitizing inputs and outputs

Concept Map

                              ┌─────────────────┐
                              │Custom Module    │
                              │Development      │
                              └────────┬────────┘
                                       │
         ┌─────────────────────┬──────┼──────┬────────────────────┐
         │                     │      │      │                    │
┌────────▼────────┐  ┌─────────▼───┐  │ ┌────▼───────┐  ┌─────────▼──────┐
│Module Structure  │  │Code         │  │ │Integration │  │Development    │
│and Files         │  │Organization │  │ │Points      │  │Workflow       │
└────────┬─────────┘  └─────────────┘  │ └────┬───────┘  └──────────────┘
         │                             │      │
┌────────▼────────┐                    │ ┌────▼───────┐
│.info.yml        │                    │ │Hooks       │
│.module          │                    │ └────────────┘
│.services.yml    │                    │
│.routing.yml     │                    │ ┌────────────┐
│.permissions.yml │                    │ │Events      │
└─────────────────┘                    │ └────────────┘
                                       │
                                       │ ┌────────────┐
                               ┌───────┼─►Plugins     │
                               │       │ └────────────┘
                               │       │
                               │       │ ┌────────────┐
                       ┌───────▼───┐   └─►Services    │
                       │Core       │     └────────────┘
                       │Components │
                       └───┬───────┘     ┌────────────┐
                           │            ┌►Entity Types│
                           │            │└────────────┘
                  ┌────────┼────────┐   │
                  │        │        │   │┌────────────┐
             ┌────▼──┐ ┌───▼────┐ ┌▼───┼┤Forms       │
             │Routing│ │Services│ │API ││└────────────┘
             └───────┘ └────────┘ └────┘│
                                        │┌────────────┐
                                        └►Theme       │
                                         └────────────┘

Quick Reference

• Essential Files:

  • my_module.info.yml: Module metadata and dependencies
  • my_module.module: Hook implementations
  • my_module.services.yml: Service definitions
  • my_module.routing.yml: URL route definitions
  • my_module.permissions.yml: Permission definitions

• Key Directories:

  • src/: PHP classes
  • config/install/: Configuration to install
  • templates/: Twig templates
  • css/, js/: Frontend assets

• Important Hooks:

  • hook_theme(): Register theme implementations
  • hook_entity_type_alter(): Modify entity definitions
  • hook_form_alter(): Modify forms
  • hook_cron(): Execute periodic tasks
  • hook_menu_local_tasks_alter(): Modify tabs
  • hook_entity_presave(): Act before entity save
  • hook_update_N(): Update functions

• Service Patterns:

  • Service registration in services.yml
  • Dependency injection through constructors
  • Use interfaces for better testing
  • Service tags for discovery

• Common Namespaces:

  • Drupal\my_module\Controller
  • Drupal\my_module\Form
  • Drupal\my_module\Plugin\Block
  • Drupal\my_module\Entity
  • Drupal\my_module\Service

AI Recommendation

When developing custom Drupal modules, consider these approaches:

1. Start Small and Focused: Begin with the minimal code needed for your feature and grow incrementally.

// Start with a simple module structure
my_module/
  my_module.info.yml
  my_module.module
  my_module.services.yml
  src/
    Service/
      MyService.php

2. Use Services for Business Logic: Place your core functionality in services rather than procedural code.

// Good: Service-based approach
services:
  my_module.processor:
    class: Drupal\my_module\Service\Processor
    arguments: ['@entity_type.manager', '@logger.factory']

// In your code
\Drupal::service('my_module.processor')->process();

// Better: With dependency injection
public function __construct(
  ProcessorInterface $processor
) {
  $this->processor = $processor;
}

3. Follow Drupal Coding Standards: Maintain consistent code style for better maintainability.

// Follow PSR and Drupal standards
/**
 * Processes an item.
 *
 * @param int $id
 *   The item ID.
 *
 * @return bool
 *   TRUE if successful, FALSE otherwise.
 */
public function processItem($id) {
  if (empty($id)) {
    return FALSE;
  }
  
  // Use two spaces for indentation.
  // Place operators at the end of the line.
  $result = $this->itemStorage
    ->load($id)
    ->process();
    
  return $result;
}

4. Use Configuration System Properly: Store settings in the configuration system for easier deployment.

// Define schema for configuration
config/schema/my_module.schema.yml:
my_module.settings:
  type: config_object
  label: 'My Module settings'
  mapping:
    timeout:
      type: integer
      label: 'Timeout in seconds'
    display_mode:
      type: string
      label: 'Display mode'

// Access configuration
$config = \Drupal::config('my_module.settings');
$timeout = $config->get('timeout');

// Update configuration
\Drupal::configFactory()
  ->getEditable('my_module.settings')
  ->set('timeout', 120)
  ->save();

5. Implement Proper Caching: Make your module performant from the start.

// Cache implementation with tags and context
public function getItems() {
  $cid = 'my_module:items';
  
  if ($cache = $this->cache->get($cid)) {
    return $cache->data;
  }
  
  $items = $this->loadItems();
  
  // Cache with appropriate tags for invalidation
  $this->cache->set(
    $cid,
    $items,
    CacheBackendInterface::CACHE_PERMANENT,
    ['my_module:items', 'node_list']
  );
  
  return $items;
}

// In render arrays
$build = [
  '#theme' => 'my_items',
  '#items' => $items,
  '#cache' => [
    'tags' => ['my_module:items'],
    'contexts' => ['user.permissions'],
    'max-age' => 3600,
  ],
];

6. Leverage Existing APIs: Don't reinvent what Drupal already provides.

// Use entity API instead of custom tables when appropriate
// Instead of creating custom tables for structured data, create an entity type:

/**
 * @ContentEntityType(
 *   id = "my_item",
 *   label = @Translation("My Item"),
 *   handlers = {
 *     "storage" = "Drupal\my_module\Entity\Storage\MyItemStorage",
 *     "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
 *     "access" = "Drupal\my_module\Entity\Access\MyItemAccessControlHandler",
 *     "form" = {
 *       "default" = "Drupal\my_module\Form\MyItemForm",
 *     },
 *   },
 *   base_table = "my_item",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "title",
 *   }
 * )
 */

7. Build for Testability: Structure your code to be testable from the beginning.

// Use interfaces and dependency injection
interface ProcessorInterface {
  public function process($data);
}

class Processor implements ProcessorInterface {
  public function process($data) {
    // Implementation
  }
}

// In tests
$mock_processor = $this->createMock(ProcessorInterface::class);
$mock_processor->expects($this->once())
  ->method('process')
  ->with($this->equalTo('test data'))
  ->willReturn(TRUE);

$service = new MyService($mock_processor);
$result = $service->doSomething('test data');
$this->assertTrue($result);

Custom module development is the heart of Drupal's extensibility. By following established patterns and best practices, you can create modules that are maintainable, perform well, and integrate seamlessly with the rest of the Drupal ecosystem. Remember that well-structured code with clear responsibilities will be easier to maintain as your project grows and Drupal core evolves.

entity-field-integration.md

Drupal Entity-Field Integration

Tags: Integration, Entity, Field, Content Modeling, Data

High-Level Overview

Entity-Field Integration is the comprehensive system that combines Drupal's Entity API with the Field API to create flexible, structured content models. This integration is central to Drupal's content architecture, allowing entities (like nodes, users, and custom entity types) to be extended with typed, configurable fields. The system provides a standardized way to define, store, validate, and display structured data while maintaining separation between the entity type definitions and their field-based properties, enabling a powerful content modeling system that works consistently across different entity types.

Purpose in Drupal Architecture

The Entity-Field integration serves as the backbone of Drupal's content modeling by:

1. Separating entity definitions from their field properties for flexibility
2. Enabling site builders to extend content types without programming
3. Providing consistent field handling across different entity types
4. Supporting field-level translations and revisions
5. Creating a typed data system with validation and formatting
6. Allowing entity properties to be stored in various backend systems
7. Unifying access control at both entity and field levels
8. Establishing a framework for customizable display and editing interfaces
9. Facilitating structured metadata and field ownership tracking

This integration creates a modular approach to content modeling, where entity types define the foundational structure while fields provide the specific properties, creating a balance between standardization and customization that meets diverse content requirements.

Hierarchical Breakdown

1. Structural Components

• Entity Field Manager: Manages field definitions for entities
• Field Type Plugins: Define data types for fields
• Field Definitions: Describe field properties and settings
• Base Field Definitions: Entity fields defined in code
• Bundle Field Definitions: Fields added through admin UI
• Field Storage Definitions: How fields are stored
• Field Items: Individual field values
• Field Item Lists: Collections of field values
• Field Widgets: UI elements for editing fields
• Field Formatters: Display renderers for field data

2. Field Attachment to Entities

• Fieldable Entity Types: Entities that support fields
• Entity Bundles: Subtypes that can have different fields
• Default Value Functions: Computing initial field values
• Computed Fields: Dynamic fields based on other data
• Required Fields: Mandatory fields for entity creation
• Field Cardinality: Single-value vs. multiple-value fields
• Entity Reference Fields: Creating entity relationships
• Field Constraints: Validation rules for field data
• Field Settings: Configuration for field behavior
• Field Schema: Database structure for field storage

3. Field Data Operations

• Field Accessors: Methods to get/set field values
• Field Data Validation: Ensuring data integrity
• Field Data Normalization: Standardizing input
• Field Value Filtering: Sanitizing outputs
• Field Type Conversion: Transforming between types
• Default Values: Initial field content
• Empty Values: Determining when fields are empty
• Field Access Control: Permissions for field operations
• Field Events: Notifications for field changes
• Field Hooks: Altering field behavior

4. Field Display and Form Integration

• Entity View Display: Configuration for entity rendering
• Entity Form Display: Configuration for entity editing
• View Modes: Context-specific display settings
• Form Modes: Context-specific form settings
• Field Layout: Positioning of fields
• Field Groups: Organizing related fields
• Field Access: Controlling visibility and editability
• Field Templates: Theming for individual fields
• Field Preprocessing: Preparing data for display
• Field Rendering: Converting field data to output

Concrete Examples

1. Defining Base Fields on an Entity Type

/**
 * Implements hook_entity_base_field_info().
 */
function my_module_entity_base_field_info(\Drupal\Core\Entity\EntityTypeInterface $entity_type) {
  $fields = [];
  
  // Add a field to the node entity type.
  if ($entity_type->id() === 'node') {
    $fields['my_custom_field'] = \Drupal\Core\Field\BaseFieldDefinition::create('string')
      ->setLabel(t('My custom field'))
      ->setDescription(t('A custom field added to all nodes.'))
      ->setRevisionable(TRUE)
      ->setTranslatable(TRUE)
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'string',
        'weight' => -4,
      ])
      ->setDisplayOptions('form', [
        'type' => 'string_textfield',
        'weight' => -4,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE)
      ->setRequired(FALSE);
  }
  
  return $fields;
}

2. Adding a Configurable Field to an Entity Bundle

use Drupal\field\Entity\FieldConfig;
use Drupal\field\Entity\FieldStorageConfig;

/**
 * Adds a field to the article content type.
 */
function my_module_add_field_to_article() {
  // Create field storage (the actual place field values are stored).
  $field_storage = FieldStorageConfig::create([
    'field_name' => 'field_article_subtitle',
    'entity_type' => 'node',
    'type' => 'string',
    'settings' => [
      'max_length' => 255,
    ],
    'cardinality' => 1,
  ]);
  $field_storage->save();
  
  // Create the field instance on the bundle.
  $field = FieldConfig::create([
    'field_storage' => $field_storage,
    'bundle' => 'article',
    'label' => 'Subtitle',
    'description' => 'A subtitle for the article.',
    'required' => FALSE,
    'settings' => [
      'text_processing' => 0,
    ],
  ]);
  $field->save();
  
  // Configure field display on the view and form modes.
  entity_get_display('node', 'article', 'default')
    ->setComponent('field_article_subtitle', [
      'type' => 'string',
      'weight' => -3,
      'label' => 'above',
    ])
    ->save();
    
  entity_get_form_display('node', 'article', 'default')
    ->setComponent('field_article_subtitle', [
      'type' => 'string_textfield',
      'weight' => -3,
      'settings' => [
        'size' => 60,
        'placeholder' => '',
      ],
    ])
    ->save();
}

3. Creating a Custom Field Type

namespace Drupal\my_module\Plugin\Field\FieldType;

use Drupal\Core\Field\FieldItemBase;
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\Core\TypedData\DataDefinition;

/**
 * Plugin implementation of the 'my_composite' field type.
 *
 * @FieldType(
 *   id = "my_composite",
 *   label = @Translation("Composite field"),
 *   description = @Translation("This field stores composite values with multiple properties."),
 *   default_widget = "my_composite_default",
 *   default_formatter = "my_composite_default"
 * )
 */
class MyCompositeItem extends FieldItemBase {

  /**
   * {@inheritdoc}
   */
  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    // Define properties for our field.
    $properties['title'] = DataDefinition::create('string')
      ->setLabel(new TranslatableMarkup('Title'))
      ->setRequired(TRUE);
      
    $properties['value'] = DataDefinition::create('string')
      ->setLabel(new TranslatableMarkup('Value'))
      ->setRequired(TRUE);
      
    $properties['notes'] = DataDefinition::create('string')
      ->setLabel(new TranslatableMarkup('Notes'));
      
    return $properties;
  }

  /**
   * {@inheritdoc}
   */
  public static function schema(FieldStorageDefinitionInterface $field_definition) {
    // Define database schema for the field.
    return [
      'columns' => [
        'title' => [
          'type' => 'varchar',
          'length' => 255,
          'not null' => TRUE,
        ],
        'value' => [
          'type' => 'varchar',
          'length' => 255,
          'not null' => TRUE,
        ],
        'notes' => [
          'type' => 'text',
          'size' => 'big',
          'not null' => FALSE,
        ],
      ],
      'indexes' => [
        'title' => ['title'],
        'value' => ['value'],
      ],
    ];
  }

  /**
   * {@inheritdoc}
   */
  public function isEmpty() {
    // Field is considered empty if either title or value is empty.
    $title = $this->get('title')->getValue();
    $value = $this->get('value')->getValue();
    return empty($title) || empty($value);
  }

  /**
   * {@inheritdoc}
   */
  public static function defaultStorageSettings() {
    return [
      'max_length' => 255,
    ] + parent::defaultStorageSettings();
  }

  /**
   * {@inheritdoc}
   */
  public static function defaultFieldSettings() {
    return [
      'notes_required' => FALSE,
    ] + parent::defaultFieldSettings();
  }
}

4. Accessing Field Data on Entities

/**
 * Examples of working with entity field data.
 */
function my_module_field_examples($entity_id) {
  // Load an entity.
  $node = \Drupal::entityTypeManager()->getStorage('node')->load($entity_id);
  
  if (!$node) {
    return;
  }
  
  // Basic field access.
  $title = $node->getTitle();  // Using a getter method for base fields.
  $body = $node->get('body')->value;  // Raw value access for a field.
  $format = $node->get('body')->format;  // Accessing a specific field property.
  
  // Checking if a field exists and has values.
  if ($node->hasField('field_tags') && !$node->get('field_tags')->isEmpty()) {
    // Working with a multi-value field.
    foreach ($node->get('field_tags') as $item) {
      // For entity reference fields, access the target entity.
      $tid = $item->target_id;
      $term = $item->entity;  // Automatically loads the term entity.
      $term_name = $term->getName();
      // Do something with each tag.
    }
  }
  
  // Setting field values.
  $node->set('title', 'New title');  // Single value field.
  
  // Setting a field with multiple properties.
  $node->set('body', [
    'value' => 'New body text',
    'format' => 'full_html',
  ]);
  
  // Setting a multi-value field.
  $node->set('field_tags', [
    ['target_id' => 1],  // First value.
    ['target_id' => 2],  // Second value.
  ]);
  
  // Alternatively, clearing and adding values one by one.
  $node->field_tags = [];  // Clear the field.
  $node->field_tags[] = ['target_id' => 1];  // Add first value.
  $node->field_tags[] = ['target_id' => 2];  // Add second value.
  
  // Working with custom composite fields.
  if ($node->hasField('field_my_composite')) {
    $node->set('field_my_composite', [
      'title' => 'Example Title',
      'value' => 'Example Value',
      'notes' => 'Some detailed notes',
    ]);
    
    // Access composite field values.
    $title = $node->get('field_my_composite')->title;
    $value = $node->get('field_my_composite')->value;
    $notes = $node->get('field_my_composite')->notes;
  }
  
  // Save the entity with updated field values.
  $node->save();
}

5. Field Access Control

/**
 * Implements hook_entity_field_access().
 */
function my_module_entity_field_access($operation, \Drupal\Core\Field\FieldDefinitionInterface $field_definition, \Drupal\Core\Session\AccountInterface $account, \Drupal\Core\Field\FieldItemListInterface $items = NULL) {
  // Control access to a specific field.
  if ($field_definition->getName() === 'field_restricted_data') {
    // Check operation type (view, edit, delete).
    if ($operation === 'view') {
      // Only allow users with a specific permission to view this field.
      return \Drupal\Core\Access\AccessResult::allowedIfHasPermission($account, 'view restricted data');
    }
    elseif ($operation === 'edit') {
      // Only allow users with a specific permission to edit this field.
      return \Drupal\Core\Access\AccessResult::allowedIfHasPermission($account, 'edit restricted data');
    }
  }
  
  // For other fields, don't interfere with access control.
  return \Drupal\Core\Access\AccessResult::neutral();
}

6. Creating a Computed Field

namespace Drupal\my_module\Plugin\Field\FieldType;

use Drupal\Core\Field\FieldItemBase;
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\TypedData\DataDefinition;

/**
 * Plugin implementation of the 'computed_fullname' field type.
 *
 * @FieldType(
 *   id = "computed_fullname",
 *   label = @Translation("Computed full name"),
 *   description = @Translation("Computes full name from first and last name fields."),
 *   default_formatter = "string",
 *   no_ui = TRUE,
 * )
 */
class ComputedFullnameItem extends FieldItemBase {

  /**
   * {@inheritdoc}
   */
  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['value'] = DataDefinition::create('string')
      ->setLabel(t('Full name'))
      ->setComputed(TRUE)
      ->setClass('\Drupal\my_module\TypedData\ComputedFullname');
      
    return $properties;
  }

  /**
   * {@inheritdoc}
   */
  public static function schema(FieldStorageDefinitionInterface $field_definition) {
    // No storage for computed fields.
    return [];
  }

  /**
   * {@inheritdoc}
   */
  public function isEmpty() {
    // This computed field is never empty.
    return FALSE;
  }
}

// In src/TypedData/ComputedFullname.php:
namespace Drupal\my_module\TypedData;

use Drupal\Core\TypedData\TypedDataInterface;
use Drupal\Core\TypedData\ComputedItemListTrait;
use Drupal\Core\TypedData\DataDefinitionInterface;
use Drupal\Core\TypedData\TypedData;
use Drupal\Core\DependencyInjection\DependencySerializationTrait;

/**
 * A computed property for full name.
 */
class ComputedFullname extends TypedData {
  
  use DependencySerializationTrait;
  
  /**
   * {@inheritdoc}
   */
  public function getValue() {
    /** @var \Drupal\Core\Entity\ContentEntityInterface $entity */
    $entity = $this->getParent()->getParent()->getEntity();
    
    if (!$entity->hasField('field_first_name') || !$entity->hasField('field_last_name')) {
      return '';
    }
    
    $first_name = $entity->get('field_first_name')->value ?: '';
    $last_name = $entity->get('field_last_name')->value ?: '';
    
    if (empty($first_name) && empty($last_name)) {
      return '';
    }
    
    return trim($first_name . ' ' . $last_name);
  }
}

7. Creating Entity Fields for Relationships

/**
 * Implements hook_entity_base_field_info().
 */
function my_module_entity_base_field_info(\Drupal\Core\Entity\EntityTypeInterface $entity_type) {
  $fields = [];
  
  // Add entity reference fields to orders.
  if ($entity_type->id() === 'order') {
    // Reference to a single customer.
    $fields['customer'] = \Drupal\Core\Field\BaseFieldDefinition::create('entity_reference')
      ->setLabel(t('Customer'))
      ->setDescription(t('The customer who placed this order.'))
      ->setSetting('target_type', 'user')
      ->setRequired(TRUE)
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'entity_reference_label',
        'weight' => 0,
      ])
      ->setDisplayOptions('form', [
        'type' => 'entity_reference_autocomplete',
        'weight' => 0,
        'settings' => [
          'match_operator' => 'CONTAINS',
          'size' => '60',
          'placeholder' => '',
        ],
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
    
    // Reference to multiple products.
    $fields['products'] = \Drupal\Core\Field\BaseFieldDefinition::create('entity_reference')
      ->setLabel(t('Products'))
      ->setDescription(t('The products in this order.'))
      ->setSetting('target_type', 'product')
      ->setCardinality(\Drupal\Core\Field\FieldStorageDefinitionInterface::CARDINALITY_UNLIMITED)
      ->setRequired(TRUE)
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'entity_reference_label',
        'weight' => 1,
      ])
      ->setDisplayOptions('form', [
        'type' => 'entity_reference_autocomplete',
        'weight' => 1,
        'settings' => [
          'match_operator' => 'CONTAINS',
          'size' => '60',
          'placeholder' => '',
        ],
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
  }
  
  return $fields;
}

Relationships to Other Components

• Entity API: Fields extend entity functionality
• TypedData API: Fields implement typed data interfaces
• Serialization System: Fields can be serialized
• Form API: Fields rendered in forms
• Render System: Fields displayed through render arrays
• Plugin API: Field types, widgets, and formatters are plugins
• Configuration System: Field settings stored as config
• Cache API: Field render caching
• Access Control: Field-level permissions
• Theme System: Field output theming
• Translation System: Field translation
• Views Integration: Fields exposed to Views
• REST/JSON:API: Fields exposed in web services
• Schema API: Field database structures

Common Patterns and Edge Cases

Common Patterns

• Multiple Field Properties: Fields with several sub-values
• Entity Reference Fields: Creating relationships
• Multi-Value Fields: Fields that hold multiple values
• Field Default Values: Predefined initial values
• Field Conditions: Showing/hiding based on conditions
• Field Groups: Organizing related fields visually
• Field Pre-Processing: Preparing field data for display
• Field Validation: Custom validation constraints
• Field Derivatives: Fields based on configuration
• Field Translations: Language-specific field values

Edge Cases

• Field Cardinality Changes: Updating existing fields
• Computed Field Dependencies: Tracking what affects computed fields
• Complex Field Widgets: Advanced UI for editing fields
• Field Schema Changes: Migrating data when changing structure
• Circular Entity References: Self-referential fields
• Revision Handling: Field data in previous revisions
• Field Access Edge Cases: Complex permission scenarios
• Empty Field Determination: What constitutes "empty"
• Default Value Generators: Dynamic default values
• Storage Optimization: Handling large field data sets

Concept Map

                                ┌────────────────────┐
                                │ Entity-Field       │
                                │ Integration        │
                                └─────────┬──────────┘
                                          │
            ┌───────────────────┬─────────┼────────────┬────────────────────┐
            │                   │         │            │                    │
    ┌───────▼───────┐   ┌───────▼─────┐   │    ┌───────▼────────┐   ┌───────▼────────┐
    │ Entity Types  │   │Field Types  │   │    │Field Storage   │   │Field Display   │
    └───────┬───────┘   └───────┬─────┘   │    └───────┬────────┘   └───────┬────────┘
            │                   │         │            │                    │
    ┌───────▼───────┐   ┌───────▼─────┐   │    ┌───────▼────────┐   ┌───────▼────────┐
    │Fieldable      │   │FieldItem    │   │    │StorageDefinition│   │FormatterPlugins│
    │Entities       │   │Interface    │   │    └───────┬────────┘   └────────────────┘
    └───────┬───────┘   └───────┬─────┘   │            │
            │                   │         │            │            ┌────────────────┐
    ┌───────▼───────┐   ┌───────▼─────┐   │    ┌───────▼────────┐  │WidgetPlugins   │
    │Entity Bundles │   │FieldItemBase│   │    │Schema Definition│  └────────────────┘
    └───────────────┘   └─────────────┘   │    └────────────────┘
                                          │
                                ┌─────────▼──────────┐
                                │Field Definition    │
                                │System             │
                                └─────────┬──────────┘
                                          │
                        ┌─────────────────┼─────────────────┐
                        │                 │                 │
                ┌───────▼───────┐ ┌───────▼────────┐ ┌─────▼──────────┐
                │Base Field     │ │Bundle Field    │ │Field Settings  │
                │Definitions    │ │Definitions     │ └────────────────┘
                └───────────────┘ └────────────────┘

Quick Reference

• Primary Interfaces:

  • FieldableEntityInterface: For entities that can have fields
  • FieldItemInterface: For individual field items
  • FieldDefinitionInterface: For field definitions
  • FieldStorageDefinitionInterface: For storage definitions

• Primary Classes:

  • BaseFieldDefinition: For fields defined in code
  • FieldConfig: For fields defined through UI
  • FieldItemBase: Base class for field type plugins
  • FieldItemList: Container for field values

• Field API Entry Points:

  • hook_entity_base_field_info(): Define base fields
  • hook_entity_bundle_field_info(): Define bundle fields
  • hook_entity_field_access(): Control field access
  • hook_entity_field_storage_info(): Define storage

• Key Methods on Entities:

  • hasField($field_name): Check if a field exists
  • get($field_name): Get a field's value
  • set($field_name, $value): Set a field's value
  • getFields(): Get all fields
  • getFieldDefinitions(): Get all field definitions

• Common Field Settings:

  • required: Whether the field is required
  • cardinality: Number of values (use -1 for unlimited)
  • translatable: Whether the field is translatable
  • revisionable: Whether the field is revisionable

AI Recommendation

When working with Entity-Field integration in Drupal, consider these approaches:

1. Design Field Architecture Carefully: Think about field organization before implementation.

// Instead of flat fields with redundancy:
$fields['first_name'] = BaseFieldDefinition::create('string');
$fields['last_name'] = BaseFieldDefinition::create('string');
$fields['shipping_address_line1'] = BaseFieldDefinition::create('string');
$fields['shipping_address_city'] = BaseFieldDefinition::create('string');
$fields['billing_address_line1'] = BaseFieldDefinition::create('string');
$fields['billing_address_city'] = BaseFieldDefinition::create('string');

// Better: Use structured field types
$fields['name'] = BaseFieldDefinition::create('name')
  ->setDescription(t('The name of the customer.'));

$fields['shipping_address'] = BaseFieldDefinition::create('address')
  ->setDescription(t('Shipping address information.'));

$fields['billing_address'] = BaseFieldDefinition::create('address')
  ->setDescription(t('Billing address information.'));

2. Use Entity References for Relationships: Create proper relationships rather than duplicating data.

// Don't duplicate data
$fields['author_name'] = BaseFieldDefinition::create('string');
$fields['author_email'] = BaseFieldDefinition::create('string');

// Better: Reference the user entity
$fields['author'] = BaseFieldDefinition::create('entity_reference')
  ->setSetting('target_type', 'user')
  ->setDescription(t('The author of this content.'));

3. Implement Clean Field Access: Use granular field-level permissions when needed.

/**
 * Implements hook_entity_field_access().
 */
function mymodule_entity_field_access($operation, $field_definition, $account, $items = NULL) {
  // Only check specific fields for specific entities
  if ($field_definition->getName() === 'field_sensitive_data' && 
      $field_definition->getTargetEntityTypeId() === 'node') {
        
    // Get the bundle from items if available
    $bundle = $items ? $items->getEntity()->bundle() : NULL;
    
    // Only protect this field on specific bundles
    if ($bundle === 'confidential_report') {
      return AccessResult::allowedIfHasPermission($account, 'access sensitive data')
        ->cachePerPermissions()
        ->addCacheableDependency($items ? $items->getEntity() : NULL);
    }
  }
  
  return AccessResult::neutral();
}

4. Handle Multi-value Fields Properly: Be careful with field cardinality and values.

// Working with multi-value fields
$entity = Node::load($nid);

// Getting values - use foreach to handle any cardinality
foreach ($entity->field_tags as $item) {
  $term = $item->entity;
  // Process each term
}

// Setting values - use array structure
$entity->field_tags = [
  ['target_id' => 1],
  ['target_id' => 2],
  ['target_id' => 3],
];

// Adding a value
$existing_values = $entity->field_tags->getValue();
$existing_values[] = ['target_id' => 4];
$entity->set('field_tags', $existing_values);

// Or use the array access notation
$entity->field_tags[] = ['target_id' => 5];

5. Use Computed Fields for Derived Data: Don't store what can be computed.

/**
 * Computing a full name from first and last name.
 */
class ComputedFullName extends TypedData {
  public function getValue() {
    $entity = $this->getParent()->getParent()->getEntity();
    
    $first = $entity->get('field_first_name')->value ?: '';
    $last = $entity->get('field_last_name')->value ?: '';
    
    return trim($first . ' ' . $last);
  }
}

6. Leverage Field Display Settings: Configure fields for specific view contexts.

// Configure field display per view mode
\Drupal::service('entity_display.repository')
  ->getViewDisplay('node', 'article', 'teaser')
  ->setComponent('field_image', [
    'type' => 'image',
    'label' => 'hidden',
    'settings' => [
      'image_style' => 'thumbnail',
      'image_link' => 'content',
    ],
    'weight' => -1,
  ])
  ->save();

\Drupal::service('entity_display.repository')
  ->getViewDisplay('node', 'article', 'full')
  ->setComponent('field_image', [
    'type' => 'image',
    'label' => 'hidden',
    'settings' => [
      'image_style' => 'large',
      'image_link' => '',
    ],
    'weight' => -1,
  ])
  ->save();

7. Consider Performance in Field Handling: Be mindful of query impact.

// Inefficient: Loading each entity fully to get one field
foreach ($entity_ids as $id) {
  $entity = Entity::load($id);
  $titles[] = $entity->getTitle();
}

// Better: Use entity query and field conditions
$query = \Drupal::entityQuery('node')
  ->condition('type', 'article')
  ->condition('status', 1)
  ->sort('created', 'DESC')
  ->range(0, 10);
$nids = $query->execute();

// Most efficient: Use specialized storage methods when available
$titles = \Drupal::entityTypeManager()
  ->getStorage('node')
  ->getQuery()
  ->condition('type', 'article')
  ->condition('status', 1)
  ->sort('created', 'DESC')
  ->range(0, 10)
  ->execute();

// Then load only what's needed
$nodes = \Drupal::entityTypeManager()
  ->getStorage('node')
  ->loadMultiple($nids);

The Entity-Field integration is the foundation of Drupal's content modeling capabilities. Understanding the relationship between entities and fields allows you to design flexible, efficient data structures that can evolve with your application's needs while maintaining consistent APIs for data access, validation, and display.

entity-system.md

Drupal Entity System

Tags: Architecture, Core, Entity, Content Modeling, Data Storage

High-Level Overview

The Entity System is Drupal's primary content modeling framework, providing standardized objects that can contain typed, structured, and translatable data. It forms the foundation for virtually all content in Drupal, from nodes and users to configuration objects like views and content types. The Entity API provides a consistent way to create, read, update, delete (CRUD), render, and interact with all types of content through a unified interface.

Purpose in Drupal Architecture

The Entity System serves as the backbone of Drupal's content architecture by:

1. Providing a unified framework for storing and retrieving all types of data
2. Supporting structured content through fields, properties, and metadata
3. Enabling content translation, revisioning, and access control
4. Separating storage from the business logic layer
5. Offering extensibility through custom entity types and fields
6. Creating consistent APIs for content manipulation across the system
7. Facilitating validation and type safety for data integrity

This abstraction layer gives developers consistent patterns for working with diverse content types, while simultaneously enabling end-users to create and customize content models without programming knowledge.

Hierarchical Breakdown

1. Entity Types and Their Definitions

• EntityTypeInterface: Core interface for entity type definitions
• EntityType: Base implementation for all entity type definitions
• ContentEntityType: Entity types for structured content (nodes, users, files)
• ConfigEntityType: Entity types for configuration objects (views, content types)
• EntityTypeManager: Service that discovers and manages entity types
• Entity Type Handlers: Classes that handle various entity operations

2. Entity Classes and Interfaces

• EntityInterface: Base interface for all entities
• ContentEntityInterface: Interface for field-based content entities
• ConfigEntityInterface: Interface for configuration entities
• EntityBase: Abstract base class for all entities
• ContentEntityBase: Base implementation for content entities
• ConfigEntityBase: Base implementation for configuration entities

3. Entity Storage

• EntityStorageInterface: Interface for entity storage operations
• SqlContentEntityStorage: SQL storage for content entities
• ConfigEntityStorage: Config storage for config entities
• RevisionableStorageInterface: Interface for revision handling
• TranslatableStorageInterface: Interface for translation handling
• EntityStorageSchema: Maps entity properties to database columns

4. Entity Field System

• FieldDefinitionInterface: Interface for field definitions
• BaseFieldDefinition: Used for entity base fields
• FieldConfig: Used for user-configurable fields
• FieldItemList: Container for field values
• FieldItemInterface: Interface for individual field items
• Field Types: Implementations for different data types
• Field Formatters: Control how fields are displayed
• Field Widgets: Control how fields are edited

5. Entity Query API

• EntityQueryInterface: Interface for querying entities
• QueryFactory: Creates entity queries for any entity type
• QueryAggregate: Allows aggregate operations on queries
• Condition Groups: For complex query conditions
• Sort Interface: For ordering query results

6. Entity Access Control

• EntityAccessControlHandlerInterface: Interface for entity access
• EntityAccessControlHandler: Base implementation for access control
• FieldAccessControllerInterface: Interface for field-level access
• EntityPermissionProvider: Defines entity permissions

Concrete Examples

1. Defining a Custom Entity Type

namespace Drupal\example\Entity;

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

/**
 * Defines the Example entity.
 *
 * @ContentEntityType(
 *   id = "example",
 *   label = @Translation("Example"),
 *   handlers = {
 *     "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
 *     "list_builder" = "Drupal\example\ExampleListBuilder",
 *     "form" = {
 *       "default" = "Drupal\example\Form\ExampleForm",
 *       "delete" = "Drupal\Core\Entity\ContentEntityDeleteForm",
 *     },
 *     "access" = "Drupal\example\ExampleAccessControlHandler",
 *     "route_provider" = {
 *       "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
 *     },
 *   },
 *   base_table = "example",
 *   admin_permission = "administer site configuration",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "name",
 *     "uuid" = "uuid",
 *   },
 *   links = {
 *     "canonical" = "/admin/structure/example/{example}",
 *     "add-form" = "/admin/structure/example/add",
 *     "edit-form" = "/admin/structure/example/{example}/edit",
 *     "delete-form" = "/admin/structure/example/{example}/delete",
 *     "collection" = "/admin/structure/example",
 *   }
 * )
 */
class Example extends ContentEntityBase {

  /**
   * {@inheritdoc}
   */
  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 Example entity.'))
      ->setSettings([
        'max_length' => 255,
        'text_processing' => 0,
      ])
      ->setDefaultValue('')
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'string',
        'weight' => -4,
      ])
      ->setDisplayOptions('form', [
        'type' => 'string_textfield',
        'weight' => -4,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE)
      ->setRequired(TRUE);

    $fields['description'] = BaseFieldDefinition::create('text_long')
      ->setLabel(t('Description'))
      ->setDescription(t('A description of the example.'))
      ->setDisplayOptions('view', [
        'label' => 'above',
        'type' => 'text_default',
        'weight' => 0,
      ])
      ->setDisplayOptions('form', [
        'type' => 'text_textfield',
        'weight' => 0,
      ])
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);

    $fields['status'] = BaseFieldDefinition::create('boolean')
      ->setLabel(t('Publishing status'))
      ->setDescription(t('A boolean indicating whether the Example is published.'))
      ->setDefaultValue(TRUE)
      ->setDisplayOptions('form', [
        'type' => 'boolean_checkbox',
        'weight' => -3,
      ]);

    return $fields;
  }
}

2. Creating and Saving an Entity

// Create a new node programmatically.
$node = Node::create([
  'type' => 'article',
  'title' => 'My Article Title',
  'body' => [
    'value' => 'This is the article body text',
    'format' => 'basic_html',
  ],
  'status' => TRUE,
  'uid' => 1,
]);

// Save the node.
$node->save();

// Update an existing entity.
$node->setTitle('Updated Title');
$node->set('field_tags', [1, 2]);
$node->save();

3. Loading and Querying Entities

// Load a single entity by ID.
$node = Node::load(1);

// Load multiple entities by their IDs.
$nodes = Node::loadMultiple([1, 2, 3]);

// Using the entity query API.
$query = \Drupal::entityQuery('node')
  ->condition('type', 'article')
  ->condition('status', 1)
  ->condition('field_tags.target_id', 5)
  ->range(0, 10)
  ->sort('created', 'DESC');
$nids = $query->execute();

// Load the results.
$articles = Node::loadMultiple($nids);

4. Using Field API with Entities

// Accessing field values.
$title = $node->getTitle();
$body = $node->get('body')->value;

// Field with multiple values.
if ($node->hasField('field_images') && !$node->get('field_images')->isEmpty()) {
  foreach ($node->get('field_images') as $item) {
    $fid = $item->target_id;
    $image = File::load($fid);
    $url = $image->createFileUrl();
  }
}

// Setting field values.
$node->set('field_date', '2023-01-15');
$node->get('field_paragraphs')->appendItem([
  'target_id' => $paragraph->id(),
  'target_revision_id' => $paragraph->getRevisionId(),
]);

Relationships to Other Components

• Field API: Provides the foundation for entity field storage and manipulation
• TypedData API: Underlies the Entity API for data validation and type handling
• Configuration System: Config entities store and manage configuration objects
• Form API: EntityForms provide entity editing capabilities
• Views: Entities can be displayed and filtered through Views
• Routing: Entity routes provide URL paths for entity operations
• Access Control: Entity access control integrates with Drupal's permission system
• Plugin System: Many entity handlers are implemented as plugins
• REST/JSON:API: Entities can be exposed through REST and JSON:API endpoints

Common Patterns and Edge Cases

Common Patterns

• Entity Type Plugins: Using plugin-based architecture for entity handlers
• Entity Bundles: Subtypes of entities that can have different fields
• Fieldable Entities: Adding fields to structured content
• Entity References: Creating relationships between entities
• Entity Displays: Using view modes and form modes for different contexts
• Entity Builders: Handling the entity building process
• Entity Constraints: Implementing validation constraints
• Entity Hooks: Altering and reacting to entity operations

Edge Cases

• Revisions without Bundle Support: Managing revisions for entity types without bundles
• Entity Validation Recursion: Handling nested entity validation
• Schema Updates: Handling schema changes when entity fields change
• Field Data Migration: Migrating content when field definitions change
• Entity Access Caching: Ensuring entity access is properly cached
• Entity Cache Invalidation: Managing cache tags for entity references
• Default Values: Handling computed default values during entity creation
• Entity Translations: Managing translations with or without revisions

Concept Map

                                       ┌─────────────────┐
                                       │  Entity API     │
                                       └────────┬────────┘
                                                │
                  ┌───────────────────┬─────────┼───────────────┬────────────────┐
                  │                   │         │               │                │
       ┌──────────▼─────────┐ ┌──────▼──────┐  │         ┌─────▼─────┐   ┌─────▼──────┐
       │ Entity Type System │ │ Entity Class │  │         │ Field API │   │ Entity     │
       └──────────┬─────────┘ └──────┬──────┘  │         └─────┬─────┘   │ Access     │
                  │                  │         │               │         └─────────────┘
       ┌──────────▼─────────┐        │   ┌─────▼─────┐   ┌─────▼────────────┐
       │                    │        │   │           │   │                  │
┌──────▼───────┐ ┌─────────▼──────┐ │   │ ┌─────────▼───▼──┐ ┌─────────────▼─────┐
│ContentEntity │ │ConfigEntityType│ │   │ │FieldDefinition│ │FieldItemInterface │
└──────────────┘ └────────────────┘ │   │ └────────────────┘ └───────────────────┘
                                    │   │
                          ┌─────────▼───▼──┐ ┌──────────────────┐
                          │EntityInterface │ │EntityQueryFactory│
                          └┬───────────────┘ └───────┬──────────┘
                           │                         │
                  ┌────────▼────────┐      ┌─────────▼─────────┐
                  │                 │      │                   │
          ┌───────▼─────┐ ┌────────▼─────┐│EntityQueryInterface│
          │ContentEntity│ │ConfigEntityBase└───────────────────┘
          └─────────────┘ └──────────────┘

Quick Reference

• Primary Interfaces:

  • EntityInterface: Base interface for all entities
  • ContentEntityInterface: Interface for content entities
  • ConfigEntityInterface: Interface for configuration entities
  • EntityTypeInterface: Interface for entity type definitions
  • EntityStorageInterface: Interface for entity storage

• Primary Services:

  • entity_type.manager: Central service for entity type operations
  • entity_type.repository: Repository of entity type information
  • entity_type.bundle.info: Provides bundle information
  • entity_field.manager: Manages fields for entity types
  • entity.query: Factory for entity queries

• Entity Type Properties:

  • ID: Unique machine name (id)
  • Label: Human-readable name (label)
  • Class: Implementation class (class)
  • Provider: Module providing the entity type (provider)
  • Handlers: Classes for specific entity operations (handlers)
  • Entity Keys: Property keys for core entity behaviors (entity_keys)
  • Links: Routes for entity operations (links)

• Common Entity Types:

  • node: Main content entities
  • user: User accounts
  • taxonomy_term: Categories
  • file: Uploaded files
  • media: Media entities (images, videos, etc.)
  • block_content: Custom block content
  • node_type: Content type definitions (config entity)
  • view: Views definitions (config entity)

AI Recommendation

When working with Drupal's Entity API, consider these approaches:

1. Start with Built-in Entity Types: Before creating custom entity types, consider if extending an existing type (like Node) would meet your needs.

// Add custom fields to an existing entity type
function mymodule_entity_base_field_info(EntityTypeInterface $entity_type) {
  if ($entity_type->id() === 'node') {
    $fields['my_custom_field'] = BaseFieldDefinition::create('string')
      ->setLabel(t('My Custom Field'))
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayConfigurable('view', TRUE);
    return $fields;
  }
}

2. Use Dependency Injection: Avoid static EntityTypeManager::getInstance() calls. Use dependency injection instead:

// Recommended approach
public function __construct(
  protected readonly EntityTypeManagerInterface $entityTypeManager,
) {}

public function myMethod() {
  $nodes = $this->entityTypeManager->getStorage('node')->loadMultiple($ids);
}

3. Leverage Entity Query API: Use the query API for efficient entity loading:

$query = $this->entityTypeManager->getStorage('node')->getQuery();
$query->condition('type', 'article')
  ->exists('field_image')
  ->accessCheck(TRUE)
  ->sort('created', 'DESC')
  ->range(0, 10);
$entity_ids = $query->execute();

4. Respect Entity Access Control: Always check access when displaying entities:

if ($entity->access('view')) {
  // Render the entity.
  $build = $this->entityTypeManager->getViewBuilder('node')->view($entity);
}

5. Handle Multilingual Entities Correctly: Use the entity translation API:

// Get the translated version of an entity
$translated_entity = $entity->getTranslation($langcode);
$title = $translated_entity->getTitle();

6. Cache Entity Queries: Add cache metadata to entity query results:

$build['#cache']['tags'] = $this->entityTypeManager
  ->getStorage('node')
  ->getEntityType()
  ->getListCacheTags();

7. Handle Revisions Properly: When working with revisionable entities:

// Load a specific revision
$revision = $this->entityTypeManager
  ->getStorage('node')
  ->loadRevision($revision_id);

// Create a new revision
$entity->setNewRevision(TRUE);
$entity->setRevisionCreationTime(time());
$entity->setRevisionUserId($user_id);
$entity->save();

The Entity system is Drupal's most powerful and fundamental API. Understanding its architecture allows you to build sophisticated content models while leveraging Drupal's built-in capabilities for validation, access control, translation, and UI generation.

EXPAND.md

Documentation Expansion Strategy for Drupal Core AI Documentation

You are an expert in both Drupal core architecture and technical documentation. Your task is to systematically expand the AI-optimized documentation for Drupal core, filling gaps in coverage while maintaining the established format and depth.

Documentation Assessment Process

1. Inventory Current Coverage

   • Analyze existing .ai-docs files to understand what's already documented
   • Map the documented components to the Drupal core architecture
   • Identify major architectural areas without documentation

2. Core Architecture Mapping

   • Examine core/lib/Drupal directory structure to identify major subsystems
   • Review module directory structure in core/modules
   • Analyze key service definitions in core/*.services.yml files
   • Survey API hooks in *.api.php files
   • Identify key interfaces that define extension contracts

3. Prioritize Documentation Targets

   • Focus on foundational systems that other components build upon
   • Prioritize subsystems with highest extension/customization value
   • Balance coverage between framework development and application development
   • Include both abstract architecture and practical implementation patterns

Documentation Expansion Categories

For each identified gap, create a new AI-optimized document following the established format. Focus on these categories:

1. Core Subsystems

Expand documentation for critical framework subsystems:

• Entity API: Entity types, fields, storage, and rendering
• Routing System: Route definition, controllers, and HTTP layer
• Theme System: Theme hooks, render arrays, and the render pipeline
• Configuration System: Config entities, schemas, and overrides
• Cache API: Cache tags, contexts, and storage mechanisms

2. Module Ecosystem

Document core modules that developers frequently extend or leverage:

• Content Authoring Modules: Node, Field, Block, Media
• Access Control Modules: User, Permission, Authentication
• Display Modules: Views, Layout Builder, Display Suite
• Development Modules: Devel, Config, Debugging, Testing

For each module, document:

• Primary purpose and core functionality
• Entity types and plugin types it defines
• Services it provides
• Extension hooks and events
• Common development patterns

3. Development Workflows

Document patterns that span multiple subsystems:

• Custom Module Development: Structure, patterns, and best practices
• Custom Entity Type Creation: From definition to UI and storage
• Plugin Development: Common plugin types and implementation patterns
• Service Architecture: Creating and extending services
• Event Subscribers: Event types and subscription patterns

4. Integration Patterns

Document how Drupal systems work together:

• Entity-Field Integration: How entities and fields interact
• Entity-View Integration: Entity display modes and view builders
• Form-Entity Integration: EntityForms and FormDisplay
• Configuration-Entity Integration: Config entities vs. content entities
• Multilingual System: Translation, localization, and language handling

Documentation Generation Workflow

For each identified gap:

1. Research Phase:

   • Examine relevant PHP classes, interfaces, and implementations
   • Review related module files and documentation
   • Identify key dependencies and relationships
   • Understand extension points and hooks

2. Documentation Structure:

   • Follow the established AI documentation format
   • Include high-level overview and purpose
   • Create a hierarchical breakdown of components
   • Provide concrete code examples
   • Document relationships to other components
   • Include common patterns and edge cases
   • Create a concept map showing relationships
   • Add a quick reference section
   • Provide AI recommendations for working with the system

3. Example Collection:

   • Extract real code samples from Drupal core
   • Show both framework-level code and application-level code
   • Include both simple and advanced usage patterns
   • Demonstrate extension points with realistic examples

4. Integration:

   • Link new documents to existing ones
   • Update the main README.md with links to new documents
   • Ensure terminology is consistent across documents

Execution Strategy

To execute this strategy:

1. Start with an initial assessment of existing documentation
2. Create a prioritized list of gaps based on developer value
3. Generate documentation for one category at a time
4. Begin with foundational systems that other documents will reference
5. Continue with frequently used modules and extension patterns
6. Finish with integration patterns that show how components work together

By systematically applying this approach, the AI documentation will evolve to comprehensively cover Drupal's architecture in a way that assists both core contributors and application developers, focusing on the architectural understanding that empowers effective development.

field-module.md

Drupal Field Module

Tags: Module, Core, Field, Entity, Storage

High-Level Overview

The Field module is Drupal's primary system for adding custom data fields to entities. It provides a flexible architecture for defining, storing, displaying, and editing field data of various types across different entity types and bundles. The Field module enables site builders to customize content structures without programming knowledge while offering developers a standardized API for interacting with entity fields. It forms the foundation of Drupal's content modeling capabilities by separating the definition, storage, and display of fields.

Purpose in Drupal Architecture

The Field module serves as a foundational layer of Drupal's content architecture by:

1. Providing a standardized way to attach fields to entities
2. Enabling the creation of custom content structures
3. Separating field storage from entity types for flexibility
4. Supporting a wide range of data types through field type plugins
5. Offering customizable display and form widgets through plugins
6. Implementing a sophisticated storage system for field data
7. Facilitating content translation at the field level
8. Creating a consistent API for accessing and manipulating field data

By providing this infrastructure, the Field module empowers site builders to create complex content models while giving developers a consistent way to interact with entity data regardless of the underlying structure.

Hierarchical Breakdown

1. Field Types Architecture

• FieldType Plugin: Base plugin for defining field types
• FieldItemInterface: Interface for field items
• FieldItemList: Container for multiple field items
• TypedData Integration: Data typing system for fields
• Field Settings: Type-specific options
• Storage Settings: Database-specific options
• Default Value: Configuration for initial values
• Field Constraints: Validation rules for field values

2. Field Storage System

• FieldStorageDefinition: Definition of how a field is stored
• FieldStorageConfig Entity: Config entity for field storage
• Schema API Integration: Database schema definition
• SQL Storage: Primary storage engine for fields
• Cardinality: Support for single or multiple values
• Field Storage API: CRUD operations for field data
• Shared Fields: Reuse across entity types
• Storage Optimization: Efficient data handling

3. Field Instance System

• FieldConfig Entity: Config entity for field instances
• Field Settings: Instance-specific configuration
• Bundle Attachment: Connecting fields to entity bundles
• Field Instance API: Managing field instances
• Required Status: Required/optional configuration
• Field Labels: Display labels
• Help Text: Descriptive assistance
• Default Values: Bundle-specific defaults

4. Field Widgets and Formatters

• WidgetPluginInterface: Interface for form input widgets
• WidgetBase: Base class for field widgets
• FormatterPluginInterface: Interface for display formatters
• FormatterBase: Base class for field formatters
• Display Modes: Context-specific display settings
• Form Modes: Context-specific form settings
• Entity View Display: Configuration for display
• Entity Form Display: Configuration for forms

5. Field API Components

• Field Attachers: Add field data to entities
• Field Renderers: Convert field data to output
• Field Translators: Handle multilingual fields
• Field Validators: Validate field values
• Field Access Control: Field-level permissions
• Field Purging: Cleanup of deleted fields
• Field Hooks: Alteration points in field lifecycle
• Field UI Integration: Administrative interface

Concrete Examples

1. Defining a Custom Field Type

namespace Drupal\my_module\Plugin\Field\FieldType;

use Drupal\Core\Field\FieldItemBase;
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\TypedData\DataDefinition;

/**
 * Plugin implementation of the 'my_custom_field' field type.
 *
 * @FieldType(
 *   id = "my_custom_field",
 *   label = @Translation("My Custom Field"),
 *   description = @Translation("Stores custom data with multiple properties."),
 *   category = @Translation("Custom"),
 *   default_widget = "my_custom_widget",
 *   default_formatter = "my_custom_formatter"
 * )
 */
class MyCustomField extends FieldItemBase {

  /**
   * {@inheritdoc}
   */
  public static function schema(FieldStorageDefinitionInterface $field_definition) {
    return [
      'columns' => [
        'value' => [
          'type' => 'varchar',
          'length' => 255,
          'not null' => FALSE,
        ],
        'subvalue' => [
          'type' => 'int',
          'unsigned' => TRUE,
          'not null' => FALSE,
        ],
      ],
      'indexes' => [
        'value' => ['value'],
        'subvalue' => ['subvalue'],
      ],
    ];
  }

  /**
   * {@inheritdoc}
   */
  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['value'] = DataDefinition::create('string')
      ->setLabel(t('Main value'))
      ->setRequired(TRUE);

    $properties['subvalue'] = DataDefinition::create('integer')
      ->setLabel(t('Secondary value'))
      ->setRequired(FALSE);

    return $properties;
  }

  /**
   * {@inheritdoc}
   */
  public function isEmpty() {
    $value = $this->get('value')->getValue();
    return $value === NULL || $value === '';
  }

  /**
   * {@inheritdoc}
   */
  public static function defaultStorageSettings() {
    return [
      'max_length' => 255,
    ] + parent::defaultStorageSettings();
  }

  /**
   * {@inheritdoc}
   */
  public static function defaultFieldSettings() {
    return [
      'default_subvalue' => 0,
    ] + parent::defaultFieldSettings();
  }

  /**
   * {@inheritdoc}
   */
  public function storageSettingsForm(array &$form, FormStateInterface $form_state, $has_data) {
    $elements = parent::storageSettingsForm($form, $form_state, $has_data);
    
    $elements['max_length'] = [
      '#type' => 'number',
      '#title' => t('Maximum length'),
      '#default_value' => $this->getSetting('max_length'),
      '#required' => TRUE,
      '#min' => 1,
      '#disabled' => $has_data,
    ];
    
    return $elements;
  }

  /**
   * {@inheritdoc}
   */
  public function fieldSettingsForm(array $form, FormStateInterface $form_state) {
    $element = parent::fieldSettingsForm($form, $form_state);
    
    $element['default_subvalue'] = [
      '#type' => 'number',
      '#title' => t('Default subvalue'),
      '#default_value' => $this->getSetting('default_subvalue'),
      '#description' => t('Default subvalue to use when creating new content.'),
    ];
    
    return $element;
  }
}

2. Implementing a Field Widget

namespace Drupal\my_module\Plugin\Field\FieldWidget;

use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Field\WidgetBase;
use Drupal\Core\Form\FormStateInterface;

/**
 * Plugin implementation of the 'my_custom_widget' widget.
 *
 * @FieldWidget(
 *   id = "my_custom_widget",
 *   label = @Translation("My custom widget"),
 *   field_types = {
 *     "my_custom_field"
 *   }
 * )
 */
class MyCustomWidget extends WidgetBase {

  /**
   * {@inheritdoc}
   */
  public static function defaultSettings() {
    return [
      'placeholder' => '',
      'show_subvalue' => TRUE,
    ] + parent::defaultSettings();
  }

  /**
   * {@inheritdoc}
   */
  public function settingsForm(array $form, FormStateInterface $form_state) {
    $elements = parent::settingsForm($form, $form_state);
    
    $elements['placeholder'] = [
      '#type' => 'textfield',
      '#title' => t('Placeholder'),
      '#default_value' => $this->getSetting('placeholder'),
      '#description' => t('Text that will be shown inside the field until a value is entered.'),
    ];
    
    $elements['show_subvalue'] = [
      '#type' => 'checkbox',
      '#title' => t('Show subvalue field'),
      '#default_value' => $this->getSetting('show_subvalue'),
    ];
    
    return $elements;
  }

  /**
   * {@inheritdoc}
   */
  public function settingsSummary() {
    $summary = parent::settingsSummary();
    
    if (!empty($this->getSetting('placeholder'))) {
      $summary[] = t('Placeholder: @placeholder', ['@placeholder' => $this->getSetting('placeholder')]);
    }
    
    $summary[] = $this->getSetting('show_subvalue') ? t('Show subvalue: Yes') : t('Show subvalue: No');
    
    return $summary;
  }

  /**
   * {@inheritdoc}
   */
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {
    $item = $items[$delta];
    
    $element['value'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Value'),
      '#default_value' => isset($item->value) ? $item->value : NULL,
      '#placeholder' => $this->getSetting('placeholder'),
      '#maxlength' => 255,
      '#required' => $element['#required'],
    ];
    
    if ($this->getSetting('show_subvalue')) {
      $element['subvalue'] = [
        '#type' => 'number',
        '#title' => $this->t('Subvalue'),
        '#default_value' => isset($item->subvalue) ? $item->subvalue : $this->getFieldSetting('default_subvalue'),
        '#min' => 0,
      ];
    }
    else {
      // Hidden but still included in the form
      $element['subvalue'] = [
        '#type' => 'hidden',
        '#default_value' => isset($item->subvalue) ? $item->subvalue : $this->getFieldSetting('default_subvalue'),
      ];
    }
    
    return $element;
  }
}

3. Creating a Field Formatter

namespace Drupal\my_module\Plugin\Field\FieldFormatter;

use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Field\FormatterBase;
use Drupal\Core\Form\FormStateInterface;

/**
 * Plugin implementation of the 'my_custom_formatter' formatter.
 *
 * @FieldFormatter(
 *   id = "my_custom_formatter",
 *   label = @Translation("My custom formatter"),
 *   field_types = {
 *     "my_custom_field"
 *   }
 * )
 */
class MyCustomFormatter extends FormatterBase {

  /**
   * {@inheritdoc}
   */
  public static function defaultSettings() {
    return [
      'display_format' => 'default',
      'include_subvalue' => TRUE,
    ] + parent::defaultSettings();
  }

  /**
   * {@inheritdoc}
   */
  public function settingsForm(array $form, FormStateInterface $form_state) {
    $elements = parent::settingsForm($form, $form_state);
    
    $elements['display_format'] = [
      '#type' => 'select',
      '#title' => t('Display format'),
      '#options' => [
        'default' => t('Default'),
        'bold' => t('Bold'),
        'italic' => t('Italic'),
      ],
      '#default_value' => $this->getSetting('display_format'),
    ];
    
    $elements['include_subvalue'] = [
      '#type' => 'checkbox',
      '#title' => t('Include subvalue in display'),
      '#default_value' => $this->getSetting('include_subvalue'),
    ];
    
    return $elements;
  }

  /**
   * {@inheritdoc}
   */
  public function settingsSummary() {
    $summary = parent::settingsSummary();
    
    $summary[] = t('Format: @format', ['@format' => $this->getSetting('display_format')]);
    $summary[] = $this->getSetting('include_subvalue') ? t('Show subvalue: Yes') : t('Show subvalue: No');
    
    return $summary;
  }

  /**
   * {@inheritdoc}
   */
  public function viewElements(FieldItemListInterface $items, $langcode) {
    $elements = [];
    $format = $this->getSetting('display_format');
    $include_subvalue = $this->getSetting('include_subvalue');
    
    foreach ($items as $delta => $item) {
      $markup = $item->value;
      
      switch ($format) {
        case 'bold':
          $markup = '<strong>' . $markup . '</strong>';
          break;
        
        case 'italic':
          $markup = '<em>' . $markup . '</em>';
          break;
      }
      
      if ($include_subvalue && !empty($item->subvalue)) {
        $markup .= ' (' . $item->subvalue . ')';
      }
      
      $elements[$delta] = [
        '#markup' => $markup,
        '#cache' => [
          'tags' => $items->getEntity()->getCacheTags(),
        ],
      ];
    }
    
    return $elements;
  }
}

4. Programmatically Creating Fields

use Drupal\field\Entity\FieldStorageConfig;
use Drupal\field\Entity\FieldConfig;
use Drupal\Core\Entity\Entity\EntityFormDisplay;
use Drupal\Core\Entity\Entity\EntityViewDisplay;

/**
 * Creates a custom field on the article node type.
 */
function my_module_create_custom_field() {
  // Create field storage (shared across entity types).
  $field_storage = FieldStorageConfig::create([
    'field_name' => 'field_custom_data',
    'entity_type' => 'node',
    'type' => 'my_custom_field',
    'cardinality' => 3,
    'locked' => FALSE,
    'settings' => [
      'max_length' => 255,
    ],
    'translatable' => TRUE,
  ]);
  $field_storage->save();
  
  // Create field instance on article bundle.
  $field = FieldConfig::create([
    'field_storage' => $field_storage,
    'bundle' => 'article',
    'label' => 'Custom Data',
    'description' => 'Stores custom data for this article.',
    'required' => FALSE,
    'settings' => [
      'default_subvalue' => 42,
    ],
    'translatable' => TRUE,
  ]);
  $field->save();
  
  // Configure form display.
  EntityFormDisplay::load('node.article.default')
    ->setComponent('field_custom_data', [
      'type' => 'my_custom_widget',
      'weight' => 10,
      'settings' => [
        'placeholder' => 'Enter custom data',
        'show_subvalue' => TRUE,
      ],
    ])
    ->save();
  
  // Configure view display.
  EntityViewDisplay::load('node.article.default')
    ->setComponent('field_custom_data', [
      'type' => 'my_custom_formatter',
      'weight' => 10,
      'settings' => [
        'display_format' => 'bold',
        'include_subvalue' => TRUE,
      ],
      'label' => 'above',
    ])
    ->save();
}

5. Using Field API Programmatically

/**
 * Examples of working with field data programmatically.
 */
function my_module_field_examples($node) {
  // Setting field values.
  $node->field_custom_data = [
    [
      'value' => 'First value',
      'subvalue' => 10,
    ],
    [
      'value' => 'Second value',
      'subvalue' => 20,
    ],
  ];
  
  // Adding a value to a multi-value field.
  $node->field_custom_data[] = [
    'value' => 'Third value',
    'subvalue' => 30,
  ];
  
  // Accessing field values.
  $first_value = $node->field_custom_data[0]->value;
  $first_subvalue = $node->field_custom_data[0]->subvalue;
  
  // Checking if a field has values.
  if (!$node->field_custom_data->isEmpty()) {
    // Do something with the field data.
  }
  
  // Iterating through all values.
  foreach ($node->field_custom_data as $item) {
    $value = $item->value;
    $subvalue = $item->subvalue;
    // Process each value.
  }
  
  // Getting the number of values.
  $count = $node->field_custom_data->count();
  
  // Getting field as a render array.
  $view_builder = \Drupal::entityTypeManager()->getViewBuilder('node');
  $field_render_array = $view_builder->viewField($node->field_custom_data, 'default');
  
  // Getting the field definition.
  $field_definition = $node->getFieldDefinition('field_custom_data');
  $field_type = $field_definition->getType();
  $is_required = $field_definition->isRequired();
  $field_label = $field_definition->getLabel();
  
  // Save changes to the node.
  $node->save();
}

Relationships to Other Components

• Entity API: Fields are attached to entities
• TypedData API: Field values use typed data for validation
• Plugin API: Field types, widgets, and formatters are plugins
• Form API: Field widgets integrate with forms
• Cache API: Field formatters implement caching
• Configuration System: Field definitions are config entities
• Schema API: Field types define storage schemas
• Bundle System: Fields connect to entity bundles
• Entity Query API: Fields are available for queries
• Display Mode API: Field display is configurable by mode
• Translation System: Field content can be translated
• Access Control: Field-level access control
• Theme System: Field output is themeable
• Views Module: Fields are integrated with views

Common Patterns and Edge Cases

Common Patterns

• Custom Field Types: Creating specialized data structures
• Computed Fields: Generating values based on other fields
• Field Preprocessing: Altering field values before display
• Field Validation: Custom validation for field data
• Conditional Fields: Showing/hiding fields based on conditions
• Widget Settings: Configurable form elements
• Formatter Variations: Different ways to display the same data
• Field Groups: Organizing related fields together
• Entity Reference Fields: Creating relationships between entities
• Reusing Field Storage: Sharing field definitions across bundles

Edge Cases

• Empty Field Handling: Determining when a field is empty
• Delta Manipulation: Working with specific items in multi-value fields
• Mass Field Updates: Performance concerns with updating many fields
• Field Data Migration: Moving field data between field types
• Revision Handling: Field history in entity revisions
• Multilingual Complexities: Translation at field and entity level
• Field Collection Patterns: Grouping fields into cohesive sets
• Field Cardinality Changes: Handling cardinality changes on existing fields
• Orphaned Field Data: Cleaning up after field deletion
• Cross-Entity Field Use: Same field used on different entity types

Concept Map

                           ┌─────────────────┐
                           │   Field Module  │
                           └────────┬────────┘
                                    │
         ┌───────────────────┬──────┼──────┬───────────────────────┐
         │                   │      │      │                       │
┌────────▼────────┐  ┌───────▼────┐ │ ┌────▼───────┐   ┌───────────▼────────┐
│  Field Types    │  │Field Storage│ │ │Field UI    │   │  Field Display     │
└────────┬────────┘  └───────┬────┘ │ └────┬───────┘   └───────────┬────────┘
         │                   │      │      │                       │
┌────────▼────────┐  ┌───────▼────┐ │ ┌────▼───────┐   ┌───────────▼────────┐
│FieldItemInterface│  │FieldStorage│ │ │FieldConfig │   │  Formatters       │
└────────┬────────┘  │Config Entity│ │ │Entity      │   └───────────────────┘
         │           └─────────────┘ │ └────────────┘
┌────────▼────────┐                  │               ┌────────────────────┐
│FieldItemBase    │                  │               │  Widgets           │
└────────┬────────┘                  │               └────────────────────┘
         │                           │
┌────────▼────────┐                  │                ┌───────────────────┐
│FieldItemList    │                  │                │Display/Form Modes │
└─────────────────┘                  │                └───────────────────┘
                                     │
                        ┌────────────▼─────────┐
                        │Entity/Bundle Field    │
                        │Attachment            │
                        └──────────────────────┘

Quick Reference

• Primary Interfaces:

  • FieldItemInterface: Base interface for field items
  • FieldDefinitionInterface: For field definitions
  • FieldStorageDefinitionInterface: For storage definitions
  • FieldWidgetInterface: For field widgets
  • FieldFormatterInterface: For field formatters

• Primary Classes:

  • FieldItemBase: Base class for field item implementations
  • FieldStorageConfig: Config entity for field storage
  • FieldConfig: Config entity for field instances
  • WidgetBase: Base class for field widgets
  • FormatterBase: Base class for field formatters

• Field Storage Config Keys:

  • field_name: Machine name for the field
  • entity_type: Type of entity the field can be attached to
  • type: Field type plugin ID
  • cardinality: Number of values (use -1 for unlimited)
  • translatable: Whether the field is translatable
  • settings: Field type-specific storage settings

• Field Config Keys:

  • field_storage: Reference to field storage
  • bundle: Entity bundle the field is attached to
  • label: Human-readable field label
  • required: Whether the field is required
  • default_value: Default value for new entities
  • settings: Field instance-specific settings

• Common Field Types:

  • string: Single-line text field
  • text: Multi-line formatted text
  • boolean: True/false value
  • integer: Whole number
  • decimal: Decimal number
  • email: Email address
  • telephone: Phone number
  • datetime: Date and time
  • entity_reference: Reference to another entity

AI Recommendation

When working with Drupal's Field API, consider these approaches:

1. Use Appropriate Field Types: Choose the right field type for your data model, or create a custom field type if necessary.

// Instead of storing multiple related values in separate fields:
$fields['field_address_street'] = BaseFieldDefinition::create('string');
$fields['field_address_city'] = BaseFieldDefinition::create('string');
$fields['field_address_postal'] = BaseFieldDefinition::create('string');

// Create a comprehensive address field type:
/**
 * @FieldType(
 *   id = "address",
 *   label = @Translation("Address"),
 *   description = @Translation("Stores address information."),
 *   category = @Translation("Custom"),
 *   default_widget = "address_default",
 *   default_formatter = "address_default"
 * )
 */
class AddressItem extends FieldItemBase {
  // Implementation with street, city, postal properties
}

2. Leverage Field Storage/Instance Separation: Reuse field storage across bundles when appropriate.

// Create once, reuse across bundles
$field_storage = FieldStorageConfig::create([
  'field_name' => 'field_tags',
  'entity_type' => 'node',
  'type' => 'entity_reference',
  'cardinality' => -1,
  'settings' => [
    'target_type' => 'taxonomy_term',
  ],
]);
$field_storage->save();

// Attach to multiple bundles with different settings
$bundles = ['article', 'news', 'blog'];
foreach ($bundles as $bundle) {
  $field = FieldConfig::create([
    'field_storage' => $field_storage,
    'bundle' => $bundle,
    'label' => t('Tags'),
    'settings' => [
      'handler' => 'default:taxonomy_term',
      'handler_settings' => [
        'target_bundles' => ['tags' => 'tags'],
      ],
    ],
  ]);
  $field->save();
}

3. Implement Field Access Control: Use field-level permissions when necessary.

/**
 * Implements hook_entity_field_access().
 */
function mymodule_entity_field_access($operation, \Drupal\Core\Field\FieldDefinitionInterface $field_definition, \Drupal\Core\Session\AccountInterface $account, \Drupal\Core\Field\FieldItemListInterface $items = NULL) {
  // Restrict access to a sensitive field
  if ($field_definition->getName() === 'field_confidential_info') {
    // Only allow users with specific permission
    return AccessResult::allowedIfHasPermission($account, 'access confidential information')
      ->cachePerPermissions()
      ->addCacheableDependency($items ? $items->getEntity() : NULL);
  }
  
  return AccessResult::neutral();
}

4. Use Computed Fields: Create fields that calculate values based on other fields.

/**
 * A computed field that derives its value from other fields.
 */
class ComputedSummaryItem extends FieldItemBase {

  /**
   * {@inheritdoc}
   */
  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['value'] = DataDefinition::create('string')
      ->setLabel(t('Computed summary'))
      ->setComputed(TRUE)
      ->setClass('\Drupal\mymodule\ComputedSummaryComputed');
      
    return $properties;
  }
  
  /**
   * {@inheritdoc}
   */
  public function isEmpty() {
    // This is never empty as it's computed
    return FALSE;
  }
}

/**
 * Computes the summary value.
 */
class ComputedSummaryComputed extends ComputedItemPropertyBase {
  public function getValue() {
    $entity = $this->getParent()->getParent()->getEntity();
    
    // Derive value from other fields
    $title = $entity->getTitle();
    $body = $entity->get('body')->value;
    
    return substr($title . ': ' . strip_tags($body), 0, 100) . '...';
  }
}

5. Optimize Field Handling in Batch Operations: Be mindful of performance with large field operations.

// Inefficient: Loading and saving many entities with field updates
foreach ($large_dataset as $item) {
  $node = Node::load($item['id']);
  $node->field_value = $item['value'];
  $node->save();
}

// More efficient: Use entity storage directly for batch updates
$node_storage = \Drupal::entityTypeManager()->getStorage('node');
$nids = array_map(function ($item) {
  return $item['id'];
}, $large_dataset);

$nodes = $node_storage->loadMultiple($nids);
foreach ($large_dataset as $item) {
  $nid = $item['id'];
  if (isset($nodes[$nid])) {
    $nodes[$nid]->field_value = $item['value'];
  }
}

// Save all at once
$node_storage->saveMultiple($nodes);

6. Implement Custom Validation: Add field-specific validation logic.

/**
 * Implements hook_field_widget_form_alter().
 */
function mymodule_field_widget_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
  // Add custom validation to a specific field widget
  if ($context['items']->getFieldDefinition()->getName() === 'field_custom_code') {
    $element['#element_validate'][] = 'mymodule_validate_custom_code';
  }
}

/**
 * Validates the custom code field.
 */
function mymodule_validate_custom_code($element, \Drupal\Core\Form\FormStateInterface $form_state, $form) {
  $value = $element['value']['#value'];
  
  // Perform specialized validation
  if (!preg_match('/^[A-Z]{3}-\d{4}$/', $value)) {
    $form_state->setError($element, t('The custom code must be in the format AAA-1234.'));
  }
}

7. Create Consistent Field Experiences: Design field types, widgets, and formatters as a cohesive system.

// Field type
class LocationItem extends FieldItemBase {
  // Properties, schema, etc.
}

// Widget designed specifically for this field type
class LocationWidget extends WidgetBase {
  // Form elements with map integration
}

// Formatter designed to display location data
class LocationFormatter extends FormatterBase {
  // Display with map rendering
}

The Field module is one of Drupal's most fundamental systems, enabling flexible content modeling while maintaining structured data. Understanding its architecture allows you to create sophisticated data structures with appropriate editing interfaces and display formats, making content management more intuitive and powerful.

form-entity-integration.md

Drupal Form-Entity Integration

Tags: Integration, Form, Entity, UI, Data Entry

High-Level Overview

Form-Entity Integration is the comprehensive system that connects Drupal's Form API with the Entity API to provide standardized interfaces for creating, editing, and processing entity data. This integration creates a cohesive workflow for entity manipulation through web forms, handling form generation, validation, submission, and error handling while maintaining entity data integrity. The system leverages entity definitions, field widgets, and form display configurations to generate appropriate form elements automatically, while allowing for extensive customization through form alter hooks and custom form classes.

Purpose in Drupal Architecture

The Form-Entity integration serves as a critical bridge in Drupal's architecture by:

1. Providing standardized UIs for entity creation and manipulation
2. Automating form generation based on entity field definitions
3. Ensuring consistent validation of entity data
4. Supporting complex multi-step form workflows
5. Enabling form customization while maintaining data integrity
6. Isolating UI concerns from data storage concerns
7. Handling entity submission and error management
8. Creating context-specific forms through Form Display modes
9. Supporting translation and multilingual content creation
10. Facilitating programmatic entity form operations

This integration allows site builders and developers to work with entities through intuitive interfaces while ensuring that the underlying data structures maintain their integrity, creating a balance between flexibility in presentation and consistency in data handling.

Hierarchical Breakdown

1. Form Generation Components

• EntityForm: Base class for entity forms
• ContentEntityForm: Forms for content entities
• ConfigEntityForm: Forms for configuration entities
• EntityFormDisplay: Configuration for form appearance
• WidgetPluginManager: Manages field widget plugins
• FieldWidgets: UI components for editing fields
• FormState: Stores form processing state
• FormBuilder: Constructs form arrays

2. Entity Form Types

• EntityAddForm: Creating new entities
• EntityEditForm: Modifying existing entities
• EntityDeleteForm: Removing entities
• EntityForm: Base form operations
• EntityFormInterface: Contract for entity forms
• Form Modes: Context-specific form configurations
• Form Controllers: Route handlers for forms
• Form Operations: Standard entity form operations

3. Form Processing Workflow

• Form Building: Generating the form structure
• Form Validation: Field and entity validation
• Form Submission: Processing submitted data
• Form Altering: Customizing form appearance
• Form Errors: Handling validation failures
• Field Widgets: Generating field inputs
• Field Widget Validation: Field-specific validation
• Entity Validation: Entity-level constraints

4. Form Display Configuration

• EntityFormDisplay Entity: Stores form configuration
• FormDisplayOptions: Widget settings and visibility
• Form Modes: Context-specific form configurations
• Field Widget Settings: Field-specific form options
• Field Weight: Controls field order
• Field Groups: Organizes related fields
• Field Visibility: Controls field display status
• Form Display Context: Entity bundle and mode

Concrete Examples

1. Creating a Basic Entity Form

namespace Drupal\my_module\Form;

use Drupal\Core\Entity\ContentEntityForm;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Language\LanguageInterface;

/**
 * Form controller for the product entity edit forms.
 */
class ProductForm extends ContentEntityForm {

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
    // Get the entity this form is operating on.
    $product = $this->entity;
    
    // Build the form through the parent.
    $form = parent::buildForm($form, $form_state);
    
    // Add language selection if entity is translatable.
    if ($this->moduleHandler->moduleExists('language')) {
      $form['langcode'] = [
        '#title' => $this->t('Language'),
        '#type' => 'language_select',
        '#default_value' => $product->language()->getId(),
        '#languages' => LanguageInterface::STATE_ALL,
        '#weight' => 100,
      ];
    }
    
    // Add custom elements not derived from fields.
    $form['additional_info'] = [
      '#type' => 'details',
      '#title' => $this->t('Additional information'),
      '#open' => TRUE,
      '#weight' => 90,
    ];
    
    $form['additional_info']['notes'] = [
      '#type' => 'textarea',
      '#title' => $this->t('Administrative notes'),
      '#description' => $this->t('Notes for administrators. Not displayed publicly.'),
      '#default_value' => $product->get('additional_info')->notes ?? '',
    ];
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function validateForm(array &$form, FormStateInterface $form_state) {
    // Run default entity validation.
    parent::validateForm($form, $form_state);
    
    // Add custom validation.
    $price = $form_state->getValue(['price', 0, 'value']);
    if (!empty($price) && $price < 0) {
      $form_state->setErrorByName('price', $this->t('Price cannot be negative.'));
    }
  }

  /**
   * {@inheritdoc}
   */
  public function save(array $form, FormStateInterface $form_state) {
    // Get the entity this form is operating on.
    $product = $this->entity;
    
    // Store custom form values not directly mapped to fields.
    $product->set('additional_info', [
      'notes' => $form_state->getValue(['additional_info', 'notes']),
    ]);
    
    // Save the entity.
    $status = parent::save($form, $form_state);
    
    // Set a message based on the save result.
    if ($status == SAVED_NEW) {
      $this->messenger()->addMessage($this->t('Created new product %label.', [
        '%label' => $product->label(),
      ]));
    }
    else {
      $this->messenger()->addMessage($this->t('Updated product %label.', [
        '%label' => $product->label(),
      ]));
    }
    
    // Redirect to the entity view page.
    $form_state->setRedirect('entity.product.canonical', [
      'product' => $product->id(),
    ]);
    
    return $status;
  }
}

2. Configuring Entity Form Display

use Drupal\Core\Entity\Entity\EntityFormDisplay;

/**
 * Configures how entity fields appear in forms.
 */
function my_module_configure_product_form_display() {
  // Load the form display configuration entity.
  $form_display = EntityFormDisplay::load('product.physical.default');
  
  // If it doesn't exist, create a new one.
  if (!$form_display) {
    $form_display = EntityFormDisplay::create([
      'targetEntityType' => 'product',
      'bundle' => 'physical',
      'mode' => 'default',
      'status' => TRUE,
    ]);
  }
  
  // Configure the widget for the title field.
  $form_display->setComponent('title', [
    'type' => 'string_textfield',
    'weight' => -10,
    'settings' => [
      'size' => 60,
      'placeholder' => 'Enter product title',
    ],
    'third_party_settings' => [],
  ]);
  
  // Configure the widget for the price field.
  $form_display->setComponent('price', [
    'type' => 'number',
    'weight' => -9,
    'settings' => [
      'placeholder' => 'Enter price',
    ],
    'third_party_settings' => [],
  ]);
  
  // Configure the widget for the image field.
  $form_display->setComponent('field_image', [
    'type' => 'image_image',
    'weight' => -8,
    'settings' => [
      'progress_indicator' => 'throbber',
      'preview_image_style' => 'thumbnail',
    ],
    'third_party_settings' => [],
  ]);
  
  // Hide the created field in the form.
  $form_display->removeComponent('created');
  
  // Save the form display configuration.
  $form_display->save();
  
  // Create an alternate form mode for "quick edit".
  $quick_edit_form_display = EntityFormDisplay::create([
    'targetEntityType' => 'product',
    'bundle' => 'physical',
    'mode' => 'quick_edit',
    'status' => TRUE,
  ]);
  
  // Only show essential fields in the quick edit form.
  $quick_edit_form_display->setComponent('title', [
    'type' => 'string_textfield',
    'weight' => -10,
  ]);
  
  $quick_edit_form_display->setComponent('price', [
    'type' => 'number',
    'weight' => -9,
  ]);
  
  // Save the quick edit form display configuration.
  $quick_edit_form_display->save();
}

3. Altering Entity Forms

/**
 * Implements hook_form_alter().
 */
function my_module_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
  // Target a specific entity form.
  if ($form_id === 'node_article_edit_form' || $form_id === 'node_article_form') {
    // Add a custom submission handler.
    $form['actions']['submit']['#submit'][] = 'my_module_article_form_submit';
    
    // Add a custom validation handler.
    array_unshift($form['#validate'], 'my_module_article_form_validate');
    
    // Modify a field widget.
    if (isset($form['field_tags'])) {
      $form['field_tags']['widget']['#description'] = t('Enter comma-separated tags. Popular tags: photography, technology, travel.');
      
      // Add an ajax callback to a field.
      $form['field_category']['widget']['#ajax'] = [
        'callback' => 'my_module_category_ajax_callback',
        'wrapper' => 'dynamic-content-wrapper',
        'event' => 'change',
      ];
      
      // Add a container for ajax-updated content.
      $form['dynamic_content'] = [
        '#type' => 'container',
        '#attributes' => ['id' => 'dynamic-content-wrapper'],
      ];
    }
    
    // Add a custom submit button.
    $form['actions']['preview'] = [
      '#type' => 'submit',
      '#value' => t('Preview'),
      '#weight' => 20,
      '#submit' => ['::submitForm', 'my_module_article_preview_submit'],
      '#access' => \Drupal::currentUser()->hasPermission('use article preview'),
    ];
  }
}

/**
 * Custom validation handler for article forms.
 */
function my_module_article_form_validate(&$form, \Drupal\Core\Form\FormStateInterface $form_state) {
  // Get the entity being edited/created.
  /** @var \Drupal\node\NodeInterface $node */
  $node = $form_state->getFormObject()->getEntity();
  
  // Implement custom validation logic.
  if ($node->bundle() === 'article') {
    $title = $form_state->getValue('title')[0]['value'];
    $body = $form_state->getValue('body')[0]['value'] ?? '';
    
    // Title shouldn't be too short.
    if (strlen($title) < 10) {
      $form_state->setErrorByName('title', t('Article title must be at least 10 characters long.'));
    }
    
    // Body shouldn't be too short if title is short.
    if (strlen($title) < 20 && strlen($body) < 100) {
      $form_state->setErrorByName('body', t('Please provide a longer body for articles with short titles.'));
    }
  }
}

/**
 * Custom submit handler for article forms.
 */
function my_module_article_form_submit(&$form, \Drupal\Core\Form\FormStateInterface $form_state) {
  // Get the entity that was just saved.
  /** @var \Drupal\node\NodeInterface $node */
  $node = $form_state->getFormObject()->getEntity();
  
  // Perform additional actions after saving.
  if ($node->isNew()) {
    // New article was created.
    \Drupal::logger('my_module')->notice('New article @title created by @user', [
      '@title' => $node->getTitle(),
      '@user' => \Drupal::currentUser()->getAccountName(),
    ]);
    
    // Notify administrators.
    if ($node->field_notify_admin->value) {
      my_module_notify_administrators($node);
    }
  }
}

/**
 * Ajax callback for category field.
 */
function my_module_category_ajax_callback(array &$form, \Drupal\Core\Form\FormStateInterface $form_state) {
  $category_value = $form_state->getValue('field_category')[0]['target_id'];
  
  // Generate dynamic content based on selected category.
  $content = [];
  if ($category_value) {
    // Load the category term.
    $term = \Drupal\taxonomy\Entity\Term::load($category_value);
    if ($term) {
      $content = [
        '#markup' => t('You selected the category: @category', ['@category' => $term->getName()]),
      ];
      
      // Add suggested tags based on category.
      $suggested_tags = my_module_get_suggested_tags_for_category($term);
      if ($suggested_tags) {
        $content['suggested_tags'] = [
          '#type' => 'details',
          '#title' => t('Suggested tags'),
          '#open' => TRUE,
          '#markup' => implode(', ', $suggested_tags),
        ];
      }
    }
  }
  
  $form['dynamic_content']['content'] = $content;
  
  return $form['dynamic_content'];
}

4. Creating a Multi-Step Entity Form

namespace Drupal\my_module\Form;

use Drupal\Core\Entity\ContentEntityForm;
use Drupal\Core\Form\FormStateInterface;

/**
 * Form controller for product creation with multiple steps.
 */
class ProductMultiStepForm extends ContentEntityForm {

  /**
   * {@inheritdoc}
   */
  public function getFormId() {
    return 'product_multistep_form';
  }

  /**
   * {@inheritdoc}
   */
  public function buildForm(array $form, FormStateInterface $form_state) {
    // Get the current step.
    $step = $form_state->get('step') ?: 1;
    $form_state->set('step', $step);
    
    // Add a step indicator.
    $form['step_indicator'] = [
      '#type' => 'markup',
      '#markup' => $this->t('Step @current of 3', ['@current' => $step]),
      '#weight' => -100,
    ];
    
    // Build different form elements based on the current step.
    switch ($step) {
      case 1:
        return $this->buildStepOne($form, $form_state);

      case 2:
        return $this->buildStepTwo($form, $form_state);

      case 3:
        return $this->buildStepThree($form, $form_state);
    }
    
    return $form;
  }

  /**
   * Builds the first step of the form.
   */
  protected function buildStepOne(array $form, FormStateInterface $form_state) {
    $form = parent::buildForm($form, $form_state);
    
    // Show only basic product information fields.
    // Hide other fields by removing them from the form.
    $visible_fields = ['title', 'sku', 'product_type'];
    
    foreach (array_keys($form) as $key) {
      // Keep form system elements and visible fields.
      if ($key[0] !== '#' && !in_array($key, $visible_fields) && $key !== 'actions') {
        $form[$key]['#access'] = FALSE;
      }
    }
    
    // Customize the submit button.
    $form['actions']['submit']['#value'] = $this->t('Next: Product Details');
    $form['actions']['submit']['#submit'] = [[$this, 'submitStepOne']];
    
    // Remove preview and other buttons if they exist.
    unset($form['actions']['preview']);
    unset($form['actions']['delete']);
    
    return $form;
  }

  /**
   * Builds the second step of the form.
   */
  protected function buildStepTwo(array $form, FormStateInterface $form_state) {
    $form = parent::buildForm($form, $form_state);
    
    // Show only product details fields.
    $visible_fields = ['price', 'description', 'field_image'];
    
    foreach (array_keys($form) as $key) {
      // Keep form system elements and visible fields.
      if ($key[0] !== '#' && !in_array($key, $visible_fields) && $key !== 'actions') {
        $form[$key]['#access'] = FALSE;
      }
    }
    
    // Add a back button.
    $form['actions']['back'] = [
      '#type' => 'submit',
      '#value' => $this->t('Back'),
      '#submit' => [[$this, 'backToStepOne']],
      '#limit_validation_errors' => [],
      '#weight' => 10,
    ];
    
    // Customize the submit button.
    $form['actions']['submit']['#value'] = $this->t('Next: Review');
    $form['actions']['submit']['#submit'] = [[$this, 'submitStepTwo']];
    
    return $form;
  }

  /**
   * Builds the third step of the form.
   */
  protected function buildStepThree(array $form, FormStateInterface $form_state) {
    $entity = $this->entity;
    
    // Create a review summary.
    $form['review'] = [
      '#type' => 'fieldset',
      '#title' => $this->t('Review your product'),
      '#weight' => -10,
    ];
    
    $form['review']['summary'] = [
      '#theme' => 'item_list',
      '#items' => [
        $this->t('Title: @value', ['@value' => $entity->label()]),
        $this->t('SKU: @value', ['@value' => $entity->get('sku')->value]),
        $this->t('Price: @value', ['@value' => $entity->get('price')->value]),
        $this->t('Description: @value', ['@value' => strip_tags($entity->get('description')->value)]),
      ],
    ];
    
    // Add a back button.
    $form['actions']['back'] = [
      '#type' => 'submit',
      '#value' => $this->t('Back'),
      '#submit' => [[$this, 'backToStepTwo']],
      '#limit_validation_errors' => [],
      '#weight' => 10,
    ];
    
    // Customize the submit button.
    $form['actions']['submit']['#value'] = $this->t('Save Product');
    $form['actions']['submit']['#submit'] = ['::submitForm', '::save'];
    
    return $form;
  }

  /**
   * Submit handler for step one.
   */
  public function submitStepOne(array &$form, FormStateInterface $form_state) {
    // Store entity values from step one.
    $this->submitForm($form, $form_state);
    
    // Move to step two.
    $form_state->set('step', 2);
    $form_state->setRebuild(TRUE);
  }

  /**
   * Submit handler for step two.
   */
  public function submitStepTwo(array &$form, FormStateInterface $form_state) {
    // Store entity values from step two.
    $this->submitForm($form, $form_state);
    
    // Move to step three.
    $form_state->set('step', 3);
    $form_state->setRebuild(TRUE);
  }

  /**
   * Submit handler to go back to step one.
   */
  public function backToStepOne(array &$form, FormStateInterface $form_state) {
    $form_state->set('step', 1);
    $form_state->setRebuild(TRUE);
  }

  /**
   * Submit handler to go back to step two.
   */
  public function backToStepTwo(array &$form, FormStateInterface $form_state) {
    $form_state->set('step', 2);
    $form_state->setRebuild(TRUE);
  }

  /**
   * {@inheritdoc}
   */
  public function save(array $form, FormStateInterface $form_state) {
    // Save the entity.
    $status = parent::save($form, $form_state);
    
    // Set a message.
    $this->messenger()->addMessage($this->t('Product %label has been created.', [
      '%label' => $this->entity->label(),
    ]));
    
    // Redirect to the entity view page.
    $form_state->setRedirect('entity.product.canonical', [
      'product' => $this->entity->id(),
    ]);
    
    return $status;
  }
}

5. Programmatically Creating and Submitting Entity Forms

/**
 * Programmatically creates an entity using entity forms.
 */
function my_module_create_product_programmatically($title, $sku, $price, $description) {
  // Get the entity type manager service.
  $entity_type_manager = \Drupal::entityTypeManager();
  
  // Create a new product entity.
  $product = $entity_type_manager
    ->getStorage('product')
    ->create([
      'type' => 'physical',
      'title' => $title,
      'sku' => $sku,
    ]);
  
  // Get the entity form object.
  $form_object = $entity_type_manager
    ->getFormObject('product', 'default')
    ->setEntity($product);
  
  // Build the form.
  $form_state = new \Drupal\Core\Form\FormState();
  $form_state->setValues([
    'title' => [['value' => $title]],
    'sku' => [['value' => $sku]],
    'price' => [['value' => $price]],
    'description' => [['value' => $description, 'format' => 'basic_html']],
  ]);
  
  // Call the submit handler.
  \Drupal::formBuilder()->submitForm($form_object, $form_state);
  
  // Check for errors.
  if ($errors = $form_state->getErrors()) {
    // Log errors or throw an exception.
    \Drupal::logger('my_module')->error('Error creating product: @errors', [
      '@errors' => print_r($errors, TRUE),
    ]);
    return FALSE;
  }
  
  // Get the saved entity and return it.
  return $form_object->getEntity();
}

Relationships to Other Components

• Entity API: Forms operate on entity data structures
• Field API: Field widgets display and capture field values
• Plugin API: Field widgets are plugins
• Form API: Builds and processes form elements
• Configuration System: Stores form display settings
• Routing System: Maps URLs to form controllers
• Access Control: Enforces permissions for form operations
• Validation API: Ensures data integrity
• AJAX Framework: Enables dynamic form interactions
• Theme System: Renders form elements
• Translation System: Handles multilingual forms
• State API: Preserves form state during multi-step forms
• Messenger Service: Displays form status messages
• Event System: Triggers form lifecycle events

Common Patterns and Edge Cases

Common Patterns

• Form Altering: Customizing entity forms
• Multi-Step Forms: Breaking complex forms into steps
• Field Widget Configuration: Customizing field inputs
• Form Modes: Context-specific form displays
• Entity Reference Widgets: Selecting related entities
• AJAX Form Updates: Dynamic form modifications
• Form Validation: Custom field validation
• Form Submission Handlers: Post-processing form data
• Field Groups: Organizing form elements
• Conditional Fields: Showing/hiding based on conditions

Edge Cases

• Complex Validation Dependencies: Interrelated field validation
• Multilingual Form Handling: Language-specific validation
• Partial Form Submissions: Saving incomplete data
• Form State Management: Preserving data between steps
• File Upload Handling: Managing temporary vs. permanent files
• Autocomplete Widgets: Performance and security concerns
• Multiple Entity Forms: Forms that create several entities
• Access Control Edge Cases: Complex permission scenarios
• Integration with External Systems: Form callbacks to external APIs
• Handling Large Forms: Performance considerations

Concept Map

                           ┌─────────────────┐
                           │Form-Entity      │
                           │Integration      │
                           └────────┬────────┘
                                    │
        ┌───────────────────┬──────┼───────┬───────────────────┐
        │                   │      │       │                   │
┌───────▼───────┐   ┌───────▼────┐ │ ┌─────▼─────┐   ┌─────────▼─────┐
│Entity Form    │   │Form Display│ │ │Field      │   │Form Processing │
│Classes        │   │Config      │ │ │Widgets    │   │                │
└───────┬───────┘   └───────┬────┘ │ └─────┬─────┘   └─────────┬─────┘
        │                   │      │       │                   │
┌───────▼───────┐   ┌───────▼────┐ │ ┌─────▼─────┐   ┌─────────▼─────┐
│ContentEntityForm│ │EntityFormDisplay││WidgetPlugins│ │FormBuilder    │
└───────┬───────┘   └───────┬────┘ │ └─────┬─────┘   └─────────┬─────┘
        │                   │      │       │                   │
┌───────▼───────┐   ┌───────▼────┐ │ ┌─────▼─────┐   ┌─────────▼─────┐
│ConfigEntityForm │ │Form Modes  │ │ │Widget     │   │FormState      │
└───────────────┘   └────────────┘ │ │Settings   │   └───────────────┘
                                   │ └───────────┘
                         ┌─────────▼────────┐
                         │Form Alter Hooks  │
                         └─────────┬────────┘
                                   │
                   ┌───────────────┼──────────────┐
                   │               │              │
           ┌───────▼───────┐ ┌─────▼─────┐ ┌──────▼───────┐
           │hook_form_alter│ │Validation │ │Submission    │
           └───────────────┘ └───────────┘ └──────────────┘

Quick Reference

• Primary Classes:

  • EntityForm: Base class for entity forms
  • ContentEntityForm: Forms for content entities
  • ConfigEntityForm: Forms for config entities
  • EntityFormDisplay: Form display configuration entity

• Key Form Operations:

  • buildForm(): Generates the form structure
  • validateForm(): Validates submitted data
  • submitForm(): Processes form submission
  • save(): Saves the entity after submission

• Important Hooks:

  • hook_form_alter(): Modify any form
  • hook_form_FORM_ID_alter(): Modify a specific form
  • hook_field_widget_form_alter(): Modify field widgets

• Entity Form IDs:

  • {entity_type_id}_{form_operation}_form
  • {entity_type_id}_{bundle}_{form_operation}_form
  • Examples: node_article_edit_form, user_register_form

• Form Display Methods:

  • getFormDisplay(): Gets the form display entity
  • setComponent(): Configures a field's form widget
  • removeComponent(): Removes a field from the form

AI Recommendation

When working with Form-Entity integration in Drupal, consider these approaches:

1. Use EntityFormDisplay for Configuration: Let Drupal's entity form system handle field rendering and storage.

// Instead of manually creating field form elements:
$form['title'] = [
  '#type' => 'textfield',
  '#title' => t('Title'),
  '#default_value' => $entity->getTitle(),
  // ...
];

// Better: Configure the form display and let Drupal handle it
\Drupal::service('entity_display.repository')
  ->getFormDisplay('product', 'physical', 'default')
  ->setComponent('title', [
    'type' => 'string_textfield',
    'weight' => -10,
    'settings' => [
      'size' => 60,
      'placeholder' => 'Product name',
    ],
  ])
  ->save();

// Then let the form display system do the work
$form = parent::buildForm($form, $form_state);

2. Leverage Form Modes for Context-Specific Forms: Create different form configurations for different contexts.

// Register a new form mode
$form_mode = \Drupal\Core\Entity\Entity\EntityFormMode::create([
  'id' => 'node.quick_edit',
  'label' => t('Quick edit'),
  'targetEntityType' => 'node',
]);
$form_mode->save();

// Configure form display for this mode
\Drupal::service('entity_display.repository')
  ->getFormDisplay('node', 'article', 'quick_edit')
  ->setComponent('title', ['type' => 'string_textfield', 'weight' => -10])
  ->setComponent('body', ['type' => 'text_textarea_with_summary', 'weight' => 0])
  // Omit non-essential fields
  ->removeComponent('field_tags')
  ->removeComponent('field_image')
  ->save();

// Use the form mode in a route
$route = new Route(
  '/node/{node}/quick-edit',
  [
    '_entity_form' => 'node.quick_edit',
    '_title' => 'Quick edit',
  ],
  [
    '_entity_access' => 'node.update',
  ]
);

3. Implement Proper Form Validation: Use entity constraints and form validation together.

/**
 * Form validation with entity constraints.
 */
public function validateForm(array &$form, FormStateInterface $form_state) {
  // First run the default entity validation
  parent::validateForm($form, $form_state);
  
  // Execute form-specific validation
  $entity = $this->buildEntity($form, $form_state);
  
  // Cross-field validation
  if ($entity->hasField('field_start_date') && $entity->hasField('field_end_date')) {
    $start = $entity->get('field_start_date')->value;
    $end = $entity->get('field_end_date')->value;
    
    if (!empty($start) && !empty($end) && $start > $end) {
      $form_state->setErrorByName('field_end_date', 
        $this->t('End date must be after start date.'));
    }
  }
}

4. Design Multi-Step Forms Carefully: Plan state management when breaking forms into steps.

/**
 * Managing form state in multi-step forms.
 */
public function buildForm(array $form, FormStateInterface $form_state) {
  // Get the current step
  $step = $form_state->get('step') ?? 1;
  
  // Build form for the current step
  switch ($step) {
    case 1:
      $form = $this->buildStepOne($form, $form_state);
      break;
    
    case 2:
      // Ensure we have data from step 1
      if (!$form_state->get('step_1_completed')) {
        $form_state->set('step', 1);
        $this->messenger()->addWarning($this->t('Please complete step 1.'));
        return $this->buildStepOne($form, $form_state);
      }
      
      $form = $this->buildStepTwo($form, $form_state);
      break;
  }
  
  return $form;
}

/**
 * Store data between steps.
 */
public function submitStepOne(array &$form, FormStateInterface $form_state) {
  // Get values
  $values = $form_state->getValues();
  
  // Store in temporary storage
  $this->tempStore->set('form_data_step_1', $values);
  
  // Mark step as completed
  $form_state->set('step_1_completed', TRUE);
  
  // Move to next step
  $form_state->set('step', 2);
  $form_state->setRebuild(TRUE);
}

5. Use Form Alter Hooks Strategically: Modify forms without duplicating entity logic.

/**
 * Implements hook_form_FORM_ID_alter() for node_article_form.
 */
function mymodule_form_node_article_form_alter(&$form, FormStateInterface $form_state, $form_id) {
  // Add a custom field group
  if (\Drupal::moduleHandler()->moduleExists('field_group')) {
    $form['advanced_settings'] = [
      '#type' => 'details',
      '#title' => t('Advanced settings'),
      '#group' => 'advanced',
      '#weight' => 99,
      '#optional' => TRUE,
    ];
    
    // Move an existing field to this group
    if (isset($form['field_custom_setting'])) {
      $form['field_custom_setting']['#group'] = 'advanced_settings';
    }
  }
  
  // Add custom validation and submission only if this is a new node
  $node = $form_state->getFormObject()->getEntity();
  if ($node->isNew()) {
    $form['#validate'][] = 'mymodule_article_validate';
    $form['actions']['submit']['#submit'][] = 'mymodule_article_submit';
  }
}

6. Leverage AJAX for Dynamic Forms: Use AJAX callbacks to update form content.

/**
 * AJAX-enabled form implementation.
 */
public function buildForm(array $form, FormStateInterface $form_state) {
  $form = parent::buildForm($form, $form_state);
  
  // Add AJAX callback to a select field
  $form['field_product_type']['widget']['#ajax'] = [
    'callback' => [$this, 'productTypeCallback'],
    'wrapper' => 'dynamic-fields-wrapper',
    'event' => 'change',
    'progress' => [
      'type' => 'throbber',
      'message' => $this->t('Updating form...'),
    ],
  ];
  
  // Wrapper for dynamic content
  $form['dynamic_fields'] = [
    '#type' => 'container',
    '#attributes' => ['id' => 'dynamic-fields-wrapper'],
  ];
  
  // Current product type
  $product_type = $form_state->getValue('field_product_type')[0]['target_id'] ?? NULL;
  if (!$product_type) {
    $product_type = $this->entity->get('field_product_type')->target_id;
  }
  
  // Add different fields based on product type
  if ($product_type == 'digital') {
    $form['dynamic_fields']['download_info'] = [
      '#type' => 'details',
      '#title' => $this->t('Download information'),
      '#open' => TRUE,
      // Digital product fields...
    ];
  }
  elseif ($product_type == 'physical') {
    $form['dynamic_fields']['shipping_info'] = [
      '#type' => 'details',
      '#title' => $this->t('Shipping information'),
      '#open' => TRUE,
      // Physical product fields...
    ];
  }
  
  return $form;
}

/**
 * Ajax callback for product type change.
 */
public function productTypeCallback(array &$form, FormStateInterface $form_state) {
  return $form['dynamic_fields'];
}

7. Design for Progressive Enhancement: Ensure forms work with and without JavaScript.

/**
 * Create forms that work with and without JavaScript.
 */
public function buildForm(array $form, FormStateInterface $form_state) {
  $form = parent::buildForm($form, $form_state);
  
  // Create a container for the enhancement
  $form['enhanced_selection'] = [
    '#type' => 'container',
    '#attributes' => ['class' => ['js-enhanced-selection']],
  ];
  
  // Include both enhanced and fallback versions
  $form['enhanced_selection']['selector'] = [
    '#type' => 'select',
    '#title' => $this->t('Select options'),
    '#options' => $this->getOptions(),
    '#ajax' => [
      'callback' => [$this, 'updateSelectionCallback'],
      'wrapper' => 'selection-result',
    ],
    '#attributes' => ['class' => ['js-enhanced-selector']],
  ];
  
  // Non-JS fallback button
  $form['enhanced_selection']['update'] = [
    '#type' => 'submit',
    '#value' => $this->t('Update'),
    '#submit' => ['::updateSelection'],
    '#attributes' => ['class' => ['js-hide']],
  ];
  
  $form['result'] = [
    '#type' => 'container',
    '#attributes' => ['id' => 'selection-result'],
  ];
  
  // Add JavaScript to enhance the experience
  $form['#attached']['library'][] = 'my_module/form_enhancement';
  
  return $form;
}

The Form-Entity integration is a critical part of Drupal's architecture, providing the interface between users and data. Understanding this integration allows you to create intuitive, user-friendly forms while maintaining data integrity and leveraging Drupal's powerful entity system. By following these patterns, you can build forms that are flexible, accessible, and maintainable.

kernel-bootstrap.md

Drupal Kernel and Bootstrap Process

Tags: Architecture, Core, Bootstrap, Service Container, Request Handling

High-Level Overview

The Drupal Kernel is the central coordination point for Drupal's bootstrap process and request handling. It serves as the bridge between the web server and Drupal's application logic, initializing the system, building the service container, and coordinating the request-response lifecycle.

Purpose in Drupal Architecture

The Drupal Kernel implements the Symfony HttpKernelInterface and adds Drupal-specific functionality. Its primary responsibilities include:

1. Setting up PHP environment variables and handling safety/security settings
2. Initializing the service container with core and module-provided services
3. Loading enabled modules and their dependencies
4. Managing site-specific configuration
5. Handling HTTP requests and returning appropriate responses
6. Supporting the termination of requests and cleanup

By leveraging Symfony's HTTP kernel architecture while extending it with Drupal-specific functionality, the Kernel provides a robust foundation for Drupal's modular architecture.

Hierarchical Breakdown

1. Bootstrap Process Components

• RuntimeDiscovery: Finds the appropriate runtime class
• DrupalRuntime: Symfony Runtime implementation for Drupal
• DrupalKernel: Core implementation of kernel functionality
• Service Container: Dependency injection container with services
• Bootstrap Container: Minimal container for bootstrap services

2. Bootstrap Phases

• Environment Initialization: Sets up PHP settings and error handlers
• Settings Loading: Finds site path and loads settings.php
• Container Initialization: Builds or loads the cached service container
• Module Discovery: Identifies and loads enabled modules
• Service Registration: Processes service providers from core and modules
• Request Processing: Handles the incoming HTTP request

3. Key Kernel Methods

• boot(): Initializes the system
• handle(): Processes an HTTP request
• preHandle(): Performs pre-request processing
• terminate(): Performs cleanup after response is sent
• initializeContainer(): Sets up the service container
• discoverServiceProviders(): Loads service definitions

Concrete Examples

1. Bootstrap Process Flow

// In index.php - the front controller

// 1. Initialize autoloading
require_once 'autoload.php';

// 2. Discover and create the Symfony Runtime
$_ENV['APP_RUNTIME'] ??= DrupalRuntime::class;
$runtime_callable = require 'autoload_runtime.php';

// 3. The runtime callable returns a kernel
return static function (array $context) {
  return new DrupalKernel($context['APP_ENV'], require 'autoload.php');
};

2. DrupalKernel Initialization

// Creating kernel from a request
public static function createFromRequest(Request $request, $class_loader, $environment, $allow_dumping = TRUE, $app_root = NULL) {
  $kernel = new static($environment, $class_loader, $allow_dumping, $app_root);
  static::bootEnvironment($app_root);
  $kernel->initializeSettings($request);
  return $kernel;
}

3. Service Container Building

// Container initialization
protected function compileContainer() {
  // Initialize service providers from core and modules
  $this->initializeServiceProviders();
  $container = $this->getContainerBuilder();
  
  // Set basic parameters
  $container->set('kernel', $this);
  $container->setParameter('container.modules', $this->getModulesParameter());
  
  // Register applications services from YAML files
  $yaml_loader = new YamlFileLoader($container);
  foreach ($this->serviceYamls['app'] as $filename) {
    $yaml_loader->load($filename);
  }
  
  // Register service providers
  foreach ($this->serviceProviders['app'] as $provider) {
    if ($provider instanceof ServiceProviderInterface) {
      $provider->register($container);
    }
  }
  
  // Compile the container
  $container->compile();
  return $container;
}

Relationships to Other Components

• Drupal Static Class: Service locator that provides global access to services in the container
• Module System: Modules register service providers and modify the container
• Configuration System: Provides config values during bootstrap
• Request Processing: HTTP requests flow through the kernel to controllers
• Theme System: Initialized by the kernel during request processing
• Cache System: Used by the kernel to cache the compiled container
• Plugin System: Initialized as services in the container

Common Patterns and Edge Cases

Common Patterns

• Service Registration: Modules provide services through YAML files and service provider classes
• Container Caching: Compiled containers are cached for performance
• Environment-based Variations: Different behavior in prod vs dev environments

Edge Cases

• Installation Mode: Special handling when Drupal is not yet installed
• Container Rebuilding: Careful handling of persisted services during rebuilds
• CLI Requests: Support for command-line requests without HTTP
• Subrequests: Special handling for in-flight requests within a main request
• Container Resetting: Ability to reset without full rebuilding for performance

Concept Map

                                              ┌─────────────────┐
                                              │  PHP Environment│
                                              └────────┬────────┘
                                                      │
┌─────────────────┐                                   │
│   autoloader    │                          ┌────────▼────────┐
└────────┬────────┘                          │  DrupalRuntime  │
         │                                   └────────┬────────┘
         │                                            │
         │                                   ┌────────▼────────┐      ┌─────────────────┐
         ├───────────────────────────────────►  DrupalKernel   ◄──────►  Site Settings  │
         │                                   └────────┬────────┘      └─────────────────┘
         │                                            │
┌────────▼────────┐                          ┌────────▼────────┐      ┌─────────────────┐
│ Module Classes  │                          │Service Container ◄──────►  Service YAML   │
└────────┬────────┘                          └────────┬────────┘      └─────────────────┘
         │                                            │
         ▼                                            ▼
┌─────────────────┐                          ┌─────────────────┐      ┌─────────────────┐
│Service Providers│───────────────────────────► Module Loading  ◄──────►  Module List    │
└─────────────────┘                          └────────┬────────┘      └─────────────────┘
                                                      │
                                             ┌────────▼────────┐
                                             │ Request Handling│
                                             └────────┬────────┘
                                                      │
                                             ┌────────▼────────┐
                                             │    Response     │
                                             └─────────────────┘

Quick Reference

• Primary Class: \Drupal\Core\DrupalKernel
• Interface: \Drupal\Core\DrupalKernelInterface
• Runtime Class: \Drupal\Core\Runtime\DrupalRuntime
• Entry Point: index.php (front controller)
• Service Container: \Drupal\Core\DependencyInjection\ContainerBuilder
• Static Access: \Drupal class provides static service access
• Settings: Located in sites/*/settings.php
• Core Services: Defined in core/core.services.yml

AI Recommendation

When working with Drupal's kernel and bootstrap process, consider these approaches:

1. Prefer Dependency Injection: Instead of calling \Drupal::service(), inject dependencies through constructors in classes.

2. Use Service Tagging: Register services with tags to allow discovery and modification rather than directly referencing other services.

3. For Low-Level Modifications: Use service providers to alter container behavior rather than overriding core classes directly.

4. For Performance Optimization: Focus on container compilation and caching when optimizing bootstrap performance.

5. For Debugging: Use the kernel's container inspection methods to explore the service definitions rather than adding debug code.

6. For Module Development: Consider how your module's services integrate with the bootstrap process, especially if they're needed early.

7. For Event Responses: Use event subscribers to react to kernel events rather than modifying core classes.

The kernel bootstrap process represents the foundation of Drupal's architecture. Understanding it allows you to make better decisions about where to place your custom functionality and how to properly integrate with Drupal's core systems.

node-module.md

Drupal Node Module

Tags: Module, Core, Content, Entity

High-Level Overview

The Node module is Drupal's primary content management system, providing a flexible, field-based architecture for creating, editing, and displaying content. It defines the "node" entity type, which serves as the foundation for most user-facing content in Drupal sites. The Node module includes a complete system for content type creation, content moderation, revisioning, publishing workflows, and access control.

Purpose in Drupal Architecture

The Node module serves as the backbone of Drupal's content management capabilities by:

1. Providing a standardized content entity type with field support
2. Enabling content type (bundle) definition and customization
3. Supporting revisioning for content change management
4. Implementing a granular node access control system
5. Offering publishing workflows with draft and published states
6. Exposing content to the Views module for display and filtering
7. Creating foundation for content-centric features like comments and taxonomy
8. Supporting translation and multilingual content

As the primary content container, nodes connect many of Drupal's subsystems together, from fields and entities to permissions and views, creating a unified content management experience.

Hierarchical Breakdown

1. Node Entity Architecture

• Node Entity: The core content entity implementation
• NodeType Entity: Configuration entity defining content types
• NodeStorage: Database storage implementation for nodes
• NodeAccessControlHandler: Manages node permissions
• NodeViewBuilder: Handles rendering of nodes
• NodeForm: Form controllers for node editing
• NodeListBuilder: Builds admin node listings
• NodeRouteProvider: Provides node-specific routes

2. Content Type System

• NodeType: Configuration entity for content types
• NodeTypeForm: Form for managing content types
• NodeTypeListBuilder: Admin UI for content types
• NodeTypeHandlers: Special handlers for types
• ContentTypeController: Controller for node type operations

3. Node Access System

• Node Grants API: Delegated permissions system
• Node Access Records: Database-level access control
• Node Access Field Plugins: Field-based access
• Node Access Hooks: Hook points for access control
• Node Access Control Handler: Main access controller

4. Node Field System

• Base Fields: Default fields for all nodes (title, status, etc.)
• Field Form Display: Field widgets for node forms
• Field Display: Field formatters for node display
• Bundle Fields: Fields added to specific content types
• Field Layout: Positioning of fields in display

5. Node API Components

• Node Hooks: Hook points for altering node behaviors
• NodeInterface: Methods for node manipulation
• Node Query API: Content query facilities
• Node Template System: Theming for nodes
• NodeTypeInterface: API for node type operations

Concrete Examples

1. Creating a Node Programmatically

use Drupal\node\Entity\Node;

// Create a new node.
$node = Node::create([
  'type' => 'article',
  'title' => 'New Article',
  'body' => [
    'value' => '<p>This is the body text.</p>',
    'format' => 'basic_html',
  ],
  'field_image' => [
    'target_id' => $file_id,
    'alt' => 'Alt text',
    'title' => 'Image title',
  ],
  'uid' => \Drupal::currentUser()->id(),
  'status' => 1,
]);

// Save the node.
$node->save();

2. Loading and Rendering a Node

use Drupal\node\Entity\Node;

// Load a node by ID.
$node = Node::load($node_id);
if ($node) {
  // Get field values.
  $title = $node->getTitle();
  $body = $node->get('body')->value;
  $created = $node->getCreatedTime();
  
  // Check access.
  if ($node->access('view')) {
    // Render using the view builder.
    $view_builder = \Drupal::entityTypeManager()->getViewBuilder('node');
    $build = $view_builder->view($node, 'teaser');
    
    // Return the render array.
    return $build;
  }
}

3. Implementing a Node Access Hook

/**
 * Implements hook_node_access().
 */
function mymodule_node_access(\Drupal\node\NodeInterface $node, $op, \Drupal\Core\Session\AccountInterface $account) {
  // Grant access to 'special' content type for a specific role.
  if ($node->getType() == 'special' && $op == 'view') {
    if ($account->hasRole('special_viewer')) {
      return \Drupal\Core\Access\AccessResult::allowed()
        ->cachePerPermissions()
        ->cachePerUser()
        ->addCacheableDependency($node);
    }
  }
  
  // Let other modules decide for their own conditions.
  return \Drupal\Core\Access\AccessResult::neutral();
}

4. Creating a Custom Node Type

use Drupal\node\Entity\NodeType;

// Create a new content type.
$node_type = NodeType::create([
  'type' => 'custom_content',
  'name' => 'Custom Content',
  'description' => 'A custom content type.',
  'help' => 'Instructions for creating custom content.',
  'new_revision' => TRUE,
  'preview_mode' => 1,
  'display_submitted' => TRUE,
]);

// Save the content type.
$node_type->save();

// Optionally add fields programmatically.
$field_storage = \Drupal\field\Entity\FieldStorageConfig::create([
  'field_name' => 'field_custom',
  'entity_type' => 'node',
  'type' => 'text',
]);
$field_storage->save();

$field = \Drupal\field\Entity\FieldConfig::create([
  'field_storage' => $field_storage,
  'bundle' => 'custom_content',
  'label' => 'Custom Field',
]);
$field->save();

Relationships to Other Components

• Field API: Nodes are fieldable entities that rely on the Field API
• Entity API: Nodes are content entities that extend ContentEntityBase
• Form API: Node forms are built with the Form API
• Views: Nodes are primary data sources for the Views module
• Comment: Comments can be attached to nodes
• Taxonomy: Terms can be referenced from node fields
• Path: URL aliases are often created for nodes
• Menu: Nodes can be added to menus
• Search: Nodes are indexed for search
• Workflow: Content moderation often applies to nodes

Common Patterns and Edge Cases

Common Patterns

• View Modes: Different display configurations for nodes
• Node Templates: Twig templates for display customization
• Node Hooks: Altering node behavior and display
• Node Access: Controlling user access to content
• Node Operations: Standard CRUD operations on nodes
• Node Fields: Extending node data with fields
• Node Reference: Creating relationships between nodes
• Node Revisions: Tracking changes to node content
• Node Query: Finding nodes with EntityQuery

Edge Cases

• Node Access Grants: Complex permission systems
• Node Translations: Content in multiple languages
• Revision Moderation: Workflows with unpublished revisions
• Node Previews: Preview mode with unsaved content
• Node Access By-pass: Handling administrative access
• Node Revisions Without Default: Revision workflow edge cases
• Very Large Node Numbers: Performance with thousands or millions of nodes
• Node-Field Recursion: Self-referential field challenges

Concept Map

                           ┌─────────────────┐
                           │    Node Module  │
                           └─────────┬───────┘
                                     │
        ┌───────────────────┬────────┼───────────┬────────────────────┐
        │                   │        │           │                    │
┌───────▼───────┐   ┌──────▼──────┐ │   ┌───────▼────────┐    ┌──────▼─────────┐
│  Node Entity  │   │ NodeType    │ │   │ Node Access    │    │ Node API Hooks  │
└───────┬───────┘   └──────┬──────┘ │   └───────┬────────┘    └──────┬─────────┘
        │                  │        │           │                    │
┌───────▼───────┐   ┌──────▼──────┐ │   ┌───────▼────────┐    ┌──────▼─────────┐
│Revisions      │   │Content Types │ │   │Access Records  │    │Node CRUD Hooks │
└───────────────┘   └─────────────┘ │   └────────────────┘    └────────────────┘
                                    │
                          ┌─────────▼──────────┐
                          │  Node Field System │
                          └──────────┬─────────┘
                                     │
                         ┌───────────┼───────────┐
                         │           │           │
                ┌────────▼────┐ ┌────▼─────┐ ┌───▼────────────┐
                │ Base Fields │ │Field UI  │ │Display/View Modes│
                └─────────────┘ └──────────┘ └────────────────┘

Quick Reference

• Primary Entity Types:

  • node: Content entities
  • node_type: Content type configuration entities

• Primary Classes:

  • \Drupal\node\Entity\Node: The core Node class
  • \Drupal\node\Entity\NodeType: The NodeType configuration entity
  • \Drupal\node\NodeAccessControlHandler: Access control handler
  • \Drupal\node\NodeStorage: Node storage handler
  • \Drupal\node\NodeViewBuilder: Rendering handler

• Key Services:

  • entity_type.manager->getStorage('node'): Node storage service
  • entity_type.manager->getViewBuilder('node'): Node renderer
  • node.grant_storage: Node access grant storage

• Important Hooks:

  • hook_node_access: Access control for nodes
  • hook_node_grants: Define node access grants
  • hook_node_access_records: Define node access records
  • hook_node_presave: Act before a node is saved
  • hook_node_insert/update/delete: React to node operations
  • hook_node_view/view_alter: Modify node display

• Common Operations:

  • Node::create(): Create a new node
  • Node::load(): Load a node by ID
  • Node::loadMultiple(): Load multiple nodes
  • $node->save(): Save a node
  • $node->delete(): Delete a node
  • $node->createDuplicate(): Clone a node

AI Recommendation

When working with Drupal's Node module, consider these approaches:

1. Use Content Types for Different Content Models: Define separate content types for distinct content structures rather than overloading a single type with conditional fields.

// Create clear content types with focused purposes
$content_types = [
  'article' => [
    'name' => 'Article',
    'description' => 'Use for news content with a publication date',
  ],
  'page' => [
    'name' => 'Basic page',
    'description' => 'Use for static content like About page',
  ],
  'event' => [
    'name' => 'Event',
    'description' => 'Use for calendar events with date and location',
  ],
];

2. Leverage Existing Node Hooks: Use the node hook system rather than overriding classes when possible.

/**
 * Implements hook_node_presave().
 */
function mymodule_node_presave(\Drupal\node\NodeInterface $node) {
  // Set a custom property based on node data.
  if ($node->getType() == 'article' && $node->isNew()) {
    $node->field_publication_date = date('Y-m-d');
  }
}

3. Use Typed Data API for Field Values: Access field data correctly using the typed data API.

// Properly access field values
$title = $node->getTitle();
$body_value = $node->get('body')->value;
$body_format = $node->get('body')->format;

// For entity reference fields
if (!$node->get('field_image')->isEmpty()) {
  $file_id = $node->get('field_image')->target_id;
  // Or access the entity directly
  $file = $node->get('field_image')->entity;
}

4. Use Node Access API Correctly: Implement proper node access controls.

// Check node access before operations
if ($node->access('view')) {
  // ...show node content
}

// For programmatic access checks
$access = \Drupal::entityTypeManager()
  ->getAccessControlHandler('node')
  ->access($node, 'update', $account, TRUE);

5. Optimize Node Queries: Use entity queries efficiently.

// Efficient node query
$query = \Drupal::entityQuery('node')
  ->condition('type', 'article')
  ->condition('status', 1)
  ->condition('field_category', $term_id)
  ->accessCheck(TRUE)
  ->sort('created', 'DESC')
  ->range(0, 10);
$nids = $query->execute();

6. Use View Builder for Rendering: Render nodes using the view builder.

// Proper rendering
$view_builder = \Drupal::entityTypeManager()->getViewBuilder('node');
$rendered_node = $view_builder->view($node, 'teaser');
// Or with a specific language
$rendered_node = $view_builder->view($node, 'full', $language->getId());

7. Maintain Revision Information: Keep revision metadata accurate.

// Proper revision handling
$node->setNewRevision(TRUE);
$node->setRevisionUserId($user_id);
$node->setRevisionCreationTime(time());
$node->setRevisionLogMessage('Reason for the revision');
$node->save();

The Node module is the cornerstone of Drupal's content management capabilities. Understanding its architecture allows you to create sophisticated content models and workflows while leveraging Drupal's built-in capabilities for access control, revision management, and content display.

plugin-system.md

Drupal Plugin System

Tags: Architecture, Core, Plugins, Extension, Discovery

High-Level Overview

The Plugin System is Drupal's implementation of the Component Plugin Pattern, providing a standardized way to create swappable, discoverable components with consistent interfaces. Plugins enable extensibility by allowing modules to provide interchangeable implementations of specific functionality that can be discovered and used by other code without direct dependencies.

Purpose in Drupal Architecture

The Plugin System serves as Drupal's primary extension mechanism by:

1. Providing a standardized way to define, discover, and instantiate components
2. Allowing modules to extend core and other modules without tight coupling
3. Supporting different discovery mechanisms (annotations, attributes, hooks)
4. Handling plugin initialization with dependency injection
5. Enabling dynamic plugin selection based on runtime conditions
6. Supporting cacheable plugin discovery for performance optimization
7. Providing a factory pattern for instantiating plugins with configuration

By abstracting the discovery and instantiation processes, the plugin system enables developers to focus on the implementation of specific functionality rather than the mechanisms for integrating it into the larger system.

Hierarchical Breakdown

1. Plugin System Components

• Plugin Manager: Central coordinator implementing PluginManagerInterface
• Discovery: Component that locates and defines available plugins
• Factory: Component that instantiates plugin instances from definitions
• Mapper: Optional component that selects plugins for specific contexts
• Plugin Definitions: Metadata that describes plugin capabilities
• Plugin Instances: Actual implementations of plugin functionality

2. Plugin Discovery Methods

• Annotation-based Discovery: Using PHP docblock annotations
• Attribute-based Discovery: Using PHP 8 attributes
• Hook-based Discovery: Using Drupal's hook system
• YAML-based Discovery: Using YAML files to define plugins
• Static Discovery: Manually defining plugins in PHP

3. Plugin Types

• Block Plugins: Reusable content blocks
• Field Types: Data storage and display formats
• Field Formatters: How field data is rendered
• Field Widgets: UI controls for editing field data
• Views Plugins: Various components for Views functionality
• Entity Types: Definition of content/config entities
• Filter Plugins: Text processing options
• Action Plugins: Operations that can be performed
• Condition Plugins: Context-based logic rules
• Queue Workers: Batch processing handlers
• And many more: Drupal defines dozens of plugin types

Concrete Examples

1. Creating a Custom Plugin Manager

/**
 * Plugin manager for example plugins.
 */
class ExamplePluginManager extends DefaultPluginManager {

  /**
   * Constructs a new ExamplePluginManager.
   */
  public function __construct(
    \Traversable $namespaces,
    CacheBackendInterface $cache_backend,
    ModuleHandlerInterface $module_handler
  ) {
    parent::__construct(
      'Plugin/Example',
      $namespaces,
      $module_handler,
      'Drupal\example\ExampleInterface',
      'Drupal\example\Attribute\Example',
    );
    $this->alterInfo('example_info');
    $this->setCacheBackend($cache_backend, 'example_plugins');
  }
}

2. Creating a Plugin Implementation

namespace Drupal\my_module\Plugin\Example;

use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\example\ExampleInterface;
use Drupal\example\Attribute\Example;
use Symfony\Component\DependencyInjection\ContainerInterface;

#[Example(
  id: 'my_example',
  label: 'My Example Plugin',
)]
class MyExample implements ExampleInterface, ContainerFactoryPluginInterface {

  /**
   * {@inheritdoc}
   */
  public static function create(
    ContainerInterface $container,
    array $configuration,
    $plugin_id,
    $plugin_definition
  ) {
    return new static(
      $configuration,
      $plugin_id,
      $plugin_definition,
      $container->get('current_user')
    );
  }

  /**
   * Constructs a MyExample object.
   */
  public function __construct(
    array $configuration,
    $plugin_id,
    $plugin_definition,
    private readonly AccountProxyInterface $currentUser
  ) {
    $this->configuration = $configuration;
    $this->pluginId = $plugin_id;
    $this->pluginDefinition = $plugin_definition;
  }

  // Implementation of plugin interface methods...
}

3. Using Plugins in Code

// Get a plugin manager from the service container
$manager = \Drupal::service('plugin.manager.example');

// Get all plugin definitions
$definitions = $manager->getDefinitions();

// Create an instance of a specific plugin
$instance = $manager->createInstance('my_example', [
  'setting_one' => 'value',
]);

// Use the plugin
$result = $instance->doSomething();

4. Plugin Discovery and Decoration

// Example of a plugin manager with decorated discovery
protected function getDiscovery() {
  if (!$this->discovery) {
    // Create the base discovery
    $discovery = new AttributeClassDiscovery(
      $this->subdir,
      $this->namespaces,
      $this->pluginDefinitionAttributeName
    );
    
    // Allow plugins to be derived from base definitions
    $discovery = new ContainerDerivativeDiscoveryDecorator($discovery);
    
    $this->discovery = $discovery;
  }
  return $this->discovery;
}

Relationships to Other Components

• Dependency Injection Container: Provides services for plugins including managers
• Module System: Modules define plugins and provide plugin discovery paths
• Cache System: Used to cache plugin definitions for performance
• Entity System: Entities are defined and managed through plugins
• Field System: Fields, formatters, and widgets are all plugin types
• Annotation System: Used for declarative plugin definitions in docblocks
• Theme System: Block plugins and field formatters use the theme system

Common Patterns and Edge Cases

Common Patterns

• Plugin Derivatives: Creating multiple plugin definitions from a single class
• Container Factory Plugins: Plugins that get services from the container
• Default Plugins: Fallback implementations when specific plugins aren't available
• Context-Aware Plugins: Plugins that adapt behavior based on context
• Plugin Collections: Managing multiple plugin instances together

Edge Cases

• Circular Plugin Dependencies: When plugins depend on each other
• Plugin Definition Alteration: Modules modifying other modules' plugin definitions
• Lazy Loading: Performance optimizations for many plugin instances
• Plugin Migration: Handling renamed or refactored plugins
• Plugin Configuration Schema: Validating configuration for plugin instances

Concept Map

                             ┌─────────────────┐
                             │  Plugin System  │
                             └────────┬────────┘
                                      │
            ┌─────────────────────────┼────────────────────────┐
            │                         │                        │
┌───────────▼─────────────┐ ┌─────────▼───────────┐ ┌─────────▼──────────┐
│ Plugin Manager Interface │ │ Plugin Discovery    │ │ Plugin Factory     │
└───────────┬─────────────┘ └─────────┬───────────┘ └─────────┬──────────┘
            │                         │                       │
┌───────────▼─────────────┐           │                       │
│ Default Plugin Manager  │           │                       │
└───────────┬─────────────┘           │                       │
            │                         │                       │
            │             ┌───────────▼────────────┐          │
            │             │ Discovery Mechanisms   │          │
            │             └───────────┬────────────┘          │
            │                         │                       │
            │             ┌───────────┼────────────┐          │
            │             │           │            │          │
            │   ┌─────────▼───┐ ┌─────▼───────┐ ┌──▼─────────┐│
            │   │ Annotation  │ │ Attribute   │ │ YAML/Hook  ││
            │   └─────────────┘ └─────────────┘ └────────────┘│
            │                                                 │
            └─────────────────────┬─────────────────────────┬─┘
                                  │                         │
                      ┌───────────▼────────────┐ ┌──────────▼──────────┐
                      │ Plugin Definitions     │ │ Plugin Instances    │
                      └───────────┬────────────┘ └──────────┬──────────┘
                                  │                         │
                                  │                         │
                      ┌───────────▼────────────┐            │
                      │ Plugin Types           │            │
                      └───────────┬────────────┘            │
                                  │                         │
          ┌────────────┬──────────┼─────────┬───────────┐   │
          │            │          │         │           │   │
┌─────────▼────┐ ┌─────▼─────┐ ┌──▼──────┐ ┌▼────────┐ ┌▼───▼─────┐
│Block Plugins │ │Field Types│ │Formatters│ │Widgets  │ │Conditions│
└──────────────┘ └───────────┘ └─────────┘ └─────────┘ └───────────┘

Quick Reference

• Primary Interfaces:

  • \Drupal\Component\Plugin\PluginManagerInterface
  • \Drupal\Component\Plugin\Discovery\DiscoveryInterface
  • \Drupal\Component\Plugin\Factory\FactoryInterface

• Primary Classes:

  • \Drupal\Core\Plugin\DefaultPluginManager
  • \Drupal\Core\Plugin\Discovery\AnnotatedClassDiscovery
  • \Drupal\Core\Plugin\Discovery\AttributeClassDiscovery
  • \Drupal\Core\Plugin\Factory\ContainerFactory

• Common Plugin Types:

  • Block
  • Field Type
  • Field Formatter
  • Field Widget
  • Entity Type
  • Views Plugin
  • Filter Format
  • Action
  • Condition

• Plugin Definition Keys:

  • id: Unique identifier for the plugin
  • label: Human-readable name
  • class: Implementation class
  • provider: Module that provides the plugin
  • weight: For ordering plugins

AI Recommendation

When working with Drupal's plugin system, consider these approaches:

1. Extend Core Plugin Types First: Before creating your own plugin type, check if an existing core plugin type can be extended to meet your needs.

2. Dependency Injection: Implement ContainerFactoryPluginInterface to get services from the container rather than using the service locator pattern:

public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
  return new static(
    $configuration,
    $plugin_id,
    $plugin_definition,
    $container->get('entity_type.manager')
  );
}

3. Designing Plugin Interfaces: Define small, focused interfaces that clearly express what your plugins do, with default implementations for common behavior:

interface MyPluginInterface {
  public function getLabel(): string;
  public function process($data): array;
}

4. Plugin Derivatives: Use derivatives when you need multiple plugin definitions from a single class:

class MyDerivative extends DeriverBase {
  public function getDerivativeDefinitions($base_plugin_definition) {
    foreach ($this->getValues() as $key => $value) {
      $this->derivatives[$key] = $base_plugin_definition;
      $this->derivatives[$key]['label'] = $value;
    }
    return $this->derivatives;
  }
}

5. For Performance: Cache plugin definitions in production and use optimized discovery mechanisms:

// In your plugin manager constructor
$this->setCacheBackend($cache_backend, 'my_plugin_type');

6. For Module Integration: Allow other modules to alter your plugin definitions:

// In your plugin manager constructor
$this->alterInfo('my_plugin_info');

7. For Testability: Mock the plugin manager in tests rather than creating actual plugin instances.

The plugin system is one of Drupal's most powerful architectural components. Understanding it thoroughly allows you to create extensible, modular, and maintainable code that follows Drupal's best practices and design patterns.

PROMPT.md

You are an expert in both Drupal architecture and machine learning. Your task is to transform Drupal documentation into an AI-optimized format that helps language models understand the codebase.

Current Content

The files located in .ai-docs

Task

Transform this content into a comprehensive explanation optimized for AI comprehension by:

1. Starting with a high-level overview of the concept, component, or pattern
2. Explaining its purpose and position in Drupal's architecture
3. Providing a hierarchical breakdown of related sub-concepts
4. Including concrete examples with code snippets
5. Explicitly stating relationships to other Drupal components
6. Noting common patterns, variations, and edge cases
7. Adding metadata tags that categorize the concept (Architecture, API, Pattern, etc.)
8. Linking to related code files and documentation

Format Requirements

• Use Markdown format with clear section headers
• Include a "Concept Map" section showing relationships
• Create a "Quick Reference" section summarizing key points
• Add an "AI Recommendation" section explaining how to correctly apply this knowledge

Ensure the explanation would help an AI assistant understand not just the technical details but the reasoning and architectural decisions behind them.

routing-system.md

Drupal Routing System

Tags: Architecture, Core, HTTP, Request Handling, Controllers

High-Level Overview

The Routing System is Drupal's framework for mapping HTTP requests to controller code, built on top of Symfony's HTTP kernel. It governs how URLs are defined, how access is controlled, and how parameters are extracted and passed to controllers. The routing system translates the incoming request path into a structured route, matches it with defined routes, and then executes the appropriate controller with the resolved parameters.

Purpose in Drupal Architecture

The Routing System serves as the HTTP request dispatcher by:

1. Defining the URL structure of the Drupal application
2. Mapping URLs to controller classes and methods
3. Extracting parameters from URL paths
4. Handling access control at the route level
5. Converting path parameters into usable objects
6. Managing cached routes for performance
7. Supporting dynamic route generation for entities and plugins
8. Providing APIs for route discovery and manipulation

By integrating with Symfony's HTTP foundation, the routing system provides a standardized approach to request handling while extending it with Drupal-specific concepts like access checking, parameter conversion, and route providers.

Hierarchical Breakdown

1. Route Definition Components

• Route: Represents a registered URL pattern and its metadata
• RouteCollection: Container for multiple routes
• RouteProvider: Service that loads route definitions
• RouteEnhancers: Add additional data to routes during matching
• RouteFilters: Filter routes based on criteria (site context)
• Route Access: Controls who can access a specific route
• Route Parameters: Dynamic parts of a route path

2. Route Registration Sources

• Module .routing.yml files: Static route definitions
• Entity Type Definitions: Dynamic routes for entities
• Route Subscribers: Dynamically alter route collections
• Entity Type Routes: Generated from entity link templates
• Route Defaults: Default values for request attributes
• Route Requirements: Constraints and validation rules

3. Request Processing

• Router: Matches incoming path to defined routes
• RouterListener: Event subscriber that handles routing
• HttpKernel: Resolves the controller from the route
• ControllerResolver: Maps route controller definitions to PHP callables
• ArgumentResolver: Prepares arguments for the controller
• RequestContext: Information about the current request
• ParamConverter: Converts route parameters to objects

4. Controller Architecture

• ControllerBase: Base class with utility methods
• FormControllers: Special controllers that handle forms
• EntityControllers: Controllers for entity operations
• ControllerInterface: Common interface for controllers

Concrete Examples

1. Route Definition in YAML

# Example route definition in mymodule.routing.yml
mymodule.example:
  path: '/example/{parameter}'
  defaults:
    _controller: '\Drupal\mymodule\Controller\ExampleController::content'
    _title: 'Example Page'
  requirements:
    _permission: 'access content'
  options:
    parameters:
      parameter:
        type: string

2. Controller Implementation

namespace Drupal\mymodule\Controller;

use Drupal\Core\Controller\ControllerBase;
use Symfony\Component\HttpFoundation\Request;

/**
 * Controller for the example route.
 */
class ExampleController extends ControllerBase {

  /**
   * Displays content for the example page.
   *
   * @param string $parameter
   *   The parameter from the URL.
   * @param \Symfony\Component\HttpFoundation\Request $request
   *   The current request.
   *
   * @return array
   *   A render array for the page content.
   */
  public function content($parameter, Request $request) {
    return [
      '#markup' => $this->t('The parameter value is: @parameter', [
        '@parameter' => $parameter,
      ]),
    ];
  }
}

3. Route Subscriber

namespace Drupal\mymodule\Routing;

use Drupal\Core\Routing\RouteSubscriberBase;
use Symfony\Component\Routing\RouteCollection;

/**
 * Listens to the dynamic route events.
 */
class RouteSubscriber extends RouteSubscriberBase {

  /**
   * {@inheritdoc}
   */
  protected function alterRoutes(RouteCollection $collection) {
    // Change access permission for an existing route.
    if ($route = $collection->get('entity.node.canonical')) {
      $route->setRequirement('_permission', 'my custom permission');
    }
    
    // Add a new option to an existing route.
    if ($route = $collection->get('entity.user.canonical')) {
      $route->setOption('no_cache', TRUE);
    }
  }
}

4. Parameter Converter

namespace Drupal\mymodule\ParamConverter;

use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\ParamConverter\ParamConverterInterface;
use Symfony\Component\Routing\Route;

/**
 * Parameter converter for custom entities.
 */
class CustomEntityConverter implements ParamConverterInterface {
  
  /**
   * The entity type manager.
   *
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected $entityTypeManager;
  
  /**
   * Constructs a new CustomEntityConverter.
   *
   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
   *   The entity type manager.
   */
  public function __construct(EntityTypeManagerInterface $entity_type_manager) {
    $this->entityTypeManager = $entity_type_manager;
  }

  /**
   * {@inheritdoc}
   */
  public function convert($value, $definition, $name, array $defaults) {
    return $this->entityTypeManager->getStorage('custom_entity')->load($value);
  }

  /**
   * {@inheritdoc}
   */
  public function applies($definition, $name, Route $route) {
    return !empty($definition['type']) && $definition['type'] == 'custom_entity';
  }
}

Relationships to Other Components

• Event System: Route matching and access checking dispatch events that other modules can listen to
• Controller System: Routes map to controllers that implement the application logic
• Access System: Routes define access requirements that are checked by access checkers
• Entity System: Entity types define routes for standard operations like view, edit, delete
• Form API: Form routes are special routes that process form submissions
• Menu System: Menu links can point to defined routes
• Services: Route-related components are registered as services
• Caching System: Route definitions and matching results are cached for performance

Common Patterns and Edge Cases

Common Patterns

• Dynamic Route Generation: Routes generated from entity types or plugins
• Route Parameters: Extracting parts of the URL as parameters
• Parameter Conversion: Converting path parameters into objects
• Route Access Control: Defining who can access which routes
• Route Alterations: Modifying routes from other modules
• Route Negotiation: Selecting the appropriate route based on context
• Route Caching: Caching routes for performance
• Subrequests: Making internal HTTP requests using routes

Edge Cases

• Multilingual Paths: Handling translation of route paths
• Path Placeholders: Handling special characters in path parameters
• Route Conflicts: Managing conflicts when multiple routes match a path
• Route Access Caching: Properly caching access results for routes
• Dynamic Route Priority: Managing priority when routes overlap
• Contextual Route Access: Access based on parameter values
• Redirect Handling: Managing redirects to alternate routes
• Subrequest Parameter Handling: Preserving parameters in nested requests

Concept Map

                                     ┌─────────────────┐
                                     │    Request      │
                                     └───────┬─────────┘
                                             │
                                     ┌───────▼─────────┐
                                     │ HttpKernel      │
                                     └───────┬─────────┘
                                             │
                ┌────────────────────┬──────▼──────┬──────────────────────┐
                │                    │             │                      │
       ┌────────▼────────┐  ┌───────▼───────┐    │      ┌────────────────▼─┐
       │ Event Subscribers│  │ Routing System│    │      │ Controller System│
       └────────┬─────────┘  └───────┬───────┘    │      └─────────┬────────┘
                │                    │            │                │
    ┌───────────▼────────┐  ┌───────▼────────┐   │      ┌─────────▼───────┐
    │ RouterListener     │  │ RouteProvider  │   │      │ ControllerResolver
    └────────────────────┘  └───────┬────────┘   │      └───────────────────┘
                                    │            │
                          ┌─────────▼────────┐   │      ┌─────────────────┐
                          │ RouteCollection  │   └──────► ParamConverters │
                          └─────────┬────────┘          └─────────────────┘
                                    │
                        ┌───────────┼────────────┐
                        │           │            │
               ┌────────▼───┐ ┌─────▼─────┐ ┌────▼────┐
               │ Route      │ │RouteFilters│ │RouteMatch│
               └────────────┘ └───────────┘ └─────────┘

Quick Reference

• Primary Classes:

  • \Drupal\Core\Routing\RouteProvider: Loads and caches routes
  • \Drupal\Core\Routing\Router: Matches incoming paths to routes
  • \Symfony\Component\Routing\Route: Represents a single route
  • \Symfony\Component\Routing\RouteCollection: Collection of routes
  • \Drupal\Core\Routing\RouteMatch: Result of matched route

• Key Files:

  • *.routing.yml: Module route definitions
  • core.services.yml: Route service definitions
  • core/lib/Drupal/Core/Routing: Core routing classes

• Main Services:

  • router.route_provider: Drupal route provider
  • router.builder: Rebuilds the route information
  • router: The router service for matching paths
  • path.matcher: Matches request paths to routes
  • path.current: Provides the current path

• Common Route Requirements:

  • _permission: Permission required to access the route
  • _role: User role required to access the route
  • _entity_access: Entity-specific access requirement
  • _csrf_token: Requires a valid CSRF token
  • _format: Restricts to specific request format

AI Recommendation

When working with Drupal's routing system, consider these approaches:

1. Organize Routes Logically: Group related routes in your .routing.yml file with clear naming conventions.

# Group related functionality with naming conventions
mymodule.item.collection:
  path: '/items'
  # ...

mymodule.item.add:
  path: '/items/add'
  # ...

mymodule.item.view:
  path: '/items/{item}'
  # ...

2. Use Parameter Conversion: Leverage param converters to automatically load entities.

mymodule.entity_view:
  path: '/custom/{node}/view'
  defaults:
    _controller: '\Drupal\mymodule\Controller\CustomController::view'
  requirements:
    _entity_access: 'node.view'
  options:
    parameters:
      node:
        type: entity:node

3. Use Access Services: Create dedicated access services for complex access logic.

/**
 * Access check for a custom route.
 */
class CustomAccessCheck implements AccessInterface {
  public function access(AccountInterface $account, $parameter = NULL) {
    // Custom access logic here.
    return AccessResult::allowedIf($condition)
      ->cachePerPermissions()
      ->cachePerUser()
      ->addCacheableDependency($some_entity);
  }
}

4. Leverage Route Subscribers: Use route subscribers to dynamically alter routes.

public function alterRoutes(RouteCollection $collection) {
  // Modify route to use AJAX.
  if ($route = $collection->get('entity.node.edit_form')) {
    $route->setOption('_admin_route', TRUE);
  }
}

5. Consider Performance: Minimize the number of routes and use efficient access checks.

// In your route definition, use the most efficient access check.
// For example, use _permission instead of a custom access check 
// if permission is all you need to check.
requirements:
  _permission: 'access content'  // More efficient than custom access

6. Create Contextual Routes: Use the request context to provide dynamic paths.

mymodule.contextual_route:
  path: '/admin/content/custom-tab'
  defaults:
    _controller: '\Drupal\mymodule\Controller\AdminController::customTab'
  requirements:
    _permission: 'administer content'
  options:
    _admin_route: TRUE

7. Handle Form Submissions Correctly: Understand how form submissions interact with routes.

mymodule.form_example:
  path: '/myform'
  defaults:
    _form: '\Drupal\mymodule\Form\ExampleForm'
    _title: 'Example Form'
  requirements:
    _permission: 'access content'

The routing system is one of Drupal's most critical subsystems as it controls the entry points to your application. Understanding its intricacies allows you to create clean, performant, and secure URL structures that properly integrate with Drupal's access control and object resolution systems.

service-container.md

Drupal Service Container Architecture

Tags: Architecture, Core, Dependency Injection, Services, Symfony

High-Level Overview

The Service Container is Drupal's implementation of the dependency injection pattern, based on Symfony's DependencyInjection component. It provides a centralized registry of services (objects that perform specific functions) and manages their instantiation and dependencies. The container is responsible for constructing services when they are needed and injecting their dependencies.

Purpose in Drupal Architecture

The Service Container serves as the backbone of Drupal's modular architecture by:

1. Decoupling service consumers from service implementations
2. Enabling modules to define, override, and extend functionality
3. Facilitating testability through dependency injection
4. Providing a consistent pattern for accessing functionality
5. Allowing for performance optimization through service compilation and lazy loading

By centralizing service definitions, Drupal creates a highly extensible system where modules can modify behavior without changing core code, while maintaining clear dependency chains.

Hierarchical Breakdown

1. Service Container Components

• ContainerBuilder: Drupal's extension of Symfony's ContainerBuilder
• ServiceProvider: Interface for registering services
• ServiceModifier: Interface for altering existing services
• CompilerPass: Process that modifies container definitions before compilation
• Container: The compiled, optimized service container class
• Definition: Object representing a service definition with its arguments and tags

2. Service Registration Sources

• Core Services: Defined in core.services.yml
• Module Services: Each module can define services in module_name.services.yml
• ServiceProvider Classes: PHP classes that register/modify services programmatically
• Site-specific Services: Override services in settings.php

3. Service Types

• Regular Services: Standard services instantiated when requested
• Factory Services: Services created by factory methods
• Synthetic Services: Services set from outside the container
• Tagged Services: Services with tags that can be collected
• Lazy Services: Services wrapped in proxies for performance
• Private Services: Services only used as dependencies, not retrievable directly
• Shared Services: Services returned as singletons (default behavior)

Concrete Examples

1. Service Definition in YAML

# Example from a module.services.yml file
services:
  # A simple service definition
  mymodule.my_service:
    class: Drupal\mymodule\MyService
    arguments: ['@database', '@config.factory']
    tags:
      - { name: cache.bin }
    calls:
      - [setLogger, ['@logger.channel.mymodule']]

2. Service Provider Implementation

namespace Drupal\mymodule;

use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\DependencyInjection\ServiceProviderInterface;

class MymoduleServiceProvider implements ServiceProviderInterface {
  public function register(ContainerBuilder $container) {
    // Register a service programmatically
    $container->register('mymodule.dynamic_service', MyDynamicService::class)
      ->addArgument('%app.root%');
  }
}

3. Service Modifier Implementation

namespace Drupal\mymodule;

use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\DependencyInjection\ServiceModifierInterface;

class MymoduleServiceProvider implements ServiceModifierInterface {
  public function alter(ContainerBuilder $container) {
    // Override an existing service
    if ($container->has('file.usage')) {
      $definition = $container->getDefinition('file.usage');
      $definition->setClass('Drupal\mymodule\CustomFileUsage');
    }
  }
}

4. Using Tagged Services

// A compiler pass that collects tagged services
public function process(ContainerBuilder $container) {
  $handlers = [];
  foreach ($container->findTaggedServiceIds('mymodule.handler') as $id => $tags) {
    $priority = $tags[0]['priority'] ?? 0;
    $handlers[$priority][] = new Reference($id);
  }
  
  // Sort by priority and flatten
  krsort($handlers);
  $handlers = array_merge(...$handlers);
  
  // Add the handlers to our manager service
  $container->getDefinition('mymodule.handler_manager')
    ->setArgument(0, $handlers);
}

Relationships to Other Components

• Kernel: Builds and initializes the service container
• Plugin System: Many plugin managers are services that discover and instantiate plugins
• Event System: Event subscribers are tagged services discovered by compiler passes
• Drupal Static Class: A service locator facade for accessing container services
• Module System: Modules provide service definitions and service providers
• Routing System: Route controllers are resolved and instantiated by the container
• Configuration System: Often injected into services that need configuration

Common Patterns and Edge Cases

Common Patterns

• Service Tags: Used to collect services of a particular type
• Factory Pattern: Services created by factory services
• Decorator Pattern: Services that wrap other services to add functionality
• Chain of Responsibility: Multiple services processing a task in sequence
• Lazy Loading: Using proxies to delay service instantiation

Edge Cases

• Circular Dependencies: Cannot have services that depend on each other directly
• Container Reset: Services marked with "persist" tag survive container rebuilds
• Early Service Access: Some services needed during container building (bootstrap)
• Service Cache: Compiled container is cached for performance
• Container in Service Provider: Accessing services during registration can be risky

Concept Map

                                            ┌─────────────────┐
                                            │  YAML Files     │
                                            └────────┬────────┘
                                                     │
                      ┌─────────────────────────────▼─────────────────────────────┐
                      │                       ContainerBuilder                     │
                      └─┬───────────────────────────┬─────────────────────────────┘
                        │                           │
              ┌─────────▼───────────┐    ┌──────────▼────────────┐
              │ ServiceProviders   │    │ CompilerPasses        │
              └─┬─────────────┬────┘    └──────────┬────────────┘
                │             │                    │
      ┌─────────▼────┐  ┌────▼───────┐   ┌────────▼────────┐
      │  register()  │  │  alter()   │   │    process()    │
      └─────────┬────┘  └────┬───────┘   └────────┬────────┘
                │             │                    │
                └─────────────▼────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │ Service Definitions│
                    └─────────┬─────────┘
                              │
                    ┌─────────▼─────────┐          ┌─────────────────┐
                    │ Container (Cached) ├──────────► Tagged Services │
                    └─────────┬─────────┘          └─────────────────┘
                              │
                ┌─────────────┼──────────────┬───────────────┐
                │             │              │               │
      ┌─────────▼─────┐ ┌────▼─────┐ ┌──────▼────────┐ ┌────▼───────┐
      │ Regular Service│ │ Factories│ │ Lazy Services │ │ Synthetic  │
      └───────────────┘ └──────────┘ └───────────────┘ └────────────┘

Quick Reference

• Primary Class: \Drupal\Core\DependencyInjection\ContainerBuilder
• Interfaces: ServiceProviderInterface, ServiceModifierInterface
• Key Files: core.services.yml, module_name.services.yml
• Access Pattern: \Drupal::service('service_id') or injection
• Module Pattern: mymodule.service_name naming convention
• Common Tags: event_subscriber, cache.bin, http_client_middleware
• Service Parameters: Stored with container.setParameter(), accessed with %parameter_name%

AI Recommendation

When working with Drupal's service container, consider these approaches:

1. Favor Constructor Injection: Always inject dependencies in the constructor rather than using the service locator.

// Recommended
public function __construct(
  private readonly ConfigFactoryInterface $configFactory,
  private readonly LoggerChannelInterface $logger
) {}

// Avoid
public function someMethod() {
  $config = \Drupal::config('my_module.settings');
}

2. Use Interface Types: Type hint against interfaces rather than concrete implementations.

// Recommended
public function __construct(EntityTypeManagerInterface $entityTypeManager) {}

// Avoid
public function __construct(EntityTypeManager $entityTypeManager) {}

3. Service Organization: Group related functionality in a single service rather than creating many tiny services.

4. Service Tags: Use tags to create discoverable services that can be collected, but document the tag's purpose.

5. Factory Methods: For services with complex instantiation logic, use factory services or methods.

6. Consider Performance: For rarely used services, use lazy services to improve container initialization time.

7. Testing: Services facilitate testing by allowing dependencies to be mocked or replaced.

The service container is the heart of Drupal's architecture. Understanding it is essential for building maintainable, extensible code that integrates well with Drupal's existing systems and can be easily tested and modified.

theme-system.md

Drupal Theme System

Tags: Architecture, Core, Theme, Rendering, Frontend

High-Level Overview

The Theme System is Drupal's rendering and presentation layer, responsible for transforming structured data into HTML output. It provides a flexible framework for defining how content appears to users, separating visual presentation from business logic. The theme system uses render arrays as an intermediary format, processes them through a render pipeline, and ultimately generates themed HTML through Twig templates, theme hooks, and preprocessors.

Purpose in Drupal Architecture

The Theme System serves as the critical final layer of Drupal's architecture by:

1. Separating presentation logic from business logic
2. Providing a standardized way to structure output data
3. Enabling theme developers to override any aspect of presentation
4. Allowing modular customization through layers of preprocessing
5. Creating a cache-aware rendering pipeline for performance
6. Supporting responsive design through breakpoints and image styles
7. Facilitating translation and other output alterations
8. Organizing and managing frontend assets (CSS, JavaScript)

By providing these capabilities, the theme system enables Drupal to maintain a clean separation of concerns while offering maximum flexibility for visual customization.

Hierarchical Breakdown

1. Render Array System

• Render Arrays: Structured arrays representing renderable content
• Render Elements: Specialized elements with predefined properties
• Element Properties: Special keys controlling rendering behavior
• Nested Structure: Hierarchical organization of renderable elements
• Weight Property: Controls the order of rendered elements
• #theme: Property that determines which theme hook to use
• #markup: Property for direct HTML output
• #type: Property specifying the render element type
• #attached: Property for adding CSS, JS, libraries, and other assets

2. Render Pipeline

• Renderer Service: Orchestrates the rendering process
• Render Cache: Caches rendered content for performance
• Cache Contexts: Defines variations of cached content
• Cache Tags: Identifies dependencies for cache invalidation
• Placeholder Strategy: Handles dynamic uncacheable content
• Render Callbacks: Functions that transform render arrays
• Lazy Builders: Defers rendering of expensive elements

3. Theme Hooks and Templates

• Theme Hooks: Registration points for themeable output
• Theme Functions: PHP functions that generate HTML (legacy)
• Twig Templates: Template files that generate HTML (modern)
• Theme Hook Suggestions: Variant possibilities for theme hooks
• Template Discovery: How templates are located and selected
• Theme Registry: Stores information about all available hooks

4. Preprocess System

• Preprocess Functions: Alter variables before rendering
• Process Functions: Final alterations to variables
• Theme Suggestions: Alternate theme implementations
• Module Preprocess: Alterations from modules
• Theme Preprocess: Alterations from themes
• Hook Naming Conventions: How preprocess functions are named

5. Asset Management

• Libraries API: Manages CSS and JavaScript assets
• Library Definition: YAML files declaring assets
• Asset Aggregation: Combining assets for performance
• Asset Optimization: Minification and compression
• Responsive Images: Serving appropriate image sizes
• Breakpoints: Defining device width boundaries
• Library Overrides: Alter libraries from other modules

6. Theming Components

• Theme Engine: System that powers rendering (Twig)
• Base Themes: Parent themes providing foundation
• Theme Inheritance: How child themes extend parents
• Theme Regions: Designated areas for placing blocks
• Theme Settings: Configuration options for themes
• Theme Functions: Theme-specific logic and alterations

Concrete Examples

1. Creating and Rendering a Basic Render Array

// Creating a simple render array
$build = [
  '#type' => 'container',
  '#attributes' => [
    'class' => ['my-container'],
    'id' => 'my-unique-id',
  ],
  'title' => [
    '#type' => 'html_tag',
    '#tag' => 'h2',
    '#value' => t('Hello World'),
    '#weight' => 0,
  ],
  'content' => [
    '#type' => 'markup',
    '#markup' => '<p>' . t('This is a sample content.') . '</p>',
    '#weight' => 1,
  ],
  '#attached' => [
    'library' => [
      'mymodule/my-library',
    ],
  ],
];

// Rendering the array (typically done by Drupal automatically)
$output = \Drupal::service('renderer')->render($build);

2. Implementing a Theme Hook

/**
 * Implements hook_theme().
 */
function mymodule_theme($existing, $type, $theme, $path) {
  return [
    'my_custom_item' => [
      'variables' => [
        'title' => NULL,
        'description' => NULL,
        'items' => [],
        'attributes' => [],
      ],
      'file' => 'includes/theme.inc',
      'template' => 'my-custom-item', // maps to templates/my-custom-item.html.twig
    ],
  ];
}

// Using the theme hook
$output = [
  '#theme' => 'my_custom_item',
  '#title' => 'Custom Item Title',
  '#description' => 'This is a custom item description.',
  '#items' => $items,
  '#attributes' => ['class' => ['custom-item-wrapper']],
];

3. Twig Template Example

{# templates/my-custom-item.html.twig #}
<div{{ attributes.addClass('my-custom-item') }}>
  {% if title %}
    <h3>{{ title }}</h3>
  {% endif %}
  
  {% if description %}
    <div class="description">{{ description }}</div>
  {% endif %}
  
  {% if items %}
    <ul class="item-list">
      {% for item in items %}
        <li>{{ item }}</li>
      {% endfor %}
    </ul>
  {% endif %}
</div>

4. Implementing Preprocess Functions

/**
 * Implements hook_preprocess_HOOK() for node templates.
 */
function mymodule_preprocess_node(&$variables) {
  // Add the node ID as a class.
  $variables['attributes']['class'][] = 'node-' . $variables['node']->id();
  
  // Add a custom variable.
  $variables['is_featured'] = FALSE;
  
  // Check if the node has a specific field.
  if ($variables['node']->hasField('field_featured') && 
      !$variables['node']->get('field_featured')->isEmpty() &&
      $variables['node']->get('field_featured')->value == 1) {
    $variables['is_featured'] = TRUE;
    $variables['attributes']['class'][] = 'featured-content';
  }
  
  // Add a custom date format.
  $variables['custom_date'] = \Drupal::service('date.formatter')
    ->format($variables['node']->getCreatedTime(), 'custom', 'F j, Y');
}

5. Defining a Library

# mymodule.libraries.yml
my-library:
  version: 1.x
  css:
    theme:
      css/my-styles.css: {}
  js:
    js/my-script.js: {}
  dependencies:
    - core/jquery
    - core/drupal
    - core/once

responsive-images:
  version: 1.x
  css:
    base:
      css/base.css: {}
    layout:
      css/layout.css: { media: screen and (min-width: 40em) }
    theme:
      css/theme.css: { weight: 100 }

Relationships to Other Components

• Renderer: Service that manages the rendering process
• HtmlResponseAttachmentsProcessor: Handles asset attachments
• AssetResolver: Resolves CSS and JS assets
• AggregateAssetOptimizer: Optimizes assets for performance
• TwigEnvironment: The Twig rendering engine
• ThemeManager: Manages theme selection and hooks
• ThemeInitialization: Initializes the active theme
• ElementInfo: Provides information about render elements
• RenderCache: Caches rendered output
• Registry: Stores information about theme hooks
• Entity System: Entities often rendered through theme system
• Block System: Blocks rendered through theme system
• Views Module: Views output rendered through theme system
• Field API: Field formatters rendered through theme system

Common Patterns and Edge Cases

Common Patterns

• Theme Hook Suggestions: Providing variant implementations
• Template Override Inheritance: Cascading template overrides
• Element Grouping: Organizing elements by region or type
• Conditional Classes: Adding classes based on conditions
• Contextual Rendering: Altering output based on context
• Library Inheritance: Building on existing libraries
• Responsive Images: Serving different image sizes
• Asset Optimization: Combining and minifying assets
• Lazy Loading: Deferred rendering for performance

Edge Cases

• Render Cache Bypassing: Managing uncacheable content
• Recursive Rendering: Preventing infinite rendering loops
• Twig Autoescape: Security considerations in templates
• Nested Render Arrays: Deep nesting performance issues
• Asset Weight Management: Controlling asset load order
• CSS/JS Aggregation Conflicts: Handling aggregation failures
• Theme Registry Rebuilding: Performance implications
• Render Context Leaking: Ensuring render contexts are closed
• Dynamic Preprocess Logic: Complex variable preparation

Concept Map

                           ┌─────────────────┐
                           │   Theme System  │
                           └────────┬────────┘
                                    │
    ┌───────────────────────┬───────┼────────────┬────────────────────────┐
    │                       │       │            │                        │
┌───▼───────────┐  ┌────────▼───┐   │     ┌──────▼─────┐       ┌──────────▼────┐
│ Render Arrays │  │Theme Hooks │   │     │Preprocess  │       │Library/Assets │
└───┬───────────┘  └────────┬───┘   │     └──────┬─────┘       └──────────┬────┘
    │                       │       │            │                        │
┌───▼───────────┐  ┌────────▼───┐   │     ┌──────▼─────┐       ┌──────────▼────┐
│Element Types  │  │Template    │   │     │Variables   │       │CSS/JS Files   │
└───────────────┘  │Discovery   │   │     └────────────┘       └───────────────┘
                   └────────────┘   │
                                  ┌─▼──────────┐
                                  │Render      │
                                  │Pipeline    │
                                  └──┬─────────┘
                                     │
                          ┌──────────┼───────────┐
                          │          │           │
                    ┌─────▼────┐  ┌──▼─────┐  ┌──▼──────────┐
                    │Renderer  │  │Caching │  │Placeholders │
                    └──────────┘  └────────┘  └─────────────┘

Quick Reference

• Key Services:

  • renderer: Main rendering service
  • theme.manager: Manages theme selection and hooks
  • theme.registry: Stores theme hook information
  • asset.resolver: Resolves CSS and JS assets
  • library.discovery: Discovers defined libraries
  • plugin.manager.element_info: Element information

• Important Files:

  • *.libraries.yml: Library definitions
  • templates/*.html.twig: Twig templates
  • *.theme: Theme hook implementations
  • theme.api.php: Documentation on theme hooks

• Element Properties:

  • #type: The element type to render
  • #theme: The theme hook to use
  • #markup: Raw HTML content
  • #plain_text: Text to be escaped
  • #attached: CSS, JS, and other attachments
  • #cache: Cache metadata
  • #prefix, #suffix: HTML wrappers
  • #weight: Ordering of elements

• Theme Functions:

  • hook_theme(): Registers theme hooks
  • hook_theme_suggestions_HOOK(): Alternative templates
  • hook_preprocess_HOOK(): Prepares variables
  • hook_process_HOOK(): Final variable processing

AI Recommendation

When working with Drupal's Theme System, consider these approaches:

1. Use Render Arrays Consistently: Structure your data with render arrays rather than direct HTML output to ensure proper caching and preprocessing.

// Recommended: Use render arrays
$build = [
  '#theme' => 'item_list',
  '#items' => $items,
  '#title' => t('My List'),
  '#cache' => [
    'tags' => ['node_list'],
    'contexts' => ['user.permissions'],
    'max-age' => 3600,
  ],
];

// Avoid: Direct HTML output
$output = '<h2>My List</h2><ul>';
foreach ($items as $item) {
  $output .= '<li>' . $item . '</li>';
}
$output .= '</ul>';

2. Leverage Theme Suggestions: Provide specific theme suggestions rather than overriding base templates.

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function mymodule_theme_suggestions_node_alter(array &$suggestions, array $variables) {
  $node = $variables['elements']['#node'];
  $sanitized_view_mode = strtr($variables['elements']['#view_mode'], '.', '_');
  
  // Add suggestions based on content type and view mode.
  $suggestions[] = 'node__' . $node->bundle() . '__' . $sanitized_view_mode;
  
  // Add suggestions based on node ID.
  $suggestions[] = 'node__' . $node->id();
  
  // Add suggestions based on custom conditions.
  if ($node->hasField('field_layout') && !$node->field_layout->isEmpty()) {
    $suggestions[] = 'node__layout_' . $node->field_layout->value;
  }
}

3. Include Proper Cache Metadata: Always define cache contexts, tags, and max-age for renderable elements.

$build['#cache'] = [
  'contexts' => ['user.permissions', 'languages:language_interface'],
  'tags' => ['node:' . $node->id(), 'user:' . $user->id()],
  'max-age' => Cache::PERMANENT,
];

4. Organize Libraries Logically: Structure your libraries with clear separation and dependencies.

# Recommended: Organized by purpose
my-module.admin:
  css:
    theme:
      css/admin.css: {}
  dependencies:
    - core/drupal.dialog

my-module.frontend:
  css:
    base:
      css/base.css: {}
    layout:
      css/layout.css: {}
    component:
      css/components.css: {}
  js:
    js/behavior.js: {}
  dependencies:
    - core/once

5. Use Twig Best Practices: Leverage Twig's features for cleaner templates.

{# Use conditionals and loops correctly #}
{% if content %}
  <div{{ attributes.addClass('content-wrapper') }}>
    {# Filter out empty fields using Twig's filter #}
    {% for key, item in content|without('field_to_filter') if item|render %}
      {{ item }}
    {% endfor %}
  </div>
{% endif %}

6. Implement Preprocess Functions Judiciously: Add variables in preprocess, not directly in templates.

/**
 * Implements hook_preprocess_HOOK() for paragraph templates.
 */
function mymodule_preprocess_paragraph(&$variables) {
  $paragraph = $variables['paragraph'];
  
  // Calculate complex values once in preprocess, not in template.
  $variables['is_expanded'] = FALSE;
  
  if ($paragraph->hasField('field_expand') && 
      $paragraph->field_expand->value == 1) {
    $variables['is_expanded'] = TRUE;
  }
  
  // Add needed services or complex processing.
  $variables['formatted_date'] = \Drupal::service('date.formatter')
    ->format($paragraph->created->value, 'custom', 'M d, Y');
}

7. Avoid Render Arrays in Templates: Templates should only access variables, not build complex structures.

{# Good: Access preprocessed variables #}
{% if is_featured %}
  <div class="featured-badge">{{ 'Featured'|t }}</div>
{% endif %}

{# Avoid: Complex logic in templates #}
{% if content.field_featured[0]['#markup'] == '1' %}
  <div class="featured-badge">{{ 'Featured'|t }}</div>
{% endif %}

The Theme System is Drupal's presentation layer, translating data from the application layer into a visual interface. Understanding its architecture and patterns allows you to create clean, maintainable code that properly separates concerns and leverages Drupal's caching system.

views-module.md

Drupal Views Module

Tags: Module, Core, Query Builder, Display System, UI

High-Level Overview

The Views module is Drupal's powerful query builder and display system that allows site builders and developers to create custom lists, tables, grids, blocks, pages, feeds, and other output formats from any data source, primarily the entity system. It provides a flexible, extensible architecture for building complex data queries through a user interface or programmatically, with fine-grained control over filtering, sorting, relationships, contextual arguments, and output formatting.

Purpose in Drupal Architecture

The Views module serves as a critical data retrieval and presentation layer by:

1. Providing a standardized, reusable query building interface
2. Exposing entity data through a unified API
3. Creating custom displays without requiring custom code
4. Supporting multiple output formats for the same data
5. Enabling complex filtering, sorting, and contextual display
6. Integrating with Drupal's caching and access control systems
7. Allowing extension through plugins for every aspect of functionality
8. Powering many of Drupal's administrative interfaces

As one of Drupal's most widely used modules, Views bridges the gap between stored data and its presentation, enabling complex data visualization without requiring PHP coding skills.

Hierarchical Breakdown

1. Views Core Components

• ViewsData: Metadata about data sources for querying
• ViewExecutable: Runtime view execution engine
• View Entity: Configuration entity storing view definitions
• ViewUI: Administrative interface for building views
• ViewsQuery: Query object for building database queries
• ViewsStorage: Handles loading and saving view definitions
• ViewsResultRow: Object representing a single result row

2. Plugin Types

• Display: Output format and context (page, block, etc.)
• Style: Presentation style (table, list, grid, etc.)
• Row: How each result row is rendered
• Field: Individual pieces of data from the data source
• Filter: Criteria for limiting result set
• Sort: Ordering of results
• Argument: Contextual parameters from URL or context
• Relationship: Joins between data sources
• Access: Permissions for viewing the display
• Exposed Form: UI form for user-controlled filtering
• Pager: Pagination of results
• Cache: Caching strategies for queries and rendering
• Query: Database abstraction layer
• Area: Header, footer, and empty text handlers

3. Data Sources

• Entities: Primary data source (nodes, users, etc.)
• Fields: Entity field data
• Configuration: Configuration entities
• External Data: Custom data sources via plugins
• Views: Views can use other views as data sources
• Custom Tables: Direct database table access

4. Extension Points

• Hooks: Alter hooks for modifying views behavior
• Plugin API: Creating new plugins for any component
• Events: Events for views lifecycle
• Dependencies: Integration with other subsystems
• Templates: Theme overrides for views output
• Contextual Filters: Dynamic filtering based on context
• Relationships: Extending data through joins

Concrete Examples

1. Creating a Simple View Programmatically

use Drupal\views\Entity\View;

// Create a new view configuration entity.
$view = View::create([
  'id' => 'recent_content',
  'label' => 'Recent Content',
  'description' => 'Shows recent content items.',
  'base_table' => 'node_field_data',
  'base_field' => 'nid',
]);

// Add a page display.
$display = [
  'id' => 'page_1',
  'display_plugin' => 'page',
  'display_title' => 'Page',
  'display_options' => [
    'path' => 'recent-content',
    'fields' => [
      'title' => [
        'id' => 'title',
        'table' => 'node_field_data',
        'field' => 'title',
        'label' => 'Title',
        'entity_type' => 'node',
        'entity_field' => 'title',
      ],
      'created' => [
        'id' => 'created',
        'table' => 'node_field_data',
        'field' => 'created',
        'label' => 'Post date',
        'entity_type' => 'node',
        'entity_field' => 'created',
      ],
    ],
    'filters' => [
      'status' => [
        'id' => 'status',
        'table' => 'node_field_data',
        'field' => 'status',
        'value' => '1',
        'entity_type' => 'node',
        'entity_field' => 'status',
      ],
    ],
    'sorts' => [
      'created' => [
        'id' => 'created',
        'table' => 'node_field_data',
        'field' => 'created',
        'order' => 'DESC',
        'entity_type' => 'node',
        'entity_field' => 'created',
      ],
    ],
    'pager' => [
      'type' => 'full',
      'options' => [
        'items_per_page' => 10,
      ],
    ],
  ],
];

$view->addDisplay('page', 'Page', $display['display_options']);
$view->save();

2. Executing a View Programmatically

// Load a view and execute it.
$view = \Drupal::entityTypeManager()->getStorage('view')->load('recent_content');
$view_executable = \Drupal::service('views.executable')->get($view);
$view_executable->setDisplay('page_1');

// Set contextual filters (arguments) if needed.
$args = ['article'];  // Filter by content type.
$view_executable->setArguments($args);

// Execute the view.
$view_executable->execute();

// Get the results.
$results = $view_executable->result;
$render = $view_executable->render();

// Access individual result rows.
foreach ($view_executable->result as $row) {
  $nid = $row->nid;
  $node = \Drupal\node\Entity\Node::load($nid);
  // Process the node.
}

3. Implementing a Custom Views Field Plugin

namespace Drupal\my_module\Plugin\views\field;

use Drupal\Core\Form\FormStateInterface;
use Drupal\views\Plugin\views\field\FieldPluginBase;
use Drupal\views\ResultRow;

/**
 * Field handler to show a custom calculated value.
 *
 * @ingroup views_field_handlers
 *
 * @ViewsField("my_custom_field")
 */
class MyCustomField extends FieldPluginBase {

  /**
   * {@inheritdoc}
   */
  public function query() {
    // This example adds no queries, but could.
  }

  /**
   * {@inheritdoc}
   */
  protected function defineOptions() {
    $options = parent::defineOptions();
    $options['calculation_type'] = ['default' => 'simple'];
    return $options;
  }

  /**
   * {@inheritdoc}
   */
  public function buildOptionsForm(&$form, FormStateInterface $form_state) {
    $form['calculation_type'] = [
      '#type' => 'select',
      '#title' => $this->t('Calculation type'),
      '#options' => [
        'simple' => $this->t('Simple'),
        'complex' => $this->t('Complex'),
      ],
      '#default_value' => $this->options['calculation_type'],
    ];

    parent::buildOptionsForm($form, $form_state);
  }

  /**
   * {@inheritdoc}
   */
  public function render(ResultRow $values) {
    // Get data from another field in this result.
    $entity = $this->getEntity($values);
    
    // Perform a calculation.
    if ($this->options['calculation_type'] == 'complex') {
      // Implement complex logic.
      $result = $this->calculateComplex($entity);
    }
    else {
      // Implement simple logic.
      $result = $this->calculateSimple($entity);
    }
    
    return $this->sanitizeValue($result);
  }

  /**
   * Calculate simple value.
   */
  protected function calculateSimple($entity) {
    // Example calculation.
    return 'Simple: ' . $entity->id();
  }

  /**
   * Calculate complex value.
   */
  protected function calculateComplex($entity) {
    // Example calculation.
    return 'Complex: ' . ($entity->id() * 2);
  }
}

4. Altering Existing Views

/**
 * Implements hook_views_pre_view().
 */
function mymodule_views_pre_view(\Drupal\views\ViewExecutable $view, $display_id, array &$args) {
  // Target a specific view and display.
  if ($view->id() == 'user_admin_people' && $display_id == 'page_1') {
    // Add a default filter value.
    $view->setExposedInput(['status' => 1]);
  }
}

/**
 * Implements hook_views_data_alter().
 */
function mymodule_views_data_alter(array &$data) {
  // Add a custom field to the node table.
  $data['node_field_data']['my_custom_field'] = [
    'title' => t('My custom field'),
    'help' => t('Provides a custom calculated field.'),
    'field' => [
      'id' => 'my_custom_field',
    ],
  ];
}

/**
 * Implements hook_views_query_alter().
 */
function mymodule_views_query_alter(\Drupal\views\ViewExecutable $view, \Drupal\views\Plugin\views\query\QueryPluginBase $query) {
  if ($view->id() == 'content' && $view->current_display == 'page_1') {
    // Add a custom WHERE condition.
    $query->addWhere('AND', 'node_field_data.created', time() - 86400, '>');
  }
}

5. Creating a View Template Override

{# templates/views-view--recent-content--page-1.html.twig #}
{# Override the template for a specific view and display #}

{% if header %}
  <header class="custom-view-header">
    {{ header }}
  </header>
{% endif %}

{% if rows %}
  <div class="custom-view-content">
    {{ rows }}
  </div>
{% elseif empty %}
  <div class="custom-view-empty">
    {{ empty }}
  </div>
{% endif %}

{% if footer %}
  <footer class="custom-view-footer">
    {{ footer }}
  </footer>
{% endif %}

{% if pager %}
  {{ pager }}
{% endif %}

Relationships to Other Components

• Entity API: Views primarily displays entity data
• Field API: Fields are exposed as Views fields
• Database API: Views uses the database abstraction layer
• Plugin API: Views is built on the plugin architecture
• Form API: Used for exposed filters and settings forms
• Theme System: Integrates with theming for output
• Cache API: Views implements cache handlers
• Access Control: Uses entity access for row-level access
• Block System: Views blocks can be placed in regions
• Menu System: Page displays integrate with routing
• Configuration System: Views are config entities

Common Patterns and Edge Cases

Common Patterns

• Content Listing: Displaying content with filtering
• User Administration: Managing user accounts
• Custom Admin Pages: Specialized administrative interfaces
• Block Views: Displaying related content in blocks
• Contextual Displays: Context-aware content displays
• Relationships: Joining data from multiple sources
• Exposed Filters: User-controllable filtering
• Content Feeds: Generating RSS or JSON feeds
• Data Tables: Sortable, filterable data tables
• Entity Reference Views: Selecting related content

Edge Cases

• Performance Tuning: Optimizing complex queries
• Large Result Sets: Handling thousands of results
• Multiple Relationships: Managing complex data joins
• Custom Data Sources: Non-entity data in Views
• Aggregation: Grouping and calculated fields
• Query Alterations: Modifying the underlying query
• Access Control Edge Cases: Row-level permissions
• AJAX Updating: Dynamic view reloading
• Contextual Filter Validation: Handling invalid arguments
• Empty Results Behavior: Customizing empty displays

Concept Map

                            ┌─────────────────┐
                            │   Views Module  │
                            └────────┬────────┘
                                     │
     ┌───────────────────────┬──────┼──────┬────────────────────────┐
     │                       │      │      │                        │
┌────▼─────────┐   ┌─────────▼───┐  │  ┌───▼────────┐     ┌─────────▼────┐
│View Entity   │   │ViewExecutable│  │  │Plugin Types│     │ViewsData     │
└────┬─────────┘   └─────────┬───┘  │  └───┬────────┘     └──────────────┘
     │                       │      │      │
┌────▼─────────┐   ┌─────────▼───┐  │  ┌───▼────────┐
│Configuration │   │Query Builder│  │  │  Display   │
└──────────────┘   └─────────────┘  │  └───┬────────┘
                                    │      │
                            ┌───────▼────┐ │ ┌───────────┐
                            │Results     │ └─►   Style   │
                            └───┬────────┘   └───┬───────┘
                                │              ┌─▼─┬─────────┐
                          ┌─────▼──────┐ ┌─────▼───▼───┬─────────┐
                          │Row Plugins │ │Field│Filter │ Sort    │
                          └────────────┘ └─────┴───────┴─────────┘

Quick Reference

• Primary Entity Type:

  • view: Configuration entity for storing view definitions

• Primary Classes:

  • \Drupal\views\ViewExecutable: Runtime view execution
  • \Drupal\views\Entity\View: Configuration entity for views
  • \Drupal\views\Plugin\views\query\Sql: SQL query builder
  • \Drupal\views\ViewsData: Metadata for queryable fields

• Key Services:

  • views.executable: Factory for ViewExecutable objects
  • views.views_data: Access to views data definitions
  • entity_type.manager->getStorage('view'): View storage handler
  • plugin.manager.views.display: Display plugin manager
  • plugin.manager.views.style: Style plugin manager

• Important Hooks:

  • hook_views_data(): Define data for Views to use
  • hook_views_data_alter(): Modify views data definitions
  • hook_views_pre_view(): Act before a view executes
  • hook_views_pre_build(): Act before a view builds
  • hook_views_pre_execute(): Act before query execution
  • hook_views_post_execute(): Act after query execution
  • hook_views_pre_render(): Act before rendering
  • hook_views_post_render(): Act after rendering

• Plugin Annotation/Attribute Examples:

  • @ViewsField: Field handler plugin
  • @ViewsFilter: Filter plugin
  • @ViewsSort: Sort plugin
  • @ViewsDisplay: Display plugin
  • @ViewsStyle: Style plugin
  • @ViewsRow: Row plugin

AI Recommendation

When working with Drupal's Views module, consider these approaches:

1. Use the UI for Rapid Development, Code for Version Control: Create views through the UI initially, then export the configuration for version control.

// Export a view to get its configuration structure
$view = \Drupal::entityTypeManager()->getStorage('view')->load('my_view');
$view_config = $view->toArray();
print_r($view_config);

2. Implement Views Hooks for Minor Alterations: Use hooks to make targeted changes to existing views.

/**
 * Implements hook_views_pre_render().
 */
function mymodule_views_pre_render(\Drupal\views\ViewExecutable $view) {
  if ($view->id() == 'content_admin' && $view->current_display == 'page') {
    // Add a custom class to the view.
    $view->element['#attributes']['class'][] = 'custom-admin-view';
    
    // Add custom text to the header.
    $view->header['area']->options['content']['value'] .= '<p>Additional information</p>';
  }
}

3. Create Custom Plugins for Significant New Functionality: When you need custom display logic, create custom plugins.

/**
 * Plugin implementation for a custom field.
 *
 * @ViewsField("custom_status")
 */
class CustomStatus extends FieldPluginBase {
  // Implementation details...
}

4. Use Views Contextual Filters with Validation: Handle contextual parameters securely.

// In a route controller, pass validated arguments to a view
$view = Views::getView('my_view');
if ($view) {
  // Set the display
  $view->setDisplay('block_1');
  
  // Set contextual filter arguments
  $validated_args = $this->validateArgs($request->query->all());
  $view->setArguments($validated_args);
  
  // Execute and render
  $output = $view->render();
  return $output;
}

5. Optimize Views Queries: For large datasets, optimize how Views queries the database.

/**
 * Implements hook_views_query_alter().
 */
function mymodule_views_query_alter(\Drupal\views\ViewExecutable $view, \Drupal\views\Plugin\views\query\QueryPluginBase $query) {
  if ($view->id() == 'large_content_list') {
    // Add a more specific condition to improve performance
    $query->addWhere(0, 'node_field_data.status', 1);
    
    // Add a more efficient table join
    $definition = [
      'table' => 'node__field_category',
      'field' => 'entity_id',
      'left_table' => 'node_field_data',
      'left_field' => 'nid',
    ];
    $join = Drupal::service('plugin.manager.views.join')
      ->createInstance('standard', $definition);
    $query->addRelationship('node__field_category', $join, 'node_field_data');
  }
}

6. Use Relationships Judiciously: Relationships add complexity and can impact performance.

// When programming Views, add relationships carefully
$view->addRelationship(
  'uid', 
  'standard', 
  'node_field_data', 
  ['id' => 'standard', 'field' => 'uid', 'table' => 'node_field_data']
);

7. Expose Views Data for Custom Entities: Make your custom entities available to Views.

/**
 * Implements hook_views_data().
 */
function mymodule_views_data() {
  $data = [];
  
  // Define a base table for the entity
  $data['my_entity'] = [
    'table' => [
      'group' => t('My Entity'),
      'provider' => 'my_module',
      'base' => [
        'title' => t('My Entity'),
        'help' => t('Data from my custom entity.'),
        'field' => 'id',
      ],
    ],
  ];
  
  // Define fields
  $data['my_entity']['id'] = [
    'title' => t('ID'),
    'help' => t('The unique identifier.'),
    'field' => [
      'id' => 'numeric',
    ],
    'sort' => [
      'id' => 'standard',
    ],
    'filter' => [
      'id' => 'numeric',
    ],
    'argument' => [
      'id' => 'numeric',
    ],
  ];
  
  return $data;
}

The Views module is one of Drupal's most powerful features, acting as both a query builder and a display system. Understanding its architecture allows you to create highly flexible and customized data displays while maintaining performance and security.