@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/getting-start-tdd/php/11-immutable-data-and-pipeline.md

@@ -0,0 +1,266 @@
+# 第 11 章: 不変データとパイプライン処理
+
+## 11.1 不変データ設計の確認
+
+PHP 8.1+ の **readonly プロパティ**により、言語レベルで不変性を保証できます。
+
+### FizzBuzzValue の不変設計
+
+第 8 章で作成した `FizzBuzzValue` は既に不変です:
+
+```php
+final class FizzBuzzValue
+{
+    public function __construct(
+        private readonly int $number,    // 変更不可
+        private readonly string $value,  // 変更不可
+    ) {
+    }
+}
+```
+
+- **readonly** で一度設定した値を変更不可に
+- **private** で外部からの直接アクセスを禁止
+- setter メソッドがない
+
+### FizzBuzzList の不変設計
+
+```php
+final class FizzBuzzList
+{
+    private readonly array $value;  // 変更不可
+}
+```
+
+- `filter` や `map` は**新しいインスタンス/配列**を返す（元のリストは変更しない）
+- `readonly` で配列の再代入を禁止
+
+### テスト: Filter が元のリストを変更しないことを確認する
+
+```php
+public function test_filterは元のリストを変更しない(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type, 15);
+    $original = $command->execute();
+    $originalCount = $original->count();
+
+    $isFizz = fn(FizzBuzzValue $v): bool => $v->getValue() === 'Fizz';
+    $original->filter($isFizz);
+
+    $this->assertSame($originalCount, $original->count());
+}
+```
+
+## 11.2 パイプラインメソッド
+
+FizzBuzzList にパイプライン処理のためのメソッドを追加します。
+
+### テスト: groupByValue -- 値でグルーピングする
+
+```php
+public function test_groupByValueで値でグルーピングする(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type, 15);
+    $list = $command->execute();
+
+    $grouped = $list->groupByValue();
+
+    $this->assertArrayHasKey('Fizz', $grouped);
+    $this->assertArrayHasKey('Buzz', $grouped);
+    $this->assertArrayHasKey('FizzBuzz', $grouped);
+}
+```
+
+<details>
+<summary>実装コード: groupByValue</summary>
+
+```php
+/**
+ * @return array<string, FizzBuzzValue[]>
+ */
+public function groupByValue(): array
+{
+    $result = [];
+    foreach ($this->value as $v) {
+        $result[$v->getValue()][] = $v;
+    }
+    return $result;
+}
+```
+
+</details>
+
+### テスト: countByValue -- 値ごとの出現回数を数える
+
+```php
+public function test_countByValueで値ごとの出現回数を数える(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type, 15);
+    $list = $command->execute();
+
+    $counts = $list->countByValue();
+
+    $this->assertSame(1, $counts['FizzBuzz']);
+}
+```
+
+<details>
+<summary>実装コード: countByValue</summary>
+
+```php
+/**
+ * @return array<string, int>
+ */
+public function countByValue(): array
+{
+    $result = [];
+    foreach ($this->value as $v) {
+        $key = $v->getValue();
+        $result[$key] = ($result[$key] ?? 0) + 1;
+    }
+    return $result;
+}
+```
+
+</details>
+
+### テスト: take -- 先頭 N 件を取得する
+
+```php
+public function test_takeで先頭N件を取得する(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type, 15);
+    $list = $command->execute();
+
+    $taken = $list->take(5);
+
+    $this->assertSame(5, $taken->count());
+}
+```
+
+<details>
+<summary>実装コード: take</summary>
+
+```php
+public function take(int $n): self
+{
+    return new self(array_slice($this->value, 0, $n));
+}
+```
+
+</details>
+
+### テスト: join -- 要素を文字列で結合する
+
+```php
+public function test_joinで要素を文字列で結合する(): void
+{
+    $values = [
+        new FizzBuzzValue(1, '1'),
+        new FizzBuzzValue(2, '2'),
+        new FizzBuzzValue(3, 'Fizz'),
+    ];
+    $list = new FizzBuzzList($values);
+
+    $result = $list->join(', ');
+
+    $this->assertSame('1, 2, Fizz', $result);
+}
+```
+
+<details>
+<summary>実装コード: join</summary>
+
+```php
+public function join(string $separator): string
+{
+    return implode($separator, $this->toStringArray());
+}
+```
+
+</details>
+
+## 11.3 メソッドチェーンによるパイプライン
+
+`filter` と `take` は `FizzBuzzList` を返すため、**メソッドチェーン**でパイプラインを構築できます。
+
+### テスト: メソッドチェーンで Fizz を 3 件取得して結合する
+
+```php
+public function test_メソッドチェーンでパイプラインを構築する(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type);
+    $list = $command->execute();
+
+    $result = $list
+        ->filter(fn(FizzBuzzValue $v): bool => $v->getValue() === 'Fizz')
+        ->take(3)
+        ->join(', ');
+
+    $this->assertSame('Fizz, Fizz, Fizz', $result);
+}
+```
+
+### array_reduce パターン
+
+PHP の `array_reduce` を使った畳み込み:
+
+### テスト: reduce で数値の合計を計算する
+
+```php
+public function test_reduceで数値の合計を計算する(): void
+{
+    $values = [
+        new FizzBuzzValue(1, '1'),
+        new FizzBuzzValue(2, '2'),
+        new FizzBuzzValue(3, 'Fizz'),
+    ];
+    $list = new FizzBuzzList($values);
+
+    $sum = $list->reduce(0, fn(int $acc, FizzBuzzValue $v): int => $acc + $v->getNumber());
+
+    $this->assertSame(6, $sum);
+}
+```
+
+<details>
+<summary>実装コード: reduce</summary>
+
+```php
+/**
+ * @template R
+ * @param R $initial
+ * @param callable(R, FizzBuzzValue): R $fn
+ * @return R
+ */
+public function reduce(mixed $initial, callable $fn): mixed
+{
+    return array_reduce($this->value, $fn, $initial);
+}
+```
+
+</details>
+
+## 11.4 各言語のパイプライン比較
+
+| 機能 | PHP | Go | Java | Ruby | TypeScript |
+|------|-----|-----|------|------|------------|
+| パイプライン構文 | メソッドチェーン | メソッドチェーン | Stream API | メソッドチェーン | メソッドチェーン |
+| グルーピング | 手動 `foreach` | 手動 `map` 構築 | `Collectors.groupingBy` | `group_by` | `reduce` |
+| 結合 | `implode` | `strings.Join` | `Collectors.joining` | `join` | `Array.join` |
+| 畳み込み | `array_reduce` | 手動 `Reduce` | `Stream.reduce` | `reduce` / `inject` | `Array.reduce` |
+| 遅延評価 | なし（即時評価） | なし（即時評価） | `Stream`（遅延） | `Lazy` | なし |
+
+## 11.5 まとめ
+
+本章では以下を学びました:
+
+- **不変データ設計**: `readonly` プロパティで言語レベルの不変性保証
+- **パイプラインメソッド**: groupByValue、countByValue、take、join
+- **メソッドチェーン**: filter -> take -> join のパイプライン構築
+- **array_reduce**: PHP 組み込みの畳み込み関数

