AGENT SKILL

espocrm-development

Comprehensive guide for developing on EspoCRM - metadata-driven CRM with service layer architecture

License 许可
MIT
最近更新
2026-05-22
Stars
★ 0
Forks
0

01 前言 Front Matter

name
espocrm-development
tags
[ "espocrm", "php", "crm", "metadata-driven", "orm" ]
author
Claude MPM Team
license
MIT
version
1.0.0
category
development
description
Comprehensive guide for developing on EspoCRM - metadata-driven CRM with service layer architecture
context_limit
800
requires_tools
[]
progressive_disclosure
{ "references": [ "architecture.md", "development-workflow.md", "hooks-and-services.md", "frontend-customization.md", "common-tasks.md", "testing-debugging.md", "select-builder.md", "api-actions.md", "custom-field-types.md", "extension-packages.md" ], "entry_point": { "summary": "Metadata-driven CRM development using service layer, ORM EntityManager, and hook-based business logic", "quick_start": "1. Understand metadata-driven architecture 2. Use EntityManager for data access 3. Implement business logic in Services 4. Register hooks for lifecycle events 5. Rebuild cache after changes", "when_to_use": "When developing custom modules, entities, hooks, or integrations for EspoCRM" } }

02 资源文件 10

03 SKILL.md 正文

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

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

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

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.

04 同仓库更多 Skills

julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

simpy

Process-based discrete-event simulation framework in Python. Use this skill when building simulations of systems with processes, queues, resources, and time-based events such as manufacturing systems, service operations, network traffic, logistics, or any system where entities interact with shared resources over time.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

shopify-expert

Builds and debugs Shopify themes (.liquid files, theme.json, sections), develops custom Shopify apps (shopify.app.toml, OAuth, webhooks), and implements Storefront API integrations for headless storefronts. Use when building or customizing Shopify themes, creating Hydrogen or custom React storefronts, developing Shopify apps, implementing checkout UI extensions or Shopify Functions, optimizing performance, or integrating third-party services. Invoke for Liquid templating, Storefront API, app development, checkout customization, Shopify Plus features, App Bridge, Polaris, or Shopify CLI workflows.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

shap

Model interpretability and explainability using SHAP (SHapley Additive exPlanations). Use this skill when explaining machine learning model predictions, computing feature importance, generating SHAP plots (waterfall, beeswarm, bar, scatter, force, heatmap), debugging models, analyzing model bias or fairness, comparing models, or implementing explainable AI. Works with tree-based models (XGBoost, LightGBM, Random Forest), deep learning (TensorFlow, PyTorch), linear models, and any black-box model.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

shadcn-ui

Deep expertise on shadcn/ui component library including installation, customization, theming, and accessibility patterns. Use when building UI with shadcn/ui components, integrating Radix UI primitives, configuring Tailwind CSS v4 themes, or implementing dark mode. Covers Next.js App Router, Pages Router, and Vite setups.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

seoul-subway-arrival

Look up Seoul real-time subway arrival information with the official Seoul Open Data API. Use when the user asks when a train arrives, which trains are approaching a station, or how crowded Seoul subway timing looks right now.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

seo-optimization

Comprehensive 7-phase SEO optimization workflow covering technical SEO auditing, keyword research strategy, on-page optimization, content SEO and E-E-A-T, structured data implementation, link building, and AI search optimization. Use when auditing search engine visibility, diagnosing ranking issues, implementing schema markup, conducting keyword research, optimizing content for E-E-A-T signals, or adapting for AI-driven search (AI Overviews, SGE).

★ 0