espocrm_skill

Overview

This skill is a practical guide for developing on EspoCRM, a metadata-driven CRM with a service layer architecture. It codifies correct patterns for metadata, services, hooks, and ORM usage to prevent common architectural mistakes. Use it to enforce maintainable, testable extensions and integrations for EspoCRM.

How this skill works

The skill inspects development patterns and recommends concrete implementations: metadata placement in JSON, business logic inside Service classes, and all database operations via the EntityManager/ORM. It flags anti-patterns such as passing the DI container, using raw PDO, or embedding business logic in hooks, and it prescribes lifecycle hooks for validation and side effects. It also covers cache rebuilds after metadata changes and toolchain practices for module packaging.

When to use it

• When building custom modules, entities, relationships, or field types
• When implementing business logic or custom API actions
• When writing hooks that respond to lifecycle events (validation/side effects)
• When creating complex queries (use SelectBuilder/Repository instead of raw SQL)
• When packaging or deploying extensions and after changing metadata (rebuild cache)

Best practices

• Implement business rules in Services and inject dependencies via constructors
• Always use EntityManager or repositories for data access; avoid direct PDO
• Use hook interfaces for lifecycle events and keep hooks limited to validation/side effects
• Add type declarations on methods and throw exceptions for error handling
• Rebuild cache (bin/command rebuild) after any metadata changes
• Write unit tests for Services and use logging/debugging for troubleshooting

Example use cases

• Create a Service to implement a complex account merge operation with EntityManager access
• Register a BeforeSave hook to validate fields and delegate processing to a Service
• Implement a custom API action that invokes a Service and returns structured results
• Build a SelectBuilder query in a repository to optimize reports and aggregations
• Package an extension with metadata JSON, rebuild cache, and include migration steps