XOOPS uses the Data Mapper pattern, not Active Record. This is a crucial distinction that affects how you structure your module code.

In the Data Mapper pattern, the XoopsObject (Data Object) holds state but knows nothing about persistence. The XoopsPersistableObjectHandler (Mapper) handles all database operations.

XMF enhances both sides with traits:

• Data Object traits: ChangeTrackingTrait, SeoFieldsTrait, AuditTrailTrait
• Mapper traits: HandlerTrait, TreeHandlerTrait, TemporalQueryTrait

Never add $entity->save() — always use $handler->insert($entity).