BEAR.Sunday CLI チュートリアル

前提条件

  • PHP 8.2以上
  • Composer
  • Git

ステップ1: プロジェクトの作成

1.1 新規プロジェクトの作成

VENDOR=MyVendor PACKAGE=Greet composer create-project bear/skeleton greet
cd greet

1.2 開発サーバーの起動確認

php -S 127.0.0.1:8080 -t public

ブラウザで http://127.0.0.1:8080 にアクセスし、”Hello BEAR.Sunday” が表示されることを確認します。

{
    "greeting": "Hello BEAR.Sunday",
    "_links": {
        "self": {
            "href": "/index"
        }
    }
}

ステップ2: BEAR.Cliのインストール

composer require bear/cli

ステップ3: 挨拶リソースの作成

src/Resource/Page/Greeting.phpを作成します：

<?php

namespace MyVendor\Greet\Resource\Page;

use BEAR\Cli\Attribute\Cli;
use BEAR\Cli\Attribute\Option;
use BEAR\Resource\ResourceObject;

class Greeting extends ResourceObject
{
    #[Cli(
        name: 'greet',
        description: '多言語で挨拶するコマンド',
        output: 'greeting'
    )]
    public function onGet(
        #[Option(shortName: 'n', description: '挨拶する相手の名前')]
        string $name,
        #[Option(shortName: 'l', description: '言語 (en, ja, fr, es)')]
        string $lang = 'en'
    ): static {
        $greeting = match ($lang) {
            'ja' => 'こんにちは',
            'fr' => 'Bonjour',
            'es' => '¡Hola',
            default => 'Hello',
        };
        
        $this->body = [
            'greeting' => "{$greeting}, {$name}",
            'lang' => $lang
        ];

        return $this;
    }
}

ステップ4: Webリソースとしての動作確認

ブラウザで以下のURLにアクセスして動作確認します：

http://127.0.0.1:8080/greeting?name=World&lang=fr

以下のようなJSONレスポンスが表示されるはずです：

{
   "greeting": "Bonjour, World",
   "lang": "fr",
   "_links": {
      "self": {
         "href": "/greeting?name=World&lang=fr"
      }
   }
}

ステップ5: CLIコマンドの生成

vendor/bin/bear-cli-gen MyVendor.Greet

これにより以下のファイルが生成されます：

  • bin/cli/greet：実行可能なCLIコマンド

ステップ6: コマンドのテスト

生成されたコマンドをテストします：

# 実行権限を付与
chmod +x bin/cli/greet

# ヘルプの表示
./bin/cli/greet --help

# 基本的な挨拶
./bin/cli/greet -n "World"
# 出力: Hello, World

# 日本語で挨拶
./bin/cli/greet -n "世界" -l ja
# 出力: こんにちは, 世界

# JSON形式で出力
./bin/cli/greet -n "World" -l ja --format json
# 出力: {"greeting": "こんにちは, World", "lang": "ja"}

ステップ7: ローカルでのHomebrewフォーミュラのテスト

7.1 フォーミュラの生成

フォーミュラを生成するには、Gitリポジトリが初期化されている必要があります：

# Gitリポジトリの初期化（まだの場合）
git init
git add .
git commit -m "Initial commit"

フォーミュラを生成します：

vendor/bin/bear-cli-gen MyVendor.Greet

これにより以下のファイルが生成されます：

  • bin/cli/greet：実行可能なCLIコマンド
  • var/homebrew/greet.rb：Homebrewフォーミュラ（Gitリポジトリが設定されている場合）

7.2 ローカルでのHomebrewインストールテスト

生成されたフォーミュラをローカルでテストできます：

# フォーミュラを使ってローカルインストール
brew install --formula ./var/homebrew/greet.rb

# インストールされたコマンドのテスト
greet -n "Homebrew" -l ja
# 出力: こんにちは, Homebrew

# アンインストール
brew uninstall greet

オプション: 公開配布について

実際にCLIツールを他の人に配布したい場合は、以下の流れでHomebrewパッケージとして公開できます：

  1. アプリケーションをGitHubにプッシュ
  2. 生成されたフォーミュラ（var/homebrew/greet.rb）をhomebrew-プレフィックス付きのGitHubリポジトリで公開
  3. ユーザーはbrew tap your-vendor/greet && brew install greetでインストール可能

詳細な公開手順については、Homebrew公式ドキュメントを参照してください。

注意: フォーミュラの生成には以下の条件が必要です：

  • アプリケーションのGitリポジトリが初期化されている
  • ローカルテストの場合はGitHubリモートリポジトリは不要

これらの条件が満たされていない場合、フォーミュラ生成はスキップされ、その理由が表示されます。

まとめ

GreetingリソースはWeb APIとCLIで動き、CLIはHomebrewパッケージで配布できます。 ビジネスロジックの重複はなく、修正も一箇所で済みます。

同じGreetingクラスに、Web APIからもCLIからもアクセスします。

// 1つのリソース
class Greeting extends ResourceObject {
    public function onGet(string $name, string $lang = 'en'): static
    {
        // ビジネスロジックは一箇所に
    }
}

↓

# Web API として
curl "http://localhost/greeting?name=World&lang=ja"

# CLI として  
./bin/cli/greet -n "World" -l ja

# CLI として（Homebrewでインストールした場合）
brew install your-vendor/greet && greet -n "World" -l ja

長期的な保守性と生産性

ドメインロジックはインターフェイスと結合していないため、リソースのテストでドメインロジックを 検証できます。HTTP・CLIそれぞれのパラメーター変換やシリアライズは境界ごとに個別のテストが 必要です。gRPCやGraphQLのような新しい境界を追加する場合も、リソース自体は再利用できますが、 境界アダプターの実装とテストは別途必要です。

現代的な配布システムとの統合

HomebrewやComposerで配布すると、利用者はPHPやBEAR.Sundayの詳細を意識せずにCLIを使えます。ただし、実行環境の用意は別途必要です。

「Because Everything is a Resource」は、この一貫性を指しています。