PHP の Phar アーカイバー「BOX」が v3 になった（ brew でもインストール可能に）

## TL;DR

### BOX3 で Phar アーカイブを作成する方法

```
$ box compile
```

### 利用例

```shell-session
$ ls
box.phar    index.php

$ ./box.phar --version
Box version 3.1.1@6dc36fd 2018-10-09 21:42:47 UTC

$ php ./index.php
Hello Qiita!

$ # アーカイブ作成
$ ./box.phar compile
（省略）

$ ls
box.phar    index.phar    index.php

$ # Phar アーカイブを実行
$ php index.phar
Hello Qiita!
```

### BOX3 の各種インストール方法

```shell-session:Homebrewでインストール
$ brew tap humbug/box && brew install box
```

```shell-session:composerでインストール
$ composer global require humbug/box
```

```shell-session:Phiveでインストール
$ phive install humbug/box --force-accept-unsigned
```

```shell-session:Brewを使わない単体インストール
$ # "box.phar" がダウンロードされるので "box" としてパスの通ったディレクトリに移動してください
$ curl -LSs https://keinos.github.io/Phar_Box3_installer/installer.php | php
```

- ~~手動でダウンロード: https://github.com/humbug/box/releases~~
- 手動でダウンロード: https://github.com/box-project/box/releases


## TS;DR

