Building the Future: A Practical Guide to Drupal 11.2 Custom Entity Development

Drupal 11.2.x isn’t just “another point release.” It’s the moment where modern Drupal expectations harden:

• PHP 8.3+ is the baseline.
• OO hooks with attributes replace traditional .module hook implementations.
• Validation constraints provide better UX than throwing exceptions.
• SDC is a first-class theming workflow.
• Proper caching strategies are essential for time-based content.

This tutorial builds Promo Kit (promo_kit)—a complete custom content entity module with modern Drupal 11.2 architecture:

✅ Custom Content Entity (promo_kit_promo) with full CRUD operations

✅ Base Fields (image/link/date range/style) defined in code

✅ PromoManager Service (query-based filtering for active promos)

✅ Block Plugin (displays active promos with smart caching)

✅ Validation Constraints (proper form validation UX)

✅ OO Hooks (modern attribute-based hook implementations)

✅ SDC Theming (Single Directory Components for frontend)

0. What We’re Building

Requirement

Marketers need Promo Banners that appear on the site.

• Fields: Label, Description, Banner Image, Link, Style (Alert/Info/Party), Schedule (Start/End date range)
• Logic: Promo is active if:
  • status = published (enabled)
  • start is empty or start ≤ now
  • end is empty or end > now
• Frontend: Rendered by a dedicated Single Directory Component (SDC)
• Validation: End date cannot be before start date (validated via constraint)

Architecture

• Custom Content Entity: promo_kit_promo (not Block Content)
• Base Fields: Defined in Promo::baseFieldDefinitions()
• PromoManager Service: Handles active promo queries with proper date filtering
• Block Plugin: PromoBannerBlock displays active promos
• Validation Constraint: PromoDateRangeConstraint validates date logic
• OO Hooks: PromoHooks class for entity presave validation
• SDC Component: promo_banner for theming

1. Environment: Strict & Modern Drupal 11 (PHP 8.3+)

Drupal 11 is strict about modern PHP. If your local stack is “close enough,” it’s not enough.

Install DDEV (Homebrew)

Create the Drupal 11 project

2. Promo Kit Module: Scaffold

Generate the module:

Use prompts like:

• Module name: Promo Kit
• Machine name: promo_kit
• Description: Manages promotional banners with SDC integration.
• Dependencies: datetime_range, link, file
• Create .module file? Yes (we’ll use it for theme hooks)
• Create install file? Yes (optional)

Edit web/modules/custom/promo_kit/promo_kit.info.yml:

3. Custom Content Entity: Promo Banner

Create the entity class:

web/modules/custom/promo_kit/src/Entity/Promo.php

This entity extends EditorialContentEntityBase which provides:

• Revisions
• Publishing workflow (status field)
• Translation support
• Moderation integration

Key features:

• Entity ID: promo_kit_promo (prefixed to avoid collisions)
• Base Fields: label, status, description, date_range, link, image, style
• Tables: promo_kit_promo, promo_kit_promo_field_data, promo_kit_promo_revision, promo_kit_promo_field_revision

The entity uses PHP 8 attributes for configuration:

Base Fields include:

• label: Title/name of the promo
• status: Published/unpublished
• description: Long text description
• promo_date_range: Daterange field (start/end)
• promo_link: Link field
• promo_image: Image field
• promo_style: List field (info/alert/party)
• uid: Owner reference
• created/changed: Timestamps

4. PromoManager Service: Smart Query-Based Filtering

Create the service:

web/modules/custom/promo_kit/src/PromoManager.php

This service provides:

4.1 getActivePromos() Method

Returns active promos by pushing date filtering into the entity query (not loading all and filtering in PHP):

Key points:

• Uses UTC timezone (Drupal stores dates in UTC)
• Builds complex query conditions for date ranges
• Handles empty date fields (always active if no dates set)
• Scalable: filters at database level, not in PHP

4.2 getSecondsUntilNextBoundary() Method

Calculates dynamic cache max-age based on when the next promo starts or ends:

This ensures the block cache expires at the right time when promo visibility changes.

Register the service in promo_kit.services.yml:

5. Block Plugin: Display Active Promos

Create the block plugin:

web/modules/custom/promo_kit/src/Plugin/Block/PromoBannerBlock.php

This block:

• Injects PromoManager and EntityTypeManagerInterface
• Calls $this->promoManager->getActivePromos()
• Renders each promo using the view builder
• Implements proper caching:
• Cache tags: promo_kit_promo_list (invalidates when any promo changes)
• Cache contexts: user.permissions (access checking affects results)
• Cache max-age: Dynamic based on next boundary

6. Validation Constraint: Date Range Logic

Instead of throwing exceptions in presave (which causes white screens), use a validation constraint for proper form error display.

6.1 Constraint Plugin

