diff --git a/manuals/1.0/en/325.cli.md b/manuals/1.0/en/325.cli.md new file mode 100644 index 00000000..863f3f57 --- /dev/null +++ b/manuals/1.0/en/325.cli.md @@ -0,0 +1,337 @@ +--- +layout: docs-en +title: Command Line Interface (CLI) +category: Manual +permalink: /manuals/1.0/en/cli.html +--- +# Command Line Interface (CLI) + +BEAR.Sunday's Resource-Oriented Architecture (ROA) represents every functionality of the application as a URI-addressable resource. This approach allows access to resources in various ways, not limited to the web. + +```bash +$ php page.php '/greeting?name=World&lang=ja' +{ + "greeting": "こんにちは, World", + "lang": "ja" +} +``` + +BEAR.Cli is a tool that converts such resources into native CLI commands, making them distributable via Homebrew: + +```bash +$ greet -n "World" -l ja +Hello, World +``` + +Without writing additional code, you can reuse existing application resources as standard CLI tools. Distribution through Homebrew allows users to use them just like any general command-line tool, without knowing that they are running on PHP or BEAR.Sunday. + +## Installation + +Install via Composer. + +```bash +composer require bear/cli +``` + +## Basic Usage + +### Adding CLI Attributes to Resources + +Add CLI attributes to the resource class to define the command-line interface. + +```php +use BEAR\Cli\Attribute\Cli; +use BEAR\Cli\Attribute\Option; + +class Greeting extends ResourceObject +{ + #[Cli( + name: 'greet', + description: 'Say hello in multiple languages', + output: 'greeting' + )] + public function onGet( + #[Option(shortName: 'n', description: 'Name to greet')] + string $name, + #[Option(shortName: 'l', description: 'Language (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; + } +} +``` + +### Generating CLI Commands and Formula + +```bash +$ vendor/bin/bear-cli-gen MyVendor.MyProject +# Generated files: +# bin/cli/greet # CLI command +# var/homebrew/greet.rb # Homebrew formula +``` + +## Using the Command + +The generated command provides standard CLI features as follows: + +### Displaying Help + +```bash +$ greet --help +Say hello in multiple languages + +Usage: greet [options] + +Options: + --name, -n Name to greet (required) + --lang, -l Language (en, ja, fr, es) (default: en) + --help, -h Show this help message + --version, -v Show version information + --format Output format (text|json) (default: text) +``` + +### Displaying Version Information + +```bash +$ greet --version +greet version 0.1.0 +``` + +### Basic Usage Examples + +```bash +# Basic greeting +$ greet -n "World" +Hello, World + +# Specify language +$ greet -n "World" -l ja +こんにちは, World + +# Short options +$ greet -n "World" -l fr +Bonjour, World + +# Long options +$ greet --name "World" --lang es +¡Hola, World +``` + +### JSON Output + +```bash +$ greet -n "World" -l ja --format json +{ + "greeting": "こんにちは, World", + "lang": "ja" +} +``` + +### Output Behavior + +The CLI command output follows these specifications: + +- **Default Output**: Displays only the specified field's value +- **`--format=json` option**: Shows the full JSON response like the API endpoint +- **Error Messages**: Displayed in standard error (stderr) +- **HTTP Status Code Mapping**: Maps to exit codes (0: success, 1: client error, 2: server error) + +## Distribution Methods + +Commands created with BEAR.Cli can be distributed via Homebrew in the following two ways: + +### 1. Distribution via Local Formula + +When testing a development version: + +```bash +$ brew install --formula ./var/homebrew/greet.rb +``` + +This method is suitable in the following cases: +- Private projects +- Testing during development +- Distribution of internal tools + +### 2. Distribution via Homebrew Tap + +A method to widely distribute using a public repository: + +```bash +$ brew tap your-vendor/greet +$ brew install your-vendor/greet +``` + +This method is suitable in the following cases: +- Open-source projects +- Distribution of public tools +- Providing continuous updates + +#### Testing Development Version + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +``` + +#### Stable Release + +1. Create a tag: + +```bash +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 +``` + +2. Update the formula: + +```diff + class Greet < Formula ++ desc "Your CLI tool description" ++ homepage "https://github.com/your-vendor/your-project" ++ url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" ++ sha256 "..." # Write the hash value obtained from the command below ++ version "0.1.0" +- head "https://github.com/your-vendor/your-project.git", branch: "main" + + depends_on "php@8.1" + depends_on "composer" + end +``` + +You can add dependencies like databases to the formula as needed. However, it's recommended to handle environment setup like database initialization with a `bin/setup` script. + +3. Obtain SHA256 hash: + +```bash +# Download tarball from GitHub and compute hash +$ curl -sL https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256 +``` + +4. Create a Homebrew Tap: + +Setup for GitHub CLI is required: +- [Install GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) +- [Authenticate GitHub CLI](https://cli.github.com/manual/gh_auth_login) + +```bash +# Authenticate with GitHub CLI +$ gh auth login + +# The public repository name must start with homebrew- +$ gh repo create your-vendor/homebrew-greet --public --clone +$ cd homebrew-greet +``` + +5. Place and Publish the Formula: + +```bash +$ cp /path/to/project/var/homebrew/greet.rb . +$ git add greet.rb +$ git commit -m "Add formula for greet command" +$ git push +``` + +6. Installation and Distribution: + +End users can start using the tool with just the following commands. Since PHP environments and dependency packages are installed automatically, users don't need to worry about environment setup: + +```bash +$ brew tap your-vendor/greet # The homebrew- prefix is omitted +$ brew install your-vendor/greet + +# Ready to use immediately +$ greet --version +greet version 0.1.0 +``` + +## Customizing the Formula + +If necessary, you can edit the formula using the `brew edit` command: + +```bash +$ brew edit your-vendor/greet +``` + +```ruby +class Greet < Formula + desc "Your CLI tool description" + homepage "https://github.com/your-vendor/your-project" + url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" + sha256 "..." # SHA256 of the tgz + version "0.1.0" + + depends_on "php@8.1" # Specify PHP version + depends_on "composer" + + # Add if your application requires + # depends_on "mysql" + # depends_on "redis" +end +``` + +## Version Management + +To pin to a specific version: + +```bash +# Pin version +$ brew pin your-vendor/greet + +# Unpin +$ brew unpin your-vendor/greet +``` + +## Deployment + +For continuous deployment, the following steps are recommended: + +1. Verification in Development Environment + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +$ greet --version # Check version +$ greet --help # Check help +``` + +2. Release and Deployment + +```bash +# Create version tag +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 + +# Update Homebrew tap +$ cp var/homebrew/greet.rb /path/to/homebrew-tap/Formula/ +$ cd /path/to/homebrew-tap +$ git add Formula/greet.rb +$ git commit -m "Release greet v0.1.0" +$ git push origin main +``` + +3. Verify Installation + +```bash +$ brew update +$ brew install your-vendor/greet +$ greet --version # Confirm the new version +``` + +## Clean Architecture + +BEAR.Cli demonstrates the strengths of Resource-Oriented Architecture (ROA) and Clean Architecture. In line with the Clean Architecture principle that "UI is a detail," you can add a new adapter, CLI, to the same resource in addition to the web interface. + +Furthermore, BEAR.Cli not only supports the creation of commands but also supports distribution and updates via Homebrew. This allows end-users to start using the tool with just one command, utilizing it like a native UNIX command without being aware of the existence of PHP or BEAR.Sunday. + +Also, the CLI tool can be version-managed and updated independently from the application repository. This enables you to maintain stability and continuous updates as a command-line tool without being affected by the evolution of the API. This is a new form of API provision realized through the combination of Resource-Oriented Architecture and Clean Architecture. + diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md new file mode 100644 index 00000000..fbb33dcc --- /dev/null +++ b/manuals/1.0/ja/325.cli.md @@ -0,0 +1,334 @@ +--- +layout: docs-ja +title: コマンドラインインターフェイス (CLI) +category: Manual +permalink: /manuals/1.0/ja/cli.html +--- +# コマンドラインインターフェイス (CLI) + +BEAR.Sundayのリソース指向アーキテクチャ（ROA）は、アプリケーションのあらゆる機能をURIでアドレス可能なリソースとして表現します。このアプローチにより、Webに限らず様々な方法でリソースにアクセスできます。 + +```bash +$ php page.php '/greeting?name=World&lang=ja' +{ + "greeting": "こんにちは, World", + "lang": "ja" +} +``` + +BEAR.Cliは、このようなリソースをネイティブなCLIコマンドに変換し、Homebrewで配布可能にするツールです： + + +```bash +$ greet -n "World" -l ja +こんにちは, World +``` + +追加のコードを書くことなく、既存のアプリケーションリソースを標準的なCLIツールとして再利用できます。Homebrewを通じた配布により、PHPやBEAR.Sundayで動作していることを知ることなく、一般的なコマンドラインツールと同じように利用できます。 + +## インストール + +Composerでインストールします。 + +```bash +composer require bear/cli +``` + +## 基本的な使い方 + +### リソースへのCLI属性の追加 + +リソースクラスにCLI属性を追加して、コマンドラインインターフェースを定義します。 + +```php +use BEAR\Cli\Attribute\Cli; +use BEAR\Cli\Attribute\Option; + +class Greeting extends ResourceObject +{ + #[Cli( + name: 'greet', + description: 'Say hello in multiple languages', + output: 'greeting' + )] + public function onGet( + #[Option(shortName: 'n', description: 'Name to greet')] + string $name, + #[Option(shortName: 'l', description: 'Language (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; + } +} +``` + +### CLIコマンドとフォーミュラの生成 + +```bash +$ vendor/bin/bear-cli-gen MyVendor.MyProject +# 生成されたファイル: +# bin/cli/greet 　 # CLIコマンド +# var/homebrew/greet.rb # Homebrewフォーミュラ + + +## コマンドの使用方法 + +生成されたコマンドは以下のような標準的なCLI機能を提供します： + +### ヘルプの表示 + +```bash +$ greet --help +Say hello in multiple languages + +Usage: greet [options] + +Options: + --name, -n Name to greet (required) + --lang, -l Language (en, ja, fr, es) (default: en) + --help, -h Show this help message + --version, -v Show version information + --format Output format (text|json) (default: text) +``` + +### バージョン情報の表示 + +```bash +$ greet --version +greet version 0.1.0 +``` + +### 基本的な使用例 + +```bash +# 基本的な挨拶 +$ greet -n "World" +Hello, World + +# 言語を指定 +$ greet -n "World" -l ja +こんにちは, World + +# 短いオプション +$ greet -n "World" -l fr +Bonjour, World + +# 長いオプション +$ greet --name "World" --lang es +¡Hola, World +``` + +### JSON出力 + +```bash +$ greet -n "World" -l ja --format json +{ + "greeting": "こんにちは, World", + "lang": "ja" +} +``` + +### 出力の挙動 + +CLIコマンドの出力は以下の仕様に基づきます： + +- **デフォルト出力**: 指定されたフィールドの値のみを表示 +- **`--format=json` オプション**: APIエンドポイントと同様に、フルJSONレスポンスを表示 +- **エラーメッセージ**: 標準エラー出力（stderr）に表示 +- **HTTPステータスコードのマッピング**: 終了コードにHTTPステータスコードをマップ（0: 成功、1: クライアントエラー、2: サーバーエラー） + +## 配布方法 + +BEAR.Cliで作成したコマンドは、以下の2つの方法でHomebrewを通じて配布できます： + +### 1. ローカルフォーミュラによる配布 + +開発版をテストする場合： + +```bash +$ brew install --formula ./var/homebrew/greet.rb +``` + +この方法は以下の場合に適しています： +- プライベートプロジェクト +- 開発中のテスト +- 社内ツールの配布 + +### 2. Homebrewタップによる配布 + +公開リポジトリを使用して広く配布する方法です： + +```bash +$ brew tap your-vendor/greet +$ brew install your-vendor/greet +``` + +この方法は以下の場合に適しています： +- オープンソースプロジェクト +- 公開ツールの配布 +- 継続的なアップデートの提供 + +#### 開発版のテスト + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +``` + +#### 安定版のリリース + +1. タグを作成： +```bash +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 +``` + +2. フォーミュラを更新： +```diff + class Greet < Formula ++ desc "Your CLI tool description" ++ homepage "https://github.com/your-vendor/your-project" ++ url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" ++ sha256 "..." # 以下のコマンドで取得したハッシュ値を記述 ++ version "0.1.0" +- head "https://github.com/your-vendor/your-project.git", branch: "main" + + depends_on "php@8.1" + depends_on "composer" + end +``` + +フォーミュラには必要に応じてデータベースなどの依存関係を追加できます。ただし、データベースのセットアップなどの環境構築は `bin/setup` スクリプトで行うことを推奨します。 + +3. SHA256ハッシュの取得： +```bash +# GitHubからtarballをダウンロードしてハッシュを計算 +$ curl -sL https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256 +``` + +4. Homebrewタップの作成: + +GitHub CLIのセットアップが必要です： +- [GitHub CLI のインストール](https://docs.github.com/ja/github-cli/github-cli/about-github-cli) +- [GitHub CLI の認証](https://cli.github.com/manual/gh_auth_login) + +```bash +# GitHub CLIで認証 +$ gh auth login + +# 公開リポジトリ名はhomebrew-で始める必要があります +$ gh repo create your-vendor/homebrew-greet --public --clone +$ cd homebrew-greet +``` + +5. フォーミュラの配置と公開： +```bash +$ cp /path/to/project/var/homebrew/greet.rb . +$ git add greet.rb +$ git commit -m "Add formula for greet command" +$ git push +``` + +6. インストールと配布: + +エンドユーザーは以下のコマンドだけでツールを使い始めることができます。PHP環境や依存パッケージのインストールは自動的に行われるため、ユーザーが環境構築について心配する必要はありません： + +```bash +$ brew tap your-vendor/greet # homebrew-プレフィックスは省略 +$ brew install your-vendor/greet + +# すぐに使用可能 +$ greet --version +greet version 0.1.0 +``` + +## フォーミュラのカスタマイズ + +必要に応じて、`brew edit` コマンドでフォーミュラを編集できます： + +```bash +$ brew edit your-vendor/greet +``` + +```ruby +class Greet < Formula + desc "Your CLI tool description" + homepage "https://github.com/your-vendor/your-project" + url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" + sha256 "..." # tgzのSHA256 + version "0.1.0" + + depends_on "php@8.1" # PHPバージョンの指定 + depends_on "composer" + + # アプリケーションが必要とする場合は追加 + # depends_on "mysql" + # depends_on "redis" +end +``` + +## バージョン管理 + +特定のバージョンに固定する場合： + +```bash + +# バージョンの固定 +$ brew pin your-vendor/greet + +# 固定解除 +$ brew unpin your-vendor/greet +``` + +## デプロイ + +継続的デプロイメントのために、以下のような手順が推奨されます： + +1. 開発環境での確認 + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +$ greet --version # バージョン確認 +$ greet --help # ヘルプの確認 +``` + +2. リリースとデプロイ + +```bash +# バージョンタグの作成 +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 + +# Homebrewタップの更新 +$ cp var/homebrew/greet.rb /path/to/homebrew-tap/Formula/ +$ cd /path/to/homebrew-tap +$ git add Formula/greet.rb +$ git commit -m "Release greet v0.1.0" +$ git push origin main +``` + +3. インストールの確認 + +```bash +$ brew update +$ brew install your-vendor/greet +$ greet --version # 新しいバージョンの確認 +``` + +## クリーンアーキテクチャ + +BEAR.Cliは、リソース指向アーキテクチャ（ROA）とクリーンアーキテクチャの強みを実証しています。クリーンアーキテクチャが目指す「UIは詳細である」という原則に従い、同じリソースに対してWebインターフェースだけでなく、CLIという新しいアダプターを追加できます。 + +さらに、BEAR.Cliはコマンドの作成だけでなく、Homebrewによる配布や更新もサポートしています。これにより、エンドユーザーはコマンド一つでツールを使い始めることができ、PHPやBEAR.Sundayの存在を意識せず、ネイティブなUNIXコマンドのように扱えます。 + +また、CLIツールはアプリケーションリポジトリから独立してバージョン管理および更新が可能です。そのため、APIの進化に影響されず、コマンドラインツールとしての安定性と継続的なアップデートを保つことができます。これは、リソース指向アーキテクチャとクリーンアーキテクチャの組み合わせにより実現した、APIの新しい提供形態です。