DIBA PHP - 意図駆動型アーキテクチャのPHPフレームワークを開発しました。

PHPフレームワークは多く存在します。
- フルスタックな**Laravel**
- ライトウェイトな**CodeIgniter4**
- 堅牢な**Luminas**
- コンポーネント思考の**Yii2**
- 国産の**CakePHP**

など、どれも素晴らしいアーキテクチャを持つプロジェクトです。

そんなPHPフレームワークに憧れ、PHPをこよなく愛するPHPerが、新しい**デベロッパー・ファースト**なアーキテクチャのPHPフレームワークを開発してみました。

よろしければ、ご一読頂けますと幸いです。

# DIBA PHP
![diba-php.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/569001/0022f2f6-aaa0-49a2-b2bd-eba212fa0e01.png)

DIBA = **Declarative Intent Based Architecture**
「意図駆動型アーキテクチャ」を意味します。
意図駆動型は、開発者が「**何をしたいのか**」を中心に設計しています。

- GitHub: https://github.com/kn0ws/diba-php
- PHP 8.0 以上
- Composer対応 依存は軽量(現在はEloquent + Symfony/YAMLのみ)
- .env による設定切り替え、マルチDB対応
- Intent定義、Executor、レスポンス、バリデーション、サービス、テストなど、すべてが疎結合＆宣言的
- CLIによる雛形自動生成、テスト、Intent定義のMMD形式グラフ化、定義のバリデーションチェック

他にも様々な機能がありますが、今後も追加予定です。

# DIBA PHPのインストール手順
:::note warn
現時点では開発したてですので、バグが多いかもしれません。
ぜひ、コントリビューターとして参加いただき、成長にお力を貸していただけますと幸いです。
また、公式ドキュメントも現在制作中です。完成までお待ち下さい。
:::

```bash
git clone https://github.com/kn0ws/diba-php.git
cd diba-php
composer install
cp env.sample .env
php -S localhost:8080 -t public
```
## 動作確認
```bash
curl http://localhost:8080/welcome
```
以下のレスポンスが返ってきます。
```json
{
  "message": "Welcome to DIBA PHP!",
  "time": "2025-04-16 00:00:00"
}
```


## DIBA PHPのディレクトリ構造

```
app/
├── Constraints/     ← バリデーション
├── Executors/       ← 実行処理
├── Intents/         ← Intent定義 (YAML)
├── Models/          ← Eloquent ORM
├── Responses/       ← レスポンス形式
├── Services/        ← ビジネスロジック
├── Views/           ← ビューファイル
framework/           ← フレームワーク本体
config/
├── database.php      ← データベース接続設定ファイル
├── env.php           ← .env読み込み用
├── events.php        ← イベントログ収集設定
public/
├── index.php         ← エントリポイント
├── .htaccess         ← Apache用
cli/
├── diba.php           ← CLIコマンド実行用
├── migrate.php        ← DBマイグレーション用
stub/                  ← 自動生成用テンプレート集
tests/                 ← Intent テスト
logs/                  ← ログファイル類
vendor/                ← Composer依存ライブラリ (composer install時に生成)
```

## 開発手順

### 1. IntentをYAMLで定義
例えば、「ユーザー登録を実装したい」場合は、以下のようにIntentを作成します。

```yaml:app/intents/user.intents.yaml
UserRegisterHTML:
  intent: "ユーザー登録ページを表示"
  description: "ユーザー登録ページをHTML形式のViewでレスポンスする。"
  tags: [page, user, register, view] #タグは自由ですが、ページ(page)、user系の処理、登録(register)、Viewで返す というタグをつけています。CLIで検索可能になります。
  match:
    method: GET
    path: /user/register
  executors:
    - UserExecutor@registerForm # app/Executors/UserExecutor.php > registerFormメソッドを指定
  response: Responses\ViewResponse # ViewをHTML形式でレスポンス
  response_args:
    - "user_register.php" # app/Views 内のViewファイルを指定
```

### 2. Executorを作成して実行処理を記述
```php:app/Executors/UserExecutor.php
<?php
namespace Executors;

use Framework\Request;
use Framework\State;

class UserExecutor
{
    public function registerForm(Request $request, State $state): void
    {
        $message = "ユーザー登録ページです！";
        $time = date('Y-m-d H:i:s');
        $data = [
            'message' => $message,
            'time' => $time,
        ];
        $state->set('title', "DIBA PHP");
        $state->set('data', $data);
    }
}
```