web/modules/custom/promo_kit/src/Plugin/Validation/Constraint/PromoDateRangeConstraint.php

6.2 Constraint Validator

web/modules/custom/promo_kit/src/Plugin/Validation/Constraint/PromoDateRangeConstraintValidator.php

6.3 Attach Constraint to Entity

The constraint is attached at the entity level (type: entity:promo_kit_promo), so it validates automatically during entity validation.

For field-level constraints, you would use hook_entity_bundle_field_info_alter() to attach the constraint to a specific field.

7. OO Hooks: Modern Drupal 11.2 Approach

Create the hook class:

web/modules/custom/promo_kit/src/Hook/PromoHooks.php

Note: This presave validation is a backup. The constraint provides better UX by showing form errors. The presave hook catches any programmatic saves that bypass form validation.

After adding hook classes, clear cache:

8. Frontend: Single Directory Components (SDC)

Create the component structure:

8.1 Component Definition

web/modules/custom/promo_kit/components/promo_banner/promo_banner.component.yml

8.2 Component Template

web/modules/custom/promo_kit/components/promo_banner/promo_banner.twig

8.3 Component Styles

web/modules/custom/promo_kit/components/promo_banner/promo_banner.css

9. Connect Entity Output to SDC

9.1 Theme Hook

Register the theme hook in promo_kit.module:

9.2 Entity Template

web/modules/custom/promo_kit/templates/promo-kit-promo.html.twig

10. Permissions and Routes

10.1 Permissions

promo_kit.permissions.yml

10.2 Routes

promo_kit.routing.yml

The entity routes (add, edit, delete, list) are automatically generated by the AdminHtmlRouteProvider specified in the entity annotation.

11. Enable and Use

Enable the module:

11.1 Create Promos

Go to: /admin/content/promo/add

Example values:

• Label: “Summer Sale 2025”
• Description: “Get 50% off all products!”
• Date Range: Start today, end in 30 days
• Link: https://example.com/sale
• Style: party
• Banner Image: Upload an image
• Status: Enabled

11.2 Place the Block

Go to: /admin/structure/block

• Click “Place block”
• Find “Promo Banners” (from Promo Kit category)
• Place in desired region (e.g., Header, Content)
• Configure visibility settings if needed
• Save

The block will automatically display only active promos based on the current date/time.

12. Comprehensive Testing Checklist

12.1 Promo CRUD Operations

12.2 Schedule Logic

12.3 Validation

12.4 Style Variants

12.5 Block Display

13. Advanced: Cache Strategy Deep Dive

The module implements a sophisticated caching strategy for time-based content:

13.1 Cache Tags

The promo_kit_promo_list tag is automatically invalidated when:

• Any promo is created
• Any promo is updated
• Any promo is deleted

This ensures the block updates immediately when content changes.

13.2 Cache Contexts

The user.permissions context ensures different users see appropriate content based on their access permissions.

13.3 Dynamic Cache Max-Age

Instead of a fixed cache duration (e.g., 1 hour), the block calculates when the next promo will start or end, and sets the cache to expire at that exact moment.

Example:

• Current time: 2:00 PM
• Promo A ends: 2:30 PM
• Promo B starts: 3:00 PM
• Cache max-age: 1800 seconds (30 minutes, until Promo A ends)

This ensures promos appear/disappear at the correct time without over-caching or under-caching.

14. Troubleshooting

“I don’t see SDC styling”

1. Confirm component files exist:
   • components/promo_banner/promo_banner.component.yml
   • components/promo_banner/promo_banner.twig
   • components/promo_banner/promo_banner.css
2. Clear cache:

1. Check template file name:
   • Must be: promo-kit-promo.html.twig
   • Location: templates/ directory

“Block shows expired promos”

1. Check promo date ranges in admin UI
2. Verify server timezone matches expected timezone
3. Clear cache:

1. Check PromoManager query logic in getActivePromos()

“Validation doesn’t trigger”

1. Confirm constraint files exist and are properly namespaced
2. Clear cache twice (plugin discovery can be sticky):

1. Check entity type in constraint annotation: type: ['entity:promo_kit_promo']

“Permission denied errors”

1. Grant appropriate permissions:
   • /admin/people/permissions
   • Search for “promo”
   • Grant permissions to appropriate roles
2. Clear cache:

15. What We Built (Architecture Summary)

Custom Content Entity

• Entity ID: promo_kit_promo
• Base class: EditorialContentEntityBase
• Features: Revisions, translations, publishing workflow
• Tables: 4 tables (base, field_data, revision, field_revision)

Service Layer

• PromoManager: Business logic for querying active promos
• Methods: getActivePromos(), getSecondsUntilNextBoundary()
• Benefits: Reusable, testable, query-based filtering

Block Plugin

• ID: promo_banner_block
• Features: Dependency injection, proper caching
• Caching: Tags, contexts, dynamic max-age

