Edited at

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


TL;DR


インストール


Homebrewでインストール

$ brew tap humbug/box

$ brew install box
$ box -v


Brewを使わない単体インストール

$ curl -LSs https://keinos.github.io/Phar_Box3_installer/installer.php | php

$ ./box.phar -v


利用例

$ ls

box.phar index.php
$ php index.php
Hello Qiita!
$ ./box.phar --version
Box version 3.1.1@6dc36fd 2018-10-09 21:42:47 UTC
$ ./box.phar compile
(省略)
$ ls
box.phar index.phar index.php
$ php index.phar
Hello Qiita!


TS;DR

Phar って何?


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


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

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

PHP 5.3 以降で使えるようになったにも関わらず、マニュアルがとてもわかりづらく、簡単に利用できるというものではありませんでした。むしろ Qiita くらいにしか良い情報がないくらいの勢いです。

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


永らくメンテナンスされていなかった Phar アーカイバ「Box2」ですが、メンテナが「box-project」から「humbug」に移行され、先日(2018/09/10に) RC が取れてめでたく「BOX v3.0.0」になりました


変更内容

基本的にはリファクタリングがメインですが、以下が主な変更です。

BOX 2.7 から 3.0 への具体的な変更の詳細は「UPGRADE.md」をご覧ください。


  • PHP v7 専用になりました。

  • 2倍以上速くなりました。

  • 設定ファイルは必須でなくなりました。(box.json box.json.distなど)

  • Phar にインクルードするファイルを composer.json などのファイルから自動検知するようになりました。


  • php.iniphar.readonlyulimit の変更が不要になりました。


  • PHP-Scoperを同梱できるようになりました。


  • Requirements checkerを同梱できるようになりました。


  • buildコマンドからcompileコマンドに名称が変更になりました

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


コマンド一覧

$ 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 2つの 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 の設定を元にアーカイブされます。