Espocrm Development

EspoCRM Development

Overview

EspoCRM is a metadata-driven CRM platform where configuration lives in JSON files, business logic belongs in Services, and data access happens through ORM EntityManager. This skill enforces architectural patterns to prevent common mistakes like passing Container dependencies, bypassing the service layer, or implementing business logic in hooks.

When to Use This Skill

Activate when developing custom EspoCRM modules, entities, relationships, hooks, services, API endpoints, or integrations. Use especially when: working with ORM (EntityManager required), implementing business logic (belongs in Services), creating hooks (use interfaces), modifying metadata (requires cache rebuild), or building custom field types.

The Iron Law

BUSINESS LOGIC IN SERVICES, NOT HOOKS | DATA ACCESS VIA ENTITYMANAGER, NEVER DIRECT PDO | NEVER PASS CONTAINER AS DEPENDENCY

If you're accessing Container directly or writing business logic in hooks, you're violating architecture.

Core Architecture Principles

1. Metadata-Driven: Entity definitions, layouts, field configs live in JSON
2. Service Layer: All business logic implemented in Service classes
3. ORM EntityManager: Central access point for all database operations
4. Dependency Injection: Constructor injection, never pass Container
5. Hook System: Lifecycle events for validation and side effects (not business logic)
6. Repository Pattern: Entities accessed through repositories

Quick Start

1. Setup Development Environment - Use ext-template, work in src/ directory (EspoCRM 7.4+), understand metadata structure: custom/Espo/Modules/{ModuleName}/Resources/metadata/

2. Access Data with EntityManager

   use Espo\ORM\EntityManager;
   
   public function __construct(private EntityManager $entityManager) {}
   
   // Find entity
   $account = $this->entityManager->getEntityById('Account', $id);
   
   // Query with conditions
   $collection = $this->entityManager
       ->getRDBRepository('Contact')
       ->where(['accountId' => $accountId])
       ->find();

3. Implement Business Logic in Services

   namespace Espo\Modules\MyModule\Services;
   
   use Espo\Services\Record;
   
   class MyEntity extends Record {
       public function customAction(string $id, object $data): object {
           // Business logic here
           $entity = $this->entityManager->getEntityById($this->entityType, $id);
           // ... process ...
           $this->entityManager->saveEntity($entity);
           return $entity;
       }
   }

4. Register Hooks for Lifecycle Events

   namespace Espo\Modules\MyModule\Hooks\Account;
   
   use Espo\ORM\Entity;
   use Espo\Core\Hook\Hook\BeforeSave;
   
   class MyHook implements BeforeSave {
       public function beforeSave(Entity $entity, array $options): void {
           // Validation or side effects only
           if ($entity->isAttributeChanged('status')) {
               // React to changes
           }
       }
   }

5. Rebuild Cache After Changes

   bin/command rebuild

Hook Types (Interfaces)

EspoCRM provides 7 hook types - ALWAYS use interfaces: BeforeSave (validation before save), AfterSave (side effects after save), BeforeRemove (validation before delete), AfterRemove (cleanup after delete), AfterRelate (relationship creation), AfterUnrelate (relationship removal), AfterMassRelate (bulk relationship operations).