### 3. Viewを作成
```php:app/Views/user_register.php
<!DOCTYPE html>
<html>
<head><title><?= htmlspecialchars($title)?></title></head>
<body>
  <h1><?= htmlspecialchars($data['message'] ?? 'No message') ?></h1>
  <p>現在時刻: <?= htmlspecialchars($data['time'] ?? '') ?></p>
</body>
</html>
```

以上により、/user/register にアクセスするとHTMLでレスポンスされます。

MVCに近い処理順序になりますが、Intentで定義している分明確です。

他の機能については、デフォルトとして Welcome を実装していますので、そちらを見ていただけるとわかりやすいかと思います。


## DIBA PHPの概要

:::note warn
※ この章は私の意見や思想が詰まっていますので、興味の無い方はスキップをおすすめします。
:::


### DIBA PHPとは

従来のWebフレームワークは、**ルーティング → コントローラ → サービス(モデル) → レスポンス** という手続き型の処理が基本です。
しかし、この構造は大規模化するとルーティングが肥大化し、コントローラの責務も曖昧になりがちです。
小規模・中規模の開発においては、ルーティング定義が少なく整理しやすく、またコントローラの処理もそこまで肥大化しません。
もちろん、ミドルウェアやサービスも「**頑張れば読める**」範囲に収まります。

この「**頑張れば読める**」構造すら必要としないのが
**DIBA PHP** の最大の特徴です。

PHPで軽量に実装されたマイクロフレームワークであり、**「何をしたいか（＝Intent）」を宣言するだけで、実装が疎結合に連携し、拡張性の高いアーキテクチャを実現**します。

また、マイクロサービスやイベント駆動アーキテクチャと比較しても、DIBAは非常に軽量かつ明示的です。
Intent間の連携や状態の移動は、コードではなくYAMLで視覚的に設計できるため、**単一アプリケーション内でのイベント連携と疎結合設計を両立**できます。

「***どう処理するか***」ではなく「***何をしたいか***」が「**意図駆動型**」の考え方です。

充実したCLIにより、開発効率を大幅に高速化しつつ、開発におけるドキュメントライティングを補助する可能な点も、大きな特徴です。

```bash
# Intent・Executor・レスポンスなどの自動生成
php cli/diba.php make:intent Sample
php cli/diba.php make:executor Sample
php cli/diba.php make:response Csv
php cli/diba.php make:constraint RequireName
php cli/diba.php make:model Product
php cli/diba.php make:service UserService

# RESTful API一式を自動生成（Intent + Executor + Model）
php cli/diba.php make:rest Product

# Intent定義の一覧 / ルート一覧
php cli/diba.php list:intents
php cli/diba.php list:routes

# Intent定義ファイルの構文・スキーマバリデーション
php cli/diba.php validate:intents

# Intentの構造をMermaid形式で出力（graph:intents）
php cli/diba.php graph:intents
# 単一タグ
php cli/diba.php graph:intents --tag event
# 複数タグ指定（OR条件）
php cli/diba.php graph:intents --include-tags core,event,api
# ファイル保存付き
php cli/diba.php graph:intents --include-tags example,event --save docs/graph.mmd


# Intentのシミュレート（ExecutorとResponseをテスト実行）
php cli/diba.php simulate Sample '{"key":"value"}'
php cli/diba.php simulate Sample '{"key":"value"}' --dump  # 実行後のState保存

# テスト
# 単体intentテスト
php cli/diba.php run:test tests/welcome.test.yaml
# 一括intentテスト
php cli/diba.php run:tests tests/
```

---

### なぜ小〜中規模にも向いているのか
以下のポイントが、小〜中規模でもDIBA PHPが優れている点です。
|ポイント|説明|
|---|------------|
|宣言的 |Intentを1ファイルに1定義。YAMLだけでURL/処理/レスポンスを表現でき、可読性が高い。|
|初期コストが低い|ControllerやRouteクラスの学習が不要。|
|CLIで全自動|make:intent だけでAPIの雛形が完成。Intent定義もMermaid形式で出力可能。|
|意図が1ファイルで完結|チーム内で「このIntentは何するのか」がYAMLだけで把握可能。|

---
### 既存アーキテクチャ(MVC)との違い

