espocrm-development

EspoCRM の開発

概要

EspoCRM は、設定が JSON ファイルに保存され、ビジネスロジックは Service に属し、データアクセスは ORM の EntityManager を介して行われる、メタデータ駆動型の CRM プラットフォームです。このスキルでは、Container の依存関係を渡す、サービスレイヤーを迂回する、フックにビジネスロジックを実装するといった、よくある間違いを防ぐためのアーキテクチャパターンを適用します。

このスキルを使用する場面

EspoCRM のカスタムモジュール、エンティティ、リレーションシップ、フック、サービス、API エンドポイント、インテグレーションを開発する際に有効にしてください。特に次の場合に使用してください： ORM を使用する場合（EntityManager が必須）、ビジネスロジックを実装する場合（Service に実装）、フックを作成する場合（インターフェースを使用）、メタデータを変更する場合（キャッシュの再構築が必要）、カスタムフィールドタイプを作成する場合、SelectBuilder で複雑なクエリを作成する場合、カスタム API アクションを実装する場合、または拡張機能をパッケージ化する場合。

絶対的な原則

ビジネスロジックはフックではなくサービスに実装 | データアクセスには必ず ENTITYMANAGER を使用し、PDO を直接使用しない | 依存関係として CONTAINER を渡さない

Container に直接アクセスしたり、フックにビジネスロジックを記述したりすることは、アーキテクチャ違反です。

アーキテクチャの基本原則

1. メタデータ駆動型：エンティティ定義、レイアウト、フィールド設定は JSON に保存されます
2. サービスレイヤー：すべてのビジネスロジックは Service クラスに実装します
3. ORM EntityManager：すべてのデータベース操作の一元的なアクセスポイントです
4. 依存性注入：コンストラクターインジェクションを使用し、Container は決して渡しません
5. フックシステム：検証と副作用のためのライフサイクルイベント（ビジネスロジックには使用しません）
6. リポジトリパターン：エンティティにはリポジトリを介してアクセスします

クイックスタート

1. 開発環境をセットアップする - ext-template を使用し、src/ ディレクトリで作業します（EspoCRM 7.4 以降）。メタデータの構造を把握します：custom/Espo/Modules/{ModuleName}/Resources/metadata/

2. 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. サービスにビジネスロジックを実装する

   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. ライフサイクルイベント用のフックを登録する

   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. 変更後にキャッシュを再構築する

   bin/command rebuild
   

フックの種類（インターフェース）

EspoCRM には 7 種類のフックがあります。必ずインターフェースを使用してください：BeforeSave（保存前の検証）、AfterSave（保存後の副作用）、BeforeRemove（削除前の検証）、AfterRemove（削除後のクリーンアップ）、AfterRelate（リレーションシップの作成）、AfterUnrelate（リレーションシップの削除）、AfterMassRelate（リレーションシップの一括操作）。

ナビゲーション

基本概念

• アーキテクチャ：メタデータシステム、ORM、DI コンテナー、リポジトリパターン、基本的なアーキテクチャパターン
• 開発ワークフロー：モジュールの作成、カスタムエンティティ、フィールド、API、拡張機能の開発プロセス
• フックとサービス：サービスレイヤーの実装、フックの種類、依存性注入、ビジネスロジックのパターン

高度なトピック

• SelectBuilder：SelectBuilder による高度なクエリ作成 - 複雑なクエリ、結合、集計、クエリの最適化
• API アクション：カスタム API エンドポイントの作成 - アクションハンドラー、リクエスト／レスポンスのパターン、認証
• カスタムフィールドタイプ：カスタムフィールドタイプの構築 - バックエンド、フロントエンド、メタデータ、インテグレーション

UI とインテグレーション

• フロントエンドのカスタマイズ：ビューシステム、クライアントサイド開発、UI のカスタマイズ
• 一般的なタスク：スケジュール済みジョブ、メール、PDF、ACL、ワークフロー、インテグレーションのパターン
• 拡張パッケージ：拡張機能のパッケージ化と配布 - マニフェストファイル、インストール、バージョン管理

品質保証

• テストとデバッグ：ユニットテスト、デバッグ手法、パフォーマンスの最適化、よくある落とし穴

重要なパターン

正しいパターン：

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

誤ったパターン：

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

避けるべきよくある間違い

• Container を渡さないでください - 代わりに具体的な依存関係を注入してください
• EntityManager を迂回しないでください - 生のクエリではなく、ORM を使用してください
• ビジネスロジックをフックに記述しないでください - サービスを使用してください
• 必ずキャッシュを再構築してください - メタデータを変更した後は実行します（bin/command rebuild）
• フックにはインターフェースを使用してください - 基底クラスは使用しないでください
• すべてに型を指定してください - PHP 7.4 以降では型宣言が必要です
• 例外をスローしてください - エラーを示すためにブール値を返さないでください

他のスキルとの連携

• systematic-debugging：ログとステップデバッグを使用して EspoCRM の問題をデバッグします
• verification-before-completion：完了を報告する前に、必ずキャッシュを再構築してテストします
• test-driven-development：サービスとフックのユニットテストを作成します

要点

EspoCRM は、サービスレイヤーアーキテクチャを採用したメタデータ駆動型のシステムです。

メタデータシステムを理解してください。データには EntityManager を使用してください。ビジネスロジックはサービスに実装してください。フックはライフサイクルイベントにのみ使用してください。変更後はキャッシュを再構築してください。

これが EspoCRM の流儀です。