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), building custom field types, creating complex queries with SelectBuilder, implementing custom API actions, or packaging extensions.

The Iron Law

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

Accessing Container directly or writing business logic in hooks violates architecture.

Core Architecture Principles

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

Quick Start

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

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();

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;
    }
}

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
        }
    }
}

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).

Navigation

Core Concepts

Architecture: Metadata system, ORM, DI container, repository pattern, and core architectural patterns
Development Workflow: Module creation, custom entities, fields, APIs, and extension development process
Hooks and Services: Service layer implementation, hook types, dependency injection, and business logic patterns

Advanced Topics

SelectBuilder: Advanced querying with SelectBuilder - complex queries, joins, aggregations, and query optimization
API Actions: Creating custom API endpoints - action handlers, request/response patterns, and authentication
Custom Field Types: Building custom field types - backend, frontend, metadata, and integration

UI and Integration

Frontend Customization: View system, client-side development, and UI customization
Common Tasks: Scheduled jobs, emails, PDFs, ACL, workflows, and integration patterns
Extension Packages: Packaging and distributing extensions - manifest files, installation, and versioning

Quality Assurance

Testing and Debugging: Unit tests, debugging techniques, performance optimization, and common pitfalls

Key Patterns

Correct Pattern:

✅ Service with injected dependencies
✅ EntityManager for data access
✅ Hooks using interfaces
✅ Type declarations on all methods
✅ Exceptions for error handling

Incorrect Patterns:

❌ Passing Container as dependency
❌ Direct PDO database access
❌ Business logic in hooks
❌ Hook base classes instead of interfaces
❌ Missing type declarations

Common Mistakes to Avoid

Never pass Container - Inject specific dependencies instead
Don't bypass EntityManager - Use ORM, not raw queries
Business logic doesn't belong in hooks - Use Services
Always rebuild cache - After metadata changes (bin/command rebuild)
Use interfaces for hooks - Not base classes
Type everything - PHP 7.4+ requires type declarations
Throw exceptions - Don't return booleans for errors

Integration with Other Skills

systematic-debugging: Debug EspoCRM issues using logs and step debugging
verification-before-completion: Always test with cache rebuild before claiming complete
test-driven-development: Write unit tests for Services and hooks

The Bottom Line

EspoCRM is metadata-driven with a service layer architecture.

Understand the metadata system. Use EntityManager for data. Implement business logic in Services. Use hooks for lifecycle events only. Rebuild cache after changes.

This is the EspoCRM way.

espocrm-development