Validation

• Constraint: PromoDateRangeConstraint
• Validator: PromoDateRangeConstraintValidator
• UX: Form errors instead of exceptions

OO Hooks

• Class: PromoHooks
• Hook: entity_presave with #[Hook] attribute
• Purpose: Backup validation for programmatic saves

SDC Theming

• Component: promo_banner
• Files: component.yml, twig, css
• Integration: Entity template includes SDC component

16. When to Use Custom Entities vs. Block Content

Use Custom Entities When:

• You need custom storage/query logic
• You have complex business rules
• You need custom routes/UI
• You want full control over the data model
• You’re building a domain-specific content type

Use Block Content When:

• You need simple reusable content blocks
• Core Block Content features are sufficient
• You want to leverage Views for display
• You don’t need custom query logic
• You want less code to maintain

Promo Kit uses a custom entity because:

• We need custom query logic for date-based filtering
• We want a dedicated service layer (PromoManager)
• We have specific caching requirements
• We want full control over the entity structure

Conclusion

We built Promo Kit using modern Drupal 11.2 best practices:

1. Custom Content Entity with proper prefixing (promo_kit_promo)
2. Service Layer (PromoManager) for business logic
3. Query-based filtering (scalable, not loading all entities)
4. Block Plugin with proper dependency injection
5. Sophisticated caching (tags, contexts, dynamic max-age)
6. Validation Constraints (proper UX)
7. OO Hooks (modern attribute-based approach)
8. SDC Theming (component-based frontend)

This architecture is production-ready, maintainable, and follows Drupal 11.2 conventions. The module demonstrates how to build custom entities the right way—with proper separation of concerns, testable code, and excellent performance.

17. Additional Module Components

17.1 Access Control Handler

web/modules/custom/promo_kit/src/PromoAccessControlHandler.php

The access control handler manages permissions for promo entities:

• View access: Requires view promo_kit_promo permission (and entity must be published)
• Create access: Requires create promo_kit_promo permission
• Update access: Requires edit promo_kit_promo permission
• Delete access: Requires delete promo_kit_promo permission
• Admin access: administer promo_kit_promo bypasses all checks

17.2 List Builder

web/modules/custom/promo_kit/src/PromoListBuilder.php

Provides the admin listing page at /admin/content/promo:

• Displays all promos in a table
• Shows label, status, author, created date
• Provides edit/delete operation links
• Supports bulk operations

17.3 Form Classes

PromoForm (src/Form/PromoForm.php)

• Add/edit form for promo entities
• Handles field widgets
• Validates input
• Saves entity

PromoSettingsForm (src/Form/PromoSettingsForm.php)

• Configuration form for promo entity type
• Accessible at /admin/structure/promo-kit-promo
• Allows field management via Field UI

17.4 View Builder

web/modules/custom/promo_kit/src/PromoViewBuilder.php

Renders promo entities:

• Builds render arrays for display
• Applies view modes
• Integrates with theme system
• Handles field formatters

17.5 User Integration Hooks

In promo_kit.module, we handle user account operations:

hook_user_cancel()

• user_cancel_block_unpublish: Unpublishes user’s promos
• user_cancel_reassign: Reassigns promos to anonymous user

hook_user_predelete()

• Deletes all promos owned by the user
• Deletes all promo revisions owned by the user

This ensures data integrity when user accounts are deleted.

18. Configuration Management

18.1 Exporting Configuration

If you add fields via Field UI (not base fields), export them:

18.2 Shipping Default Configuration

Copy relevant YAML files from config/sync/ to config/install/:

The module currently ships with minimal config (just action configs for bulk operations).

18.3 Config vs. Base Fields

Base Fields (what we use):

• Defined in code (baseFieldDefinitions())
• Always present, can’t be deleted via UI
• Portable across environments
• Version controlled in code

Config Fields (alternative):

• Defined via Field UI
• Stored as YAML configuration
• Can be added/removed via UI
• Requires config management for portability

Promo Kit uses base fields because:

• The field structure is fixed (not site-builder configurable)
• We want guaranteed field presence
• We want code-based version control
• We don’t need per-site field customization

19. Testing Strategies

19.1 Manual Testing Checklist

✅ Entity CRUD

• Create promo with all fields
• Edit promo, change values
• Delete promo
• View promo list at /admin/content/promo

✅ Date Logic

• Create promo with no dates (should always show)
• Create promo with future start (should hide until start)
• Create promo with past end (should hide)
• Create promo with active range (should show)

✅ Validation

• Try to save promo with end before start (should show error)
• Save promo with valid dates (should succeed)

✅ Block Display

• Place block in region
• Verify only active promos display
• Disable a promo, verify it disappears
• Create new promo, verify it appears

✅ Caching

• Edit promo, verify block updates immediately
• Wait for promo to expire, verify it disappears (may take up to cache max-age)