| 比較軸 | 従来のMVC | DIBA PHP |
|--------|------------|------------|
| ルーティング定義 | コードベース | YAMLで宣言的にIntentを定義 |
| アクション単位 | URL/Controller/Method | Intent単位で定義しやすい |
| 実行処理 | Controllerに集中しがち | Executorに明確に分離、責務が明確 |
| 複数処理 | コントローラ内で処理順序を記述 | executors: に順序定義が可能 |
| イベント連携 | 明示的なイベントバス実装が必要 | effects → on_effects でIntent同士の連携が可能（連鎖実行も可能） |
| レスポンス| コントローラで都度実装 | Json/Html/Redirect/View など統一されたレスポンス設計であり、CSVやPDF, XMLなどの独自のフォーマットも簡単に追加可能 |
| 中間処理（バリデーションなど） | MiddlewareやFilterの実装が必要 | constraints: に定義するだけで、中間処理を実装可能 |

---
### マイクロサービスとの比較

大規模なプロジェクトでも採用されるマイクロサービスと比較しました。

| 観点 | マイクロサービス | DIBA PHP |
|-----|------------|--------------|
| サービス構成 | 完全分離（API単位で独立） | Intentごとに分離可能（ディレクトリで管理）|
| 実行単位 | サービス単位で実行・スケーリング | 単一プロジェクト内でIntentが増えていく|
| 学習・運用コスト | 高（インフラ・デプロイ・連携） | 低（単一プロセス内で全Intentが動作）|
| 実装の疎結合性 | サービス間通信で実現 | effects → on_effects によるIntent連携で実現|

DIBA PHPは、「シングルアプリケーション内の疎結合設計」を最大化するアーキテクチャのため、**軽量アーキテクチャ的マイクロサービス**とも言えるかもしれません。

---
### イベント駆動（EDA）との比較

|観点	|イベント駆動|	DIBA PHP|
|-----|------------|----------------------|
|イベント連携|	イベントバスを経由して非同期に他サービスが反応	|$state->emit() → on_effects: でIntentが自動連携|
|メッセージ処理|	Kafka, RabbitMQ, SNS などを使用	|内部キューまたは同期実行（非同期も拡張可能）|
|実装の明示性|	リスナー側に「誰が発火したか」が見えづらい	|YAMLで連携が明示的に見える（CLIでMermaid形式で可視化も可能）|

DIBAのイベント処理では、明示的なイベント連携の中でEDAの柔軟性だけを取り入れてみました。

---

## 今後の課題

皆様の感じたご意見をコメントやGitHubのissue、PRなどに送っていただけますと幸いです。

### 1. ルーティングの柔軟性を上げる
現状は method と path の完全一致のみであり、パスパラメータや条件付きマッチが実現したいと考えています。
また、RESTful構成にしっかりと対応するために、**ルート解決エンジンの強化**を行いたいと考えています。

### 2. セッション・認証の標準化
セッション管理や認証機能がプロジェクト実装依存ですので、フレームワーク側で基本的な認証パッケージ（AuthModule）を提供しようかと考えています。

### 3. 非同期/ジョブ実行の整備
$state->emit() は現在同期実行です。
今後は EventQueue → JobDispatcher への拡張により、メール送信や通知を非同期処理へ移行できるような、キュー実装（sync, database, redis）に差し替え可能なJobアーキテクチャへの進化が必要と考えています。


### 4. View処理とテンプレートエンジンの選定
現状はPure PHPテンプレートのみ対応としています。
BladeやTwigのようなエンジンに切り替えるもよしですが、本設計上デフォルトエンジンが必要か、デベロッパー側で自由に導入できる形が良いかを考えています。

### 5. Intent定義の自動ドキュメント化
IntentがYAMLで明示されているメリットを活かし、Swagger/OpenAPIへの対応やMarkdown生成、Mermaid生成 を通じてAPI仕様書や画面仕様書を自動生成できる仕組みがあれば、より便利になるかと考えています。

### 6. プラグイン/モジュール機構の拡張
plugins/ や modules/ フォルダを作成し、IntentやExecutorを置くだけで自動読み込み可能にすることで、他プロジェクトとの共有や業務別Intentグループの切り出しが可能になると考えています。

### 7. エコシステムとコミュニティの形成
DIBA PHPを広めていくためには、利用サンプルや実際のUI、管理画面などを充実する必要があります。
ここは私の今のプロジェクトが落ち着き次第、順次対応していきますので、気長にお待ちください。

---

いかがでしょうか。
DIBA PHPに足りないもの、必要なものやご意見があれば、お気軽にご指摘ください。

DIBA PHPはフルオープンソースで開発を進めていきますので、興味があればぜひとも御協力いただけますと幸いです。