espocrm

EspoCRM の開発

概要

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

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

EspoCRM のカスタムモジュール、エンティティ、リレーションシップ、フック、サービス、API エンドポイント、インテグレーションを開発するときに有効にしてください。特に次の作業で使用してください： ORM を使用する（EntityManager が必須）、ビジネスロジックを実装する（サービスに実装する）、フックを作成する（インターフェースを使用する）、メタデータを変更する（キャッシュの再構築が必要）、カスタムフィールドタイプを作成する、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、ワークフロー、インテグレーションのパターン
• 拡張パッケージ：拡張機能のパッケージ化と配布 - マニフェストファイル、インストール、バージョン管理

品質保証

• テストとデバッグ：ユニットテスト、デバッグ手法、パフォーマンス最適化、よくある落とし穴
• PHP の品質アンチパターン：言語レベルの堅牢性／変更容易性に関する欠陥 — PHP4 のコンストラクター名、大文字の制御キーワード、goto、空の catch ブロックと、準拠した例（CAST Highlight のコード品質指標に基づく、https://doc.casthighlight.com/）

主要なパターン

正しいパターン：

✅ 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 の方法です。