✅ Permissions

• Test as anonymous user (should not see admin pages)
• Test as authenticated user with view permission (should see promos)
• Test as admin (should see everything)

19.2 Automated Testing (Optional)

For production modules, consider adding:

Unit Tests

• Test PromoManager logic
• Test date calculations
• Test constraint validator

Kernel Tests

• Test entity CRUD operations
• Test query logic
• Test access control

Functional Tests

• Test form submission
• Test block display
• Test permissions

Example test structure:

20. Performance Considerations

20.1 Query Optimization

The PromoManager uses entity queries with conditions, not loading all entities:

✅ Good (what we do):

❌ Bad (don’t do this):

20.2 Caching Strategy

The block implements three caching dimensions:

1. Cache Tags: Invalidate when content changes
2. Cache Contexts: Vary by user permissions
3. Cache Max-Age: Expire at next boundary

This ensures:

• Fresh content when promos are edited
• Correct content for different users
• Timely updates when promos expire/activate

20.3 Database Indexes

The entity automatically gets indexes on:

• id (primary key)
• uuid (unique)
• revision_id
• langcode
• status

For high-traffic sites with many promos, consider adding custom indexes on:

• promo_date_range.value (start date)
• promo_date_range.end_value (end date)

This can be done in a hook_schema_alter() or update hook.

21. Extending the Module

21.1 Adding a Weight Field

To control display order:

1. Add base field in Promo::baseFieldDefinitions():

1. Update PromoManager query:

21.2 Adding Categories/Tags

To categorize promos:

1. Add entity reference field:

1. Create taxonomy vocabulary promo_categories
2. Update block to filter by category (add block configuration)

21.3 Adding View Modes

To support different display styles:

1. Create view mode via UI or config:
   • /admin/structure/display-modes/view/add/promo_kit_promo
2. Configure fields for the view mode:
   • /admin/structure/promo-kit-promo/display/[view_mode]
3. Use in block:

21.4 Adding REST API Support

To expose promos via REST:

1. Add dependency in promo_kit.info.yml:

1. Enable REST resource:

1. Configure REST resource for promo_kit_promo entity type
2. Access via: /promo_kit_promo/{id}?_format=json

22. Deployment Checklist

22.1 Pre-Deployment

✅ Test on staging environment ✅ Verify all promos display correctly ✅ Test date-based visibility ✅ Test validation constraints ✅ Test permissions for all roles ✅ Verify caching behavior ✅ Check performance with realistic data volume

22.2 Deployment Steps

1. Enable module:

1. Clear cache:

1. Import configuration (if using config management):

1. Run update hooks (if any):

1. Verify permissions:

1. Place block (if not in config):
   • Via UI: /admin/structure/block
   • Or via Drush: drush block:place promo_banner_block

22.3 Post-Deployment

✅ Verify block appears on frontend ✅ Create test promo and verify it displays ✅ Check error logs for any issues ✅ Monitor performance ✅ Train content editors on creating promos

23. Common Pitfalls and Solutions

Pitfall 1: Forgetting accessCheck()

❌ Error:

✅ Solution:

Pitfall 2: Timezone Issues

❌ Problem: Dates don’t match expected behavior

✅ Solution: Always use UTC for date comparisons:

Pitfall 3: Cache Not Invalidating

❌ Problem: Block shows stale data after editing promo

✅ Solution: Ensure cache tags are correct:

Pitfall 4: Validation Not Working

❌ Problem: Constraint doesn’t trigger

✅ Solution: Clear cache twice (plugin discovery):

Pitfall 5: Template Not Found

❌ Problem: “Template not found” error

✅ Solution: Check file name matches theme hook:

• Hook: promo_kit_promo
• Template: promo-kit-promo.html.twig (underscores become hyphens)

24. Resources and Further Reading

Official Drupal Documentation

• Content Entity API
• Plugin API
• Validation API
• Cache API
• Single Directory Components

Drupal 11 Specific

• PHP 8.3 Compatibility
• OO Hooks with Attributes
• Drupal 11 Release Notes

Development Tools

• DDEV Documentation
• Drush Commands
• Drupal Code Generator

Appendix A: Complete File Structure

Appendix B: Key Drupal 11.2 Patterns Used

1. PHP 8 Attributes for Entity Definition

2. OO Hooks with Attributes

3. Validation Constraints

4. Constructor Property Promotion

5. Typed Properties

6. Readonly Properties

7. Mixed Type Hints

These patterns are all PHP 8.3+ features that Drupal 11.2 embraces fully.

End of Tutorial

You now have a complete, production-ready Drupal 11.2 module that demonstrates modern development practices. The Promo Kit module showcases custom entities, service layers, validation, caching, OO hooks, and SDC theming—all the tools you need to build sophisticated Drupal applications.