package/lib/assets/docs/article/getting-start-tdd/php/12-error-handling-and-type-safety.md

@@ -0,0 +1,308 @@
+# 第 12 章: エラーハンドリングと型安全性
+
+## 12.1 例外処理
+
+PHP の標準的なエラーハンドリングは **例外**（`Exception` / `Error`）です。第 7-9 章で `\InvalidArgumentException` を使用していましたが、カスタム例外クラスを導入してより型安全なエラーハンドリングを実現します。
+
+### カスタム例外クラス
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain;
+
+final class FizzBuzzException extends \InvalidArgumentException
+{
+}
+```
+
+### テスト: カスタム例外を使用する
+
+```php
+public function test_不正なタイプでカスタム例外を発生する(): void
+{
+    $this->expectException(FizzBuzzException::class);
+    $this->expectExceptionMessage('タイプ99は見つかりません');
+    FizzBuzz::create(99);
+}
+
+public function test_負の値でカスタム例外を発生する(): void
+{
+    $this->expectException(FizzBuzzException::class);
+    new FizzBuzzValue(-1, '-1');
+}
+```
+
+### PHP の例外階層
+
+```plantuml
+@startuml
+title PHP の例外階層
+
+class Throwable <<interface>>
+class Error
+class Exception
+class InvalidArgumentException
+class OutOfRangeException
+class FizzBuzzException
+
+Throwable <|-- Error
+Throwable <|-- Exception
+Exception <|-- InvalidArgumentException
+InvalidArgumentException <|-- FizzBuzzException
+Exception <|-- OutOfRangeException
+
+@enduml
+```
+
+## 12.2 列挙型（PHP 8.1+）
+
+PHP 8.1 で導入された **enum** により、タイプコードをマジックナンバーから型安全な列挙型に置き換えられます。
+
+### テスト: 列挙型で型安全にタイプを指定する
+
+```php
+public function test_列挙型でタイプを生成する(): void
+{
+    $type = FizzBuzzTypeName::Standard->createType();
+    $result = $type->generate(3);
+    $this->assertSame('Fizz', $result->getValue());
+}
+
+public function test_全ての列挙型でタイプを生成できる(): void
+{
+    foreach (FizzBuzzTypeName::cases() as $name) {
+        $type = $name->createType();
+        $this->assertInstanceOf(FizzBuzzType::class, $type);
+    }
+}
+```
+
+### 実装
+
+<details>
+<summary>FizzBuzzTypeName 列挙型</summary>
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain\Type;
+
+enum FizzBuzzTypeName: int
+{
+    case Standard = 1;
+    case NumberOnly = 2;
+    case FizzBuzzOnly = 3;
+
+    public function createType(): FizzBuzzType
+    {
+        return match ($this) {
+            self::Standard => new FizzBuzzType01(),
+            self::NumberOnly => new FizzBuzzType02(),
+            self::FizzBuzzOnly => new FizzBuzzType03(),
+        };
+    }
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Standard => '通常',
+            self::NumberOnly => '数値のみ',
+            self::FizzBuzzOnly => 'FizzBuzzのみ',
+        };
+    }
+}
+```
+
+</details>
+
+### enum の特徴
+
+| 特徴 | 説明 |
+|------|------|
+| Backed enum | `int` や `string` の値を持てる（`enum Foo: int`） |
+| メソッド定義 | enum にメソッドを追加可能 |
+| `cases()` | 全ケースの配列を返す |
+| `from()` | 値から enum を生成（無効値で `ValueError`） |
+| `tryFrom()` | 値から enum を生成（無効値で `null`） |
+
+## 12.3 match 式（PHP 8.0+）
+
+**match 式** は `switch` の型安全な代替です。`===`（厳密比較）を使い、値を返します。
+
+### switch と match の比較
+
+```php
+// switch: 型の曖昧さがある（==）
+switch ($type) {
+    case 1:
+        $result = new FizzBuzzType01();
+        break;
+    case 2:
+        $result = new FizzBuzzType02();
+        break;
+    default:
+        throw new \InvalidArgumentException();
+}
+
+// match: 型安全（===）、値を返す
+$result = match ($type) {
+    1 => new FizzBuzzType01(),
+    2 => new FizzBuzzType02(),
+    default => throw new \InvalidArgumentException(),
+};
+```
+
+### テスト: match 式で型安全に分岐する
+
+```php
+public function test_match式でタイプ名を取得する(): void
+{
+    $describe = fn(FizzBuzzType $type): string => match (true) {
+        $type instanceof FizzBuzzType01 => 'Standard',
+        $type instanceof FizzBuzzType02 => 'NumberOnly',
+        $type instanceof FizzBuzzType03 => 'FizzBuzzOnly',
+        default => 'Unknown',
+    };
+
+    $this->assertSame('Standard', $describe(new FizzBuzzType01()));
+    $this->assertSame('NumberOnly', $describe(new FizzBuzzType02()));
+    $this->assertSame('FizzBuzzOnly', $describe(new FizzBuzzType03()));
+}
+```
+
+## 12.4 FizzBuzzList の検索メソッド
+
+### テスト: findFirst -- 条件に合致する最初の要素を返す
+
+```php
+public function test_findFirstで最初のFizzBuzzを見つける(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type);
+    $list = $command->execute();
+
+    $isFizzBuzz = fn(FizzBuzzValue $v): bool => $v->getValue() === 'FizzBuzz';
+    $result = $list->findFirst($isFizzBuzz);
+
+    $this->assertNotNull($result);
+    $this->assertSame(15, $result->getNumber());
+}
+
+public function test_findFirstで見つからない場合nullを返す(): void
+{
+    $values = [new FizzBuzzValue(1, '1')];
+    $list = new FizzBuzzList($values);
+
+    $isFizzBuzz = fn(FizzBuzzValue $v): bool => $v->getValue() === 'FizzBuzz';
+    $result = $list->findFirst($isFizzBuzz);
+
+    $this->assertNull($result);
+}
+```
+
+<details>
+<summary>実装コード: findFirst</summary>
+
+```php
+/**
+ * @param callable(FizzBuzzValue): bool $predicate
+ */
+public function findFirst(callable $predicate): ?FizzBuzzValue
+{
+    foreach ($this->value as $v) {
+        if ($predicate($v)) {
+            return $v;
+        }
+    }
+    return null;
+}
+```
+
+</details>
+
+### テスト: anyMatch / allMatch -- 存在チェック
+
+```php
+public function test_anyMatchでFizzが存在する(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type, 15);
+    $list = $command->execute();
+
+    $isFizz = fn(FizzBuzzValue $v): bool => $v->getValue() === 'Fizz';
+    $this->assertTrue($list->anyMatch($isFizz));
+}
+
+public function test_allMatchで全て数値ではない(): void
+{
+    $type = new FizzBuzzType01();
+    $command = new FizzBuzzListCommand($type, 15);
+    $list = $command->execute();
+
+    $isNumber = fn(FizzBuzzValue $v): bool =>
+        $v->getValue() !== 'Fizz'
+        && $v->getValue() !== 'Buzz'
+        && $v->getValue() !== 'FizzBuzz';
+    $this->assertFalse($list->allMatch($isNumber));
+}
+```
+
+<details>
+<summary>実装コード: anyMatch / allMatch</summary>
+
+```php
+/**
+ * @param callable(FizzBuzzValue): bool $predicate
+ */
+public function anyMatch(callable $predicate): bool
+{
+    foreach ($this->value as $v) {
+        if ($predicate($v)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * @param callable(FizzBuzzValue): bool $predicate
+ */
+public function allMatch(callable $predicate): bool
+{
+    foreach ($this->value as $v) {
+        if (!$predicate($v)) {
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+</details>
+
+## 12.5 各言語のエラーハンドリング比較
+
+| 機能 | PHP | Go | Java | Ruby | TypeScript |
+|------|-----|-----|------|------|------------|
+| エラー型 | 例外（`Exception`） | `error` インターフェース | 例外（`Exception`） | 例外（`StandardError`） | 例外（`Error`） |
+| null 安全 | `?Type`（Nullable 型） | 多値返却 `(T, error)` | `Optional<T>` | `nil` | `T \| undefined` |
+| パターンマッチング | `match` 式 + `instanceof` | 型スイッチ | `instanceof` / `switch` | `case/in` | `typeof` / `switch` |
+| 列挙型 | `enum`（PHP 8.1+） | `iota` + 型定義 | `enum` | 定数モジュール | `enum` / Union 型 |
+| 型安全な分岐 | `match`（`===`） | 型スイッチ | `switch` | `case/when` | `switch` |
+
+## 12.6 まとめ
+
+本章では以下を学びました:
+
+- **例外処理**: カスタム例外クラスによる型安全なエラーハンドリング
+- **列挙型**（PHP 8.1+）: マジックナンバーの排除と型安全なファクトリ
+- **match 式**（PHP 8.0+）: 型安全な条件分岐（`===` 厳密比較）
+- **検索メソッド**: `findFirst`（`?FizzBuzzValue`）、`anyMatch`、`allMatch`
+- **Nullable 型**: `?Type` による null 安全な戻り値
+
+PHP のエラーハンドリングと型システムは、PHP 8.x の進化により Java や TypeScript に近い型安全性を実現しています。`enum` + `match` の組み合わせは特に強力で、従来の `switch` + マジックナンバーに比べて大幅に安全性が向上しています。

package/lib/assets/docs/article/getting-start-tdd/php/index.md

@@ -0,0 +1,84 @@
+# テスト駆動開発から始める PHP 入門
+
+## 概要
+
+FizzBuzz 問題を題材に、テスト駆動開発（TDD）の基本サイクルから、開発環境の整備、オブジェクト指向設計、関数型プログラミングの活用まで、PHP の特徴を活かしながら段階的に学びます。
+
+## 対象読者
+
+- PHP の基本文法を理解しているプログラミング学習者
+- TDD を体験してみたい開発者
+- オブジェクト指向設計や関数型プログラミングに興味がある方
+
+## 前提条件
+
+- PHP 8.1 以降がインストールされていること
+- Composer が利用可能であること（Nix 環境推奨: `nix develop .#php`）
+
+## PHP の特徴
+
+| 特徴 | 説明 |
+|------|------|
+| 動的型付け + 型宣言 | 型宣言（PHP 7.0+）で段階的に型安全性を向上 |
+| オブジェクト指向 | クラス、インターフェース、トレイト、抽象クラスを完備 |
+| readonly プロパティ | PHP 8.1+ で不変なプロパティ宣言をサポート |
+| enum 型 | PHP 8.1+ でネイティブな列挙型をサポート |
+| match 式 | PHP 8.0+ で型安全な条件分岐を提供 |
+| アロー関数 | `fn =>` 構文で簡潔な無名関数を記述 |
+| コンストラクタプロモーション | PHP 8.0+ でコンストラクタ引数をプロパティに自動昇格 |
+
+## 開発ツール
+
+| ツール | 用途 |
+|--------|------|
+| [PHPUnit](https://phpunit.de/) | テスティングフレームワーク |
+| [Composer](https://getcomposer.org/) | パッケージ管理 |
+| [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) | コーディング規約チェック |
+| [PHPStan](https://phpstan.org/) | 静的解析 |
+| Composer scripts | タスクランナー |
+
+## 目次
+
+### 第 1 部: TDD の基本サイクル
+
+1. [第 1 章: TODO リストと最初のテスト](01-todo-list-and-first-test.md)
+2. [第 2 章: 仮実装と三角測量](02-fake-it-and-triangulation.md)
+3. [第 3 章: 明白な実装とリファクタリング](03-obvious-implementation-and-refactoring.md)
+
+### 第 2 部: 開発環境と自動化
+
+4. [第 4 章: バージョン管理と Conventional Commits](04-version-control-and-conventional-commits.md)
+5. [第 5 章: パッケージ管理と静的解析](05-package-management-and-static-analysis.md)
+6. [第 6 章: タスクランナーと CI/CD](06-task-runner-and-ci-cd.md)
+
+### 第 3 部: オブジェクト指向設計
+
+7. [第 7 章: カプセル化とポリモーフィズム](07-encapsulation-and-polymorphism.md)
+8. [第 8 章: デザインパターンの適用](08-design-patterns.md)
+9. [第 9 章: SOLID 原則とモジュール設計](09-solid-principles-and-module-design.md)
+
+### 第 4 部: 関数型プログラミングへの展開
+
+10. [第 10 章: 高階関数と関数合成](10-higher-order-functions-and-composition.md)
+11. [第 11 章: 不変データとパイプライン処理](11-immutable-data-and-pipeline.md)
+12. [第 12 章: エラーハンドリングと型安全性](12-error-handling-and-type-safety.md)
+
+## 実装コード
+
+本記事のすべてのコード例は `apps/php/` に実装されています。
+
+```bash
+# 開発環境に入る
+nix develop .#php
+
+# テスト実行
+cd apps/php
+composer test
+```
+
+## 参考文献
+
+- Kent Beck 著『テスト駆動開発』
+- Martin Fowler 著『リファクタリング: 既存のコードを安全に改善する』
+- Robert C. Martin 著『Clean Code: アジャイルソフトウェア達人の技』
+- [PHP: The Right Way](https://phptherightway.com/)