D'fflib
WHATFeatures

Trigger Framework

D'fflib comes with an extended trigger framework, enabling bulkified, scalable and maintainable trigger handlers.

Highlights & takeaways

D'fflib enforces one trigger per SObject, delegating all orchestration to the Domain class. Handlers are registered per trigger event, executed in a structured three-phase lifecycle (initialize → process → finalize), and share a single Unit of Work commit — keeping your trigger logic bulkified, testable, and free of scattered DML.

Main benefits

Simplified and standardised trigger initiation

Each trigger directly delegates to the Domain class with the one-liner dfflib_SObjectDomain.triggerHandler( [class] ).

Clearer handler separation and management

Handlers are centrally registered in the Domain constructor, defining execution order and event coverage. Encouraging trigger logic to be split to handlers with single- and clear responsibilities.

One Handler can be easily registered to multiple trigger events, encouraging reuse and avoiding duplicate code.

Bulkified architecture

Each handler follows a three-phase lifecycle:

  1. Single initialize() for preparing data in bulk (like queries and other loops)
  2. Per record process() allowing clean execution of the handler's main operation
  3. Single finalize() for concluding the logic and saving back to the database (in bulk)

This encourages bulkified handlers with no SOQL and DML inside loops and easy to understand and manage logic.

Built-in transaction management

All handlers share the same dfflib_ISObjectUnitOfWork instance injected by the framework. Work is registered across handlers and committed after all handlers have completed. This enables grouping records and eliminating repetitive DML round-trips and governor limit pressure.

Additionally, this simplifies testing and mocking, aside from centralised and built-in transaction management. Avoiding the need for Rollback and Exception handling scattered across the trigger.

Execution control

Handlers explicitly implement one or multiple TriggerEvent interfaces and opt. FireOnce to control execution. Ensuring records are only processed once per transaction and avoiding duplicate work across trigger events.

Isolated, independently testable handlers

Because each handler is a self-contained inner class with a clear interface, it can be instantiated and tested in isolation without firing the full trigger stack. This dramatically reduces test setup complexity.

Metadata-driven handler registration in progress

We're currently finalising the migration for Trigger Handler registrations from Domain constructor to metadata. Simplifying registration and giving more flexibility to enable/disable handlers without code changes.


What it brings

The Domain as trigger orchestrator

The trigger itself is a one-liner. It delegates immediately to the Domain class, which owns all orchestration:

trigger AccountsTrigger on Account (before insert, before update, before delete, after insert, after update, after delete, after undelete) {
    dfflib_SObjectDomain.triggerHandler(DOM_Accounts.class);
}

The Domain constructor is where handlers are registered. Each registerHandler call binds a TriggerEvent to a handler class:

public with sharing class DOM_Accounts extends dfflib_SObjectDomain implements IDomain {

    public DOM_Accounts(List<Account> records) {
        super(records, dfflib.unitOfWork.newInstance());

        registerHandler(TriggerEvent.AFTER_INSERT, SyncAccountToERP.class);
        registerHandler(TriggerEvent.AFTER_UPDATE, SyncAccountToERP.class);
    }

    public class Constructor implements dfflib_SObjectDomain.IConstructable {
        public dfflib_SObjectDomain construct(List<SObject> sObjectList) {
            return new DOM_Accounts(sObjectList);
        }
    }
}

See Domain setup for the full Domain class configuration.


Handler anatomy: initialize → process → finalize

Every handler extends BaseHandler and optionally overrides three lifecycle methods. The framework calls them in order for every trigger invocation:

public class CalculateTotalPrice extends BaseHandler implements BeforeInsert, BeforeUpdate{
    // Called once before record iteration — use for bulk queries and setup
    public override void initialize( TriggerState ts, dfflib_ISObjectUnitOfWork uow ){
        // e.g. pre-load related records from a selector
    }

    // Called once per record — no SOQL, no DML
    public override Boolean process( SObject current, SObject original, dfflib_ISObjectUnitOfWork uow ){
        RoomReservation__c newRecord = ( RoomReservation__c ) current;
        RoomReservation__c oldRecord = ( RoomReservation__c ) original;
        // register work on uow, return true if this record was processed
        return true;
    }

    // Called once after record iteration
    public override void finalize( TriggerState state, dfflib_ISObjectUnitOfWork uow ){
        // e.g. call Domain method, Log
    }
}

The process() return value feeds into FireOnce deduplication (see below). Returning true signals the record was handled; returning false leaves it eligible for re-processing in a subsequent trigger invocation.


TriggerState — bulk context across phases

A TriggerState instance is injected into both initialize() and finalize(). It acts as a shared context object for the handler's full lifecycle — allowing data loaded in initialize() (e.g. a map of related records) to be available in finalize() without passing it through process(). This keeps the per-record method signature clean while still supporting bulk patterns.

public class TriggerState{
    public final List<SObject> currentList;
    public final List<SObject> originalList;
}

FireOnce — smart deduplication

Handlers that implement FireOnce are only executed once per record per transaction. If process() returns true for a record, that record is skipped on any subsequent trigger invocation within the same transaction.

public class SyncAccountToERP extends BaseHandler implements FireOnce, AfterInsert, AfterUpdate {
    // ...
}

Trigger event coverage

Register handlers against any of the following TriggerEvent enum values:

Enum valueTrigger context
BEFORE_INSERTBefore insert
BEFORE_UPDATEBefore update
BEFORE_DELETEBefore delete
AFTER_INSERTAfter insert
AFTER_UPDATEAfter update
AFTER_DELETEAfter delete
AFTER_UNDELETEAfter undelete
ALLAll trigger events

Each enum value has a corresponding interface (BeforeInsert, AfterUpdate, AllEvents, etc.) that the handler implements to declare which events it responds to.


Except for the listed items, the content on this site is licensed under CC-BY-NC-4.0
and allows sharing, provided an appropriate credit and link to source.

On this page