永らくメンテナンスされていなかった Phar アーカイバ「[Box2](https://github.com/box-project/box2)」ですが、[Kevin Herrera](https://github.com/kherge) さんの「<code>[box-project](https://github.com/box-project/)</code>」から、[Théo FIDRY](https://github.com/theofidry) さんの「<code>[humbug/humbug](https://github.com/humbug/humbug)</code>」にフォークされ、先日（2018/09/10に） RC が取れて**めでたく「[BOX v3.0.0](https://github.com/humbug/box/releases/tag/3.0.0)」になりました**。

2020/09/17 追記: <code>[humbug](https://github.com/humbug/)</code> さんの [BOX3 が本家の `box-project` に正式に移管](https://github.com/box-project/box/issues/453)され、`box-project` のメンテナに加わりました。これにより、[humbug/humbug](https://github.com/humbug/humbug) の BOX3 はアーカイブされ、今後は本家の [box-project/box](https://github.com/box-project/box) で開発が継続されます。つまり、最新の `box-project/box` が v3 になったと言うことです。

<details><summary>Phar って何?</summary><div>

> Phar アーカイブは、複数のファイルをひとつにまとめるための便利な仕組みです。 Phar アーカイブを使用すれば、PHP のアプリケーションをひとつのファイルとして配布できるようになります。 また、それをディスク上に展開しなくてもそのまま実行できるのです。 さらに、他のファイルと同様に PHP から phar アーカイブを実行することができます。 コマンドラインとウェブサーバー経由のどちらでも実行可能です。 phar は、いわば PHP アプリケーションにおける thumb drive のようなものです。 （[PHPマニュアルより](http://php.net/manual/ja/intro.phar.php)）

つまり、PHP で作った**アプリケーションやライブラリを単一のファイルで配布・利用できるようにしたもの**が `phar` ファイルです。

Java で言うところの `jar` ファイルのようなもので、Python で言えば ZIP 化したライブラリを `sys.path` のパス先に設置して `import` して利用するようなものです。

身近なところでは PHP のパッケージマネージャー `composer` の本体はこの形式で配布されています。PHP 5.3 以降で使えるようになったにも関わらず、マニュアルがとてもわかりづらく、簡単に利用できるというものではありませんでした。むしろ [Qiita くらいにしか良い情報がない](https://qiita.com/rana_kualu/items/d868604a1f54c2f93a7c)くらいの勢いです。

「BOX」は、この `phar` ファイルを手軽に作成するために作られたアプリ、つまり `Phar` アーカイバです。

</div></details>

### 変更内容

BOX 2.7 から 3.0 への主な変更内容はリファクタリングがメインですが、具体的な変更の詳細は「[UPGRADE.md](https://github.com/humbug/box/blob/master/UPGRADE.md#from-27-to-30)」をご覧ください。

- PHP v7 専用になりました。
- ２倍以上速くなりました。
- 設定ファイルは必須でなくなりました。（`box.json` `box.json.dist`など）
- Phar にインクルードするファイルを composer.json などのファイルから自動検知するようになりました。
- `php.ini` で `phar.readonly` や `ulimit` の変更が不要になりました。
- [`PHP-Scoper`](https://github.com/humbug/php-scoper)を同梱できるようになりました。
- [`Requirements checker`](https://github.com/humbug/box/blob/master/doc/requirement-checker.md#requirements-checker)を同梱できるようになりました。
- `build`コマンドから`compile`コマンドに名称が変更になりました

現在は、開発した PHP の環境依存を吸収させるために [Dockerfile も出力できる](https://github.com/humbug/box/blob/master/doc/docker.md)ように開発が進められています。

```shell-session:コマンド一覧
$ box list

    ____            
   / __ )____  _  __
  / __  / __ \| |/_/
 / /_/ / /_/ />  <  
/_____/\____/_/|_|  
                    

Box version 3.0.0@abc01b3 2018-09-10 12:36:36

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  build     Builds a new PHAR (deprecated, use "compile" instead)
  compile   Compile an application into a PHAR
  diff      Display the differences between all of the files in two PHARs
  help      Displays help for a command
  info      Displays information about the PHAR extension or file
  list      Lists commands
  process   Apply the registered compactors and replacement values on a file
  validate  Validates the configuration file
  verify    Verifies the PHAR signature
```
```shell-session:コマンド一覧（筆者翻訳）
Usage:
  command [オプション] [引数]

オプション:
  -h, --help            このヘルプを表示
  -q, --quiet           メッセージを何も表示させない
  -V, --version         BOX バージョンを表示
      --ansi            ANSI 出力を強制
      --no-ansi         ANSI 出力を無効にする
  -n, --no-interaction  ユーザ入力を求めさせない
  -v|vv|vvv, --verbose  表示の詳細レベルをあげる：1 一般情報表示、2 詳細情報表示、3 デバッグ情報表示

利用可能なコマンド:
  build     新い PHAR をビルドする（廃止されました。"compile" を代わりに利用ください）
  compile   アプリケーションを PHAR にコンパイルする
  diff      ２つの PHAR 間を比較して差分を表示する
  help      コマンドのヘルプを表示する
  info      PHAR ファイルもしくは拡張（PHAR extension）の情報を表示する
  list      コマンドの一覧を表示する
  process   登録された圧縮アルゴリズム（compactors）を適用、もしくはファイル内の値置換処理を適用する
  validate  設定ファイルの設定内容を検証する
  verify    PHAR 署名を認証確認する
```

```shell-session:compileのヘルプ
$ # 下記は `box compile -h` でも可
$ box help compile
Description:
  Compile an application into a PHAR

Usage:
  compile [options]

Options:
  -c, --config=CONFIG            The alternative configuration file path.
      --debug                    Dump the files added to the PHAR in a `.box_dump` directory
      --no-parallel              Disable the parallel processing
      --no-restart               Do not restart the PHP process. Box restarts the process by default to disable xdebug and set `phar.readonly=0`
      --dev                      Skips the compression step
      --no-config                Ignore the config file even when one is specified with the --config option
  -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
  -h, --help                     Display this help message
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
      --ansi                     Force ANSI output
      --no-ansi                  Disable ANSI output
  -n, --no-interaction           Do not ask any interactive question
  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The compile command will compile code in a new PHAR based on a variety of settings.
  
    This command relies on a configuration file for loading
    PHAR packaging settings. If a configuration file is not
    specified through the --config|-c option, one of
    the following files will be used (in order): box.json,
    box.json.dist
  
  The configuration file is actually a JSON object saved to a file. For more
  information check the documentation online:
  
    https://github.com/humbug/box
```
```shell-session:compileのヘルプ（筆者翻訳）
$ box help compile
機能概要:
  PHP アプリケーションを PHAR にコンパイルします

使い方:
  compile [オプション]

オプション:
  -c, --config=CONFIG            代替設定ファイルのパスを指定する
      --debug                    PHAR に追加されたファイルを `.box_dump` ディレクトリにダンプ出力する
      --no-parallel              並列処理を無効にする
      --no-restart               PHP プロセスを再起動させない。Box はデフォルトで `phar.readonly=0` を設定しプロセスを再起動させて xdebug を無効にします。
      --dev                      圧縮処理をスキップします
      --no-config                `--config` オプションを指定していたとしても設定ファイルを無視する
  -d, --working-dir=WORKING-DIR  指定された場合、作業ディレクトリとして利用する
  -h, --help                     このヘルプメッセージを表示
  -q, --quiet                    メッセージを何も表示させない
  -V, --version                  BOX バージョンを表示
      --ansi                     ANSI 出力を強制
      --no-ansi                  ANSI 出力を無効にする
  -n, --no-interaction           ユーザ入力を求めさせない
  -v|vv|vvv, --verbose           表示の詳細レベルをあげる：1 一般情報表示、2 詳細情報表示、3 デバッグ情報表示

ヘルプ:
  `compile` コマンドは、設定にあわせてコードのコンパイルを行い、新しい PHAR を作成します。
  
    このコマンドは、PHAR のパッケージング設定を設定ファイルに依存して読
    み込みます。--config|-c オプションで設定ファイルが指定されていない
    場合、以下のファイルを順に検索して利用しようとします。

    box.json, box.json.dist
  
  設定ファイルは JSON 形式（JSON オブジェクトをファイルに出力したもの）です。詳細に関して
  は、下記オンライン・ドキュメントを参照ください。
  
    https://github.com/humbug/box

```

### 使ってみる

"Hello World" の単体ファイルを `phar` 化する、至極シンプルな具体例です。

```shell-session:bash
$ # 作業ディレクトリの作成
$ mkdir sample
$ cd sample
$ # Phar アーカイバーのダウンロード
$ curl -LSs https://keinos.github.io/Phar_Box3_installer/installer.php | php
（省略）
$ # サンプルファイルの作成（Hello World）
$ vi index.php
（省略）
$ # サンプルファイルの動作確認
$ php index.php
Hello World!
$ # アーカイブの作成
$ ./box.phar compile
 （省略）
$ # 一覧の確認
$ ls
box.phar    index.phar    index.php
$ # アーカイブの動作確認
$ php index.phar
Hello World!
```

複数ファイルをアーカイブしたい場合は、アーカイブに内包させるファイルを指定するために[設定ファイル](https://github.com/humbug/box/blob/master/doc/configuration.md)の設置が必要になります。（デフォルトの場合は `box.json` もしくは `box.json.dist`）

Composer を使って `autoload`（ダイナミックに `include`）している場合は、`composer.json` の設定を元にアーカイブされます。


- [BOX v3 ドキュメント一覧](https://github.com/humbug/box/tree/master/doc) @ GitHub
- [BOX v3 設定ファイル（box.json）の項目一覧](https://github.com/humbug/box/blob/master/doc/configuration.md) @ GitHub
- [Qiita の BOX 関連記事一覧](https://www.google.co.jp/search?q=site:qiita.com+phar+php) @ Google