+
# Ray.MediaQuery
[](https://codecov.io/gh/ray-di/Ray.MediaQuery)
@@ -10,6 +12,7 @@
Define a PHP interface, attach `#[DbQuery]`, write a SQL file, and Ray.MediaQuery provides the implementation through Ray.Di + AOP. Return types and docblocks drive fetching, hydration, pagination, and post-query result objects.
+
```php
use Ray\MediaQuery\Annotation\DbQuery;
@@ -106,12 +109,11 @@ $todos = $todoQuery->list();
## Documentation
-- [Documentation Home](https://ray-di.github.io/Ray.MediaQuery/) — tutorial, reference, and AI-oriented docs.
-- [Hands-on Tutorial (日本語)](https://ray-di.github.io/Ray.MediaQuery/tutorial/) — 13 chapters using SQLite. ([source](./docs/tutorial/README.ja.md))
-- [Feature Reference](https://ray-di.github.io/Ray.MediaQuery/reference/) — result mapping, factories, parameter handling, pagination, and direct SQL execution. ([source](./docs/reference.md))
-- [BDR Pattern Guide](./BDR_PATTERN.md) — architectural approach behind SQL + rich domain objects.
-- [AI-Oriented Reference](https://ray-di.github.io/Ray.MediaQuery/llms-full.txt) — compact reference for coding agents. ([source](./docs/llms-full.txt))
-- [Demo Application](./demo/) — a minimal runnable smoke test of the module wiring; the hands-on tutorial above is the full feature walkthrough.
+Start from the [Documentation Home](https://ray-di.github.io/Ray.MediaQuery/). It is the single entry point for the manual, hands-on tutorial, BDR pattern, FAQ, ecosystem links, and AI-oriented reference.
+
+## Demo Application
+
+See [demo/](./demo/) for a minimal runnable smoke test of the module wiring. The hands-on tutorial in the documentation site is the full feature walkthrough.
## Philosophy
diff --git a/docs/_config.yml b/docs/_config.yml
index 980c02b..d87a030 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -1,6 +1,6 @@
title: Ray.MediaQuery
description: Interface-Driven SQL for PHP
-lang: ja
+lang: en
baseurl: /Ray.MediaQuery
markdown: kramdown
highlighter: rouge
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 84e3230..e5c71e4 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -8,7 +8,7 @@
- Manual
+Japanese manual covering installation, module setup, SQL conventions, result mapping, factories, parameters, pagination, and direct SQL execution.
+ +FAQ
+ +### Q: 変更されたオブジェクトをどうやってDBに書き戻す（保存する）のですか？ + +**A: BDR の読み取りオブジェクトを保存するのではなく、明示的な書き込み経路を使います。** BDRパターンのオブジェクトは、画面、帳票、API レスポンス、ユースケースに合わせた読み取り側の projection です。オブジェクト自身は保存しません。 + +1. 現在の状態や表示可能な操作を示すために、必要なら BDR の Query モデルを読む +2. 状態変更には Command またはアプリケーションの書き込みユースケースを呼ぶ +3. その書き込み経路で書き込み側の不変条件を検証し、UPDATE、INSERT、DELETE、または別の書き込み手段で結果を永続化する + +```php +// Query側（BDRパターン）: 今の用途に必要なprojection +$order = $this->orderRepo->getOrder($id); +if ($order->canShowProcessAction()) { + // アプリケーションは操作を提示できる。ただし最終判断はCommand側が行う。 + $this->processOrder->execute($id, new DateTimeImmutable()); +} + +// processOrder は必要に応じて明示的な書き込みSQLを使う： +// UPDATE orders SET status = 'processed', processed_at = :timestamp WHERE id = :id +``` + +`canShowProcessAction()` は表示のための読み取り側の派生判断です。`ProcessOrder` は書き込み側の不変条件をあらためて検証しなければなりません。BDR は Command モデルを定義しません。Ray.MediaQuery は DML を実行できますが、それを書き込み手段として選ぶかどうかはアプリケーション側の設計です。 + +これは**CQRS（Command Query Responsibility Segregation：コマンド・クエリ責任分離）**の区別に従います： +- **Query モデル**は画面や帳票に合わせてデータを形作り、派生・表示の振る舞いを持つことができる +- **Command モデル**はドメインの整合性を守り、業務上の行為を実行してよいかを判断する +- **SQL** は projection に向いている。JOIN、集約、計算、非正規化された結果の形を自然に表せる + +### Q: これはCQRSパターンですか？ + +**A: BDRパターンは CQRS の Query 側に適用できます。ただし、より正確には rich read model のパターンです。** Read Repository と Write Repository を別の場所に置く、という話が中心ではありません。重要なのは、関心とモデルを分けることです。 + +出発点は単純です。読み取りと書き込みでは、最適なモデルが違います。 + +書き込み側には、ドメインの整合性を守るモデルが必要です。そこでは意図、振る舞い、不変条件、失敗理由を扱います。「この業務上の行為は実行してよいか？」に答えるモデルです。 + +読み取り側では、画面、帳票、API レスポンスのために、非正規化されたフラットなデータが欲しいことがよくあります。「今表示するにはどんな形が役に立つか？」に答えるモデルです。同じ Repository や Entity モデルで両方を満たそうとするから無理が生じます。 + +CQRS はしばしば、データベースを分ける、インフラを分ける、Repository の置き場所を分ける、といった物理的なアーキテクチャとして誤解されます。それらは有用な実装上の選択肢になることはありますが、本質ではありません。本質は、Command は業務の意思決定であり、Query は表示のための構造である、という分離です。 + +BDR は薄い DTO に限定されません。読み取りモデルは、派生・表示のロジックである限り、振る舞いを持てます。合計、ラベル、表示可否、読み取り側の優先度分類など、現在の projection に関する問いに答える振る舞いです。状態変更の不変条件は Command 側に置きます。 + +SQL はそもそもこの Query 側の性質を持っています。`SELECT` は JOIN、集約、計算を使って、必要な形へ結果を projection できます。その構造を永続的な正規ドメインモデルであるかのように扱う必要はありません。BDR では、SQL ファイルがその projection を定義し、ファクトリやドメインオブジェクトが PHP の型として表面を与えます。 + +Query モデルは使い捨てであってもかまいません。画面、帳票、API レスポンスが変われば、別の `SELECT` と小さな読み取りモデルを作ればよい。それは DRY 違反ではなく、CQRS の要点です。関心が違うものには、違うモデルを与えます。 + +### Q: ファクトリーで外部APIを呼ぶと、リスト取得時に遅くなりませんか？ + +**A: その通りです、適切な戦略なしでは。** これは本質的にN+1問題の変形です。以下は緩和のための戦略です： + +**1. バッチリクエスト** +```php +final class ProductDomainFactory +{ + private array $priceCache = []; + + public function factory(string $id, string $name): ProductDomainObject + { + // 価格はファクトリー呼び出し前にバッチで取得済み + $price = $this->priceCache[$id] ?? $this->priceService->getPrice($id); + return new ProductDomainObject($id, $name, $price); + } + + public function warmPriceCache(array $productIds): void + { + // すべての価格を1回のAPI呼び出しで取得 + $this->priceCache = $this->priceService->getPrices($productIds); + } +} +``` + +**2. 遅延ロード** +```php +final readonly class ProductDomainObject +{ + public function __construct( + private string $id, + private PriceProvider $priceProvider, + ) {} + + public function getCurrentPrice(): float + { + // 実際に必要な時だけ取得する。キャッシュはreadonlyオブジェクトではなくprovider側で管理する。 + return $this->priceProvider->getPrice($this->id); + } +} +``` + +**3. 戦略的データロード** +```php +// リスト表示：高コストなデータをロードしない +#[DbQuery('product_list_simple', factory: ProductListFactory::class)] +public function getProductList(): array; + +// 詳細表示：外部データを含むすべてをロード +#[DbQuery('product_detail', factory: ProductDetailFactory::class)] +public function getProduct(string $id): ProductDomainObject; +``` + +重要なのは、いつどのようにデータをロードするかについて**意図的であること**です。ファクトリーパターンは、この戦略を完全にコントロールする力を与えます。 + +## BEAR.Sunday 連携 + +BEAR.Sunday は、アプリケーションの操作を URI で参照できる `ResourceObject` として表す PHP アプリケーションフレームワークです。`#[Embed]` は、それらのリソース間の関係を宣言します。 + +この境界は BDR と相性が良いです。Repository は **何を**問い合わせるかを宣言したまま、独立したリソースリクエストを **いつ** **どう**実行するかは BEAR.Sunday と BEAR.Async がアプリケーション境界で決めます。Repository interface と SQL file は変わりません。 + +- [BDR + BEAR.Async: 並列 SQL レシピ](https://github.com/ray-di/Ray.MediaQuery/blob/1.x/BEAR_ASYNC_RECIPE-ja.md) — 各リポジトリ呼び出しを `ResourceObject` で包むと、`#[Embed]` がアプリケーション境界でそれらを並列実行する。 + +## 参考文献 + +- [Object-Relational Mapping is the Vietnam of Computer Science](https://blog.codinghorror.com/object-relational-mapping-is-the-vietnam-of-computer-science/) - Jeff Atwood (2006) diff --git a/docs/bdr-pattern.md b/docs/bdr-pattern.md new file mode 100644 index 0000000..95e18bd --- /dev/null +++ b/docs/bdr-pattern.md @@ -0,0 +1,683 @@ +--- +layout: default +title: BDR Pattern Guide +description: "Practical guide to the Business Domain Repository Pattern: explicit SQL, factories, and immutable domain objects." +lang: en +permalink: /bdr-pattern/ +--- + +# Business Domain Repository Pattern (BDR Pattern) Practical Guide + +[日本語 (Japanese)]({{ '/bdr-pattern/ja/' | relative_url }}) + +## Introduction + +Programmers have long grappled with the **boundary** between relational and object-oriented thinking. This problem is known as the "Object-Relational Impedance Mismatch," referring to the fundamental incompatibility between the tabular data of relational databases and the hierarchical object structures of object-oriented programming. + +Traditional ORMs attempted to abstract SQL away, **making it invisible**. This abstraction created boundaries that developers constantly felt. We want to leverage the power of databases while maintaining object-oriented principles. How to reconcile these two desires has always been a challenge. + +**The BDR Pattern dissolves this boundary.** + +**In the BDR Pattern, SQL and OOP shake hands**. Each performs what it does best while working in harmony. + +The friction caused by boundaries is eliminated. There's no longer a need for forced abstractions or for one paradigm to pretend the other doesn't exist. + +## Executive Summary + +The BDR Pattern presents a new paradigm where **Object-Oriented Programming and SQL work in harmony**. It achieves "OOP autonomy with SQL foundation" and enables: + +**Core Value Propositions:** +- **SQL remains SQL**: Complex queries, JOINs, window functions - all at maximum performance +- **Objects remain objects**: Autonomous domain models with rich behavior +- **Leveraging both strengths**: Achieving both object-oriented design and SQL performance +- **Clear testing**: Each component can be tested independently + +## Why This Matters + +### Common Scenarios in Development + +Complex business logic scattered across controllers. One change requires modifications to multiple methods, and testing requires numerous mock objects. + +When using ORMs, we encounter characteristics such as: +- Need to handle N+1 query problems +- Constraints in expressing complex JOINs +- Difficulty predicting generated SQL +- Creative workarounds needed for performance tuning + +**The BDR Pattern proposes a different approach.** + +It leverages the strengths of both SQL and OOP, allowing each to shine in their respective domains. + +### The BDR Pattern Approach + +```php +public function showOrderDetails(string $id): Response +{ + $order = $this->orderRepo->getOrder($id); + return $this->render('order.html.twig', ['order' => $order]); +} + +// Business logic in factories +// SQL in optimized query files +// Tests in independent layers +``` + +Simple structure improves maintainability and readability. + +## The Problem and Solution + +### Traditional Approach Problems + +```php +class OrderController +{ + public function show(string $id): Response + { + $order = $this->orderRepo->findById($id); // Simple data + + // Business logic scattered in controller - testing nightmare! + $items = $this->inventoryService->checkStock($order->items); + $tax = $this->taxCalculator->calculate($items, $order->region); + $shipping = $this->shippingService->calculate($items, $order->region); + $canFulfill = $this->validateOrder($items, $order->status); + + // Testing this controller requires mocking 6+ dependencies! + + return $this->render('order.html.twig', compact('order', 'tax', 'shipping', 'canFulfill')); + } +} +``` + +### BDR Pattern Solution + +```php +class OrderController +{ + public function show(string $id): Response + { + // Repository returns complete domain object + $order = $this->orderRepo->getOrder($id); + + // Controller only renders - no business logic + return $this->render('order.html.twig', ['order' => $order]); + } +} +``` + +## Object Autonomy + +The BDR Pattern achieves something important: **true object autonomy with SQL as the foundation**. + +Balancing object autonomy and SQL efficiency was traditionally considered difficult. The BDR Pattern achieves this balance. Domain objects are self-contained with their own behavior and data, while their creation is efficiently powered by SQL queries. + +### Read-Only, Immutable Domain Objects + +**Critically, domain objects in the BDR Pattern are read-only and immutable.** They represent a snapshot of the database at a specific point in time. These objects: + +- **Have no `save()` methods** - They don't persist themselves +- **Have no setters** - State cannot be modified after creation +- **Are query results** - They represent the "read" side of your architecture + +This immutability is intentional and brings important benefits: +- **Thread-safe by default** - Safe to share across concurrent operations +- **Predictable behavior** - State never changes unexpectedly +- **Clear intent** - Separation between queries (reading data) and commands (changing data) + +```php +// Leveraging the power of DI in domain objects +final readonly class UserDomainObject +{ + public function __construct( + public string $id, + public string $name, + public string $role, + // Service injected from factory + private PermissionService $permissionService, + ) {} + + // Read-side business questions through injected service + public function canEdit(Document $document): bool + { + // Difficult with ORM entities - depends on external service + // Test env: FakePermissionService (everyone can edit) + // Production: RealPermissionService (complex permission checks) + return $this->permissionService->canEdit($this, $document); + } + + // Note: No save(), update(), or setter methods + // This object is a read-only snapshot +} +``` + +In the BDR Pattern, objects are not mere data containers but read-side domain objects with behavior. They answer questions about the current projection and user experience, but Command models still make the final decision before state changes. + +## Implementation Guide + +### 1. Repository Interface Definition + +```php +interface OrderRepositoryInterface +{ + #[DbQuery('order_detail', factory: OrderDomainFactory::class)] + public function getOrder(string $id): OrderDomainObject; + + #[DbQuery('active_orders', factory: OrderDomainFactory::class)] + /** @return arrayFAQ
+ +### Q: How do I save modified objects back to the database? + +**A: Use an explicit write path, not the BDR read object.** A BDR object is a read-side projection shaped for a screen, report, API response, or use case. It does not save itself. + +1. Read a BDR Query model when it helps present the current state or available actions. +2. Call a Command or application write use case for the state change. +3. In that write path, validate write-side invariants and persist the result with UPDATE, INSERT, DELETE, or another write mechanism. + +```php +// Query side (BDR Pattern): projection for the current use +$order = $this->orderRepo->getOrder($id); +if ($order->canShowProcessAction()) { + // The application may offer the action, but the Command owns the final decision. + $this->processOrder->execute($id, new DateTimeImmutable()); +} + +// processOrder may use explicit write SQL: +// UPDATE orders SET status = 'processed', processed_at = :timestamp WHERE id = :id +``` + +`canShowProcessAction()` is read-side derivation for presentation. `ProcessOrder` must still enforce the write-side invariant. BDR does not define the Command model; Ray.MediaQuery can execute DML if that is the write mechanism you choose. + +This follows the **CQRS (Command Query Responsibility Segregation)** distinction: +- **Query models** shape data for display or reporting and may contain derivation/presentation behavior +- **Command models** protect domain consistency and decide whether a business action may happen +- **SQL** is naturally good at projection: JOINs, aggregations, calculations, and denormalized result shapes + +### Q: Is this the CQRS pattern? + +**A: BDR fits the Query side of CQRS, but more precisely it is a rich read-model pattern.** It is not mainly about placing read repositories and write repositories in different locations. It is about separating concerns and models. + +The starting point is simple: reads and writes want different models. + +The write side needs a domain model that protects consistency. It carries intent, behavior, invariants, and failure reasons. It answers, "May this business action happen?" + +The read side often wants denormalized, flattened data for a screen, report, or API response. It answers, "What shape is useful to display now?" Trying to satisfy both with one Repository or Entity model creates friction. + +CQRS is often mistaken for a physical architecture: separate databases, separate infrastructure, separate repository locations. Those may be useful implementation choices, but they are not the essence. The essence is that Command is business decision, and Query is display structure. + +BDR is not limited to a thin DTO. Its read model can expose behavior, as long as that behavior is derivation or presentation logic: totals, labels, visibility, read-side priority, or other answers about the current projection. State-changing invariants stay on the Command side. + +SQL already has this Query-side character. A `SELECT` can join, aggregate, calculate, and project a result into the exact structure needed without pretending that structure is the canonical domain model. In BDR, the SQL file defines that projection, and the factory/domain object gives it a typed PHP surface. + +The Query model may be disposable. If a screen, report, or API response changes, write another `SELECT` and another small read model. That is not a DRY violation; it is the point of CQRS: different concerns get different models. + +### Q: Won't calling external APIs in factories slow down list retrievals? + +**A: Yes, without proper strategy.** This is essentially an N+1 problem variant. Here are strategies to mitigate: + +**1. Batch Requests** +```php +final class ProductDomainFactory +{ + private array $priceCache = []; + + public function factory(string $id, string $name): ProductDomainObject + { + // Prices fetched in batch before factory calls + $price = $this->priceCache[$id] ?? $this->priceService->getPrice($id); + return new ProductDomainObject($id, $name, $price); + } + + public function warmPriceCache(array $productIds): void + { + // Fetch all prices in one API call + $this->priceCache = $this->priceService->getPrices($productIds); + } +} +``` + +**2. Lazy Loading** +```php +final readonly class ProductDomainObject +{ + public function __construct( + private string $id, + private PriceProvider $priceProvider, + ) {} + + public function getCurrentPrice(): float + { + // Only fetch when actually needed; cache inside the provider, not this readonly object. + return $this->priceProvider->getPrice($this->id); + } +} +``` + +**3. Strategic Data Loading** +```php +// List view: Don't load expensive data +#[DbQuery('product_list_simple', factory: ProductListFactory::class)] +public function getProductList(): array; + +// Detail view: Load everything including external data +#[DbQuery('product_detail', factory: ProductDetailFactory::class)] +public function getProduct(string $id): ProductDomainObject; +``` + +The key is **being intentional** about when and how you load data. The factory pattern gives you complete control over this strategy. + +## BEAR.Sunday Integration + +BEAR.Sunday is a resource-oriented PHP application framework. Application operations are represented as URI-addressable `ResourceObject`s, and `#[Embed]` declares relationships between those resources. + +That boundary is useful for BDR. The Repository still declares **what** SQL to run, while BEAR.Sunday and BEAR.Async decide **when** and **how** independent resource requests run. Repository interfaces and SQL files do not change. + +- [BDR + BEAR.Async: Parallel SQL Recipe](https://github.com/ray-di/Ray.MediaQuery/blob/1.x/BEAR_ASYNC_RECIPE.md) — wrap each Repository call in a `ResourceObject` and let `#[Embed]` parallelise them at the application boundary. + +## References + +- [Object-Relational Mapping is the Vietnam of Computer Science](https://blog.codinghorror.com/object-relational-mapping-is-the-vietnam-of-computer-science/) - Jeff Atwood (2006) diff --git a/docs/index.html b/docs/index.html index 3ac1831..f2e3933 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,54 +1,154 @@ --- layout: default title: Ray.MediaQuery Documentation -description: Documentation links for Ray.MediaQuery, including the hands-on tutorial and AI-oriented reference. -lang: ja +description: Documentation links for Ray.MediaQuery, including the English tutorial, Japanese manual, and AI-oriented reference. +lang: en permalink: / +home: true --- + + + +Ray.MediaQuery Documentation
-Interface-Driven SQL for PHP
-
- SQL は SQL のまま、PHP は PHP のまま。Ray.MediaQuery のチュートリアルと AI 向けリファレンスへの入口です。
- Keep SQL explicit and PHP typed. Start with the tutorial, or open the compact AI-oriented reference.
-
+
+
+
+
+ Ray.MediaQuery
+Interface-Driven SQL for PHP
++ SQL speaks infrastructure. Types express the domain. PHP interfaces bridge them. +
+
+
+ Ray.MediaQuery
+Interface-Driven SQL for PHP
+Hands-on Tutorial
+Build a SQLite-backed blog example and learn the main Ray.MediaQuery features through 1.1.0.
+ +BDR Pattern
+How explicit SQL, factories, and immutable domain objects let SQL and OOP work in harmony.
+ +FAQ
+Architecture answers for writes, CQRS, and factory performance in the BDR pattern.
+ +Ecosystem
+Source code, AI-oriented reference, demo, and BEAR.Sunday integration recipes around Ray.MediaQuery.
++ GitHub + llms-full.txt + Async recipe +
+マニュアル
+インストール、モジュール設定、SQL ファイル規約から、戻り値マッピング、ファクトリ、パラメータ変換、ページネーション、直接 SQL 実行までのガイド。
+ +ハンズオンチュートリアル
-ブログサービスを題材に、Ray.MediaQuery 1.1.0 までの主要機能を第0章から第13章＋補章で体験します。
-Hands-on tutorial in Japanese. Build a SQLite-backed blog example end-to-end.
+SQLite のブログ例を作りながら、Ray.MediaQuery 1.1.0 までの主要機能を学びます。
Feature Reference
-戻り値マッピング、ファクトリ、パラメータ変換、ページネーション、直接 SQL 実行の詳細。
-Detailed reference for result mapping, factories, parameter handling, pagination, and direct SQL execution.
- +BDR パターン
+明示的な SQL、ファクトリ、イミュータブルなドメインオブジェクトで SQL と OOP を調和させる設計ガイド。
+AI-Oriented Reference
-AI coding agents 向けに圧縮した Ray.MediaQuery の仕様・使い方リファレンスです。
-A concise reference for AI coding agents and quick lookup.
- +FAQ
+BDR パターンにおける書き込み、CQRS、factory performance への設計上の答え。
+GitHub Repository
-README、ソースコード、Issue、リリース情報はこちら。
-Source code, README, issues, and releases.
- +エコシステム
+ソースコード、AI 向けリファレンス、デモ、BEAR.Sunday 連携レシピなど、周辺リソースへの導線です。
++ GitHub + llms-full.txt + Async レシピ +
English / 日本語
-
- 現在の詳しいチュートリアルは日本語版です。README と AI 向けリファレンスは英語で利用できます。
- The detailed tutorial is currently available in Japanese. The README and AI-oriented reference are available in English.
-