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

TL;DR

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

$ box compile

利用例

$ 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 の各種インストール方法

Homebrewでインストール

$ brew tap humbug/box && brew install box

composerでインストール

$ composer global require humbug/box

Phiveでインストール

$ phive install humbug/box --force-accept-unsigned

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」ですが、Kevin Herrera さんの「box-project」から、Théo FIDRY さんの「humbug/humbug」にフォークされ、先日（2018/09/10に） RC が取れてめでたく「BOX v3.0.0」になりました。

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

Phar って何?

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

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

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

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

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

変更内容

BOX 2.7 から 3.0 への主な変更内容はリファクタリングがメインですが、具体的な変更の詳細は「UPGRADE.md」をご覧ください。

• PHP v7 専用になりました。
• ２倍以上速くなりました。
• 設定ファイルは必須でなくなりました。（box.json box.json.distなど）
• Phar にインクルードするファイルを composer.json などのファイルから自動検知するようになりました。
• php.ini で phar.readonly や ulimit の変更が不要になりました。
• PHP-Scoperを同梱できるようになりました。
• Requirements checkerを同梱できるようになりました。
• buildコマンドからcompileコマンドに名称が変更になりました

現在は、開発した PHP の環境依存を吸収させるために Dockerfile も出力できるように開発が進められています。

コマンド一覧

$ 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

コマンド一覧（筆者翻訳）

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 署名を認証確認する

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

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 化する、至極シンプルな具体例です。

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!

複数ファイルをアーカイブしたい場合は、アーカイブに内包させるファイルを指定するために設定ファイルの設置が必要になります。（デフォルトの場合は box.json もしくは box.json.dist）

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

• BOX v3 ドキュメント一覧 @ GitHub
• BOX v3 設定ファイル（box.json）の項目一覧 @ GitHub
• Qiita の BOX 関連記事一覧 @ Google