PHP アーカイバーの「Box2」を使って Phar ファイルを作成（アーカイブ）する際の、ビルドの設定（box.jsonの設定内容）などの参考情報です。$ ./box.phar help build の内容（適宜翻訳中）ですが、まとまった資料がなかったので記事に起こしました。

使い方:

build [-c|--configuration="..."]

オプション:

オプション	説明
--configuration (-c)	設定ファイルを指定する場合のパス
--help (-h)	このヘルプを表示
--quiet (-q)	メッセージを非表示
--verbose (-v	vv
--version (-V)	box.pharのバージョン
--ansi	ANSI で出力を強制
--no-ansi	ANSI 出力を無効
--no-interaction (-n)	対話型の質問をさせない

ヘルプ:

build コマンドは、さまざまな設定に基づいて新しい Phar （PHPのアーカイブ）ファイルをビルドします。

このコマンドは、Phar のパッケージング（アーカイブ）に必要な設定をロードするために設定ファイルを必要とします。設定ファイルが --configuration | -c オプションで指定されていない場合は、次のファイルのいずれかが順番に使用されます。

box.json
box.json.dist

設定ファイルのオプション項目：

設定ファイルは、実際にはテキスト・ファイルに保存された JSON ファイルです。また、以下の設定項目は、すべてオプションです。

box.json

   {
     "algorithm": ?,
     "alias": ?,
     "banner": ?,
     "banner-file": ?,
     "base-path": ?,
     "blacklist": ?,
     "bootstrap": ?,
     "chmod": ?,
     "compactors": ?,
     "compression": ?,
     "datetime": ?,
     "datetime_format": ?,
     "directories": ?,
     "directories-bin": ?,
     "extract": ?,
     "files": ?,
     "files-bin": ?,
     "finder": ?,
     "finder-bin": ?,
     "git-version": ?,
     "intercept": ?,
     "key": ?,
     "key-pass": ?,
     "main": ?,
     "map": ?,
     "metadata": ?,
     "mimetypes": ?,
     "mung": ?,
     "not-found": ?,
     "output": ?,
     "replacements": ?,
     "shebang": ?,
     "stub": ?,
     "web": ?
   }

algorithm

algorithm（値：string, integer）の設定は、Phar の構築時に使用する署名アルゴリズムです。（Phar::setSignatureAlgorithm()）

これは、整数値（定数の値）、または Phar 定数の名前です。以下は、ヘルプにリストされた署名アルゴリズム一覧です。

MD5 (Phar::MD5)
SHA1 (Phar::SHA1)
SHA256 (Phar::SHA256)
SHA512 (Phar::SHA512)
OPENSSL (Phar::OPENSSL)

alias

alias（値：string）の設定は、新しいスタブを生成して Phar::mapPhar() メソッドを呼び出すときに使用されます。これにより、Phar 内のファイルを参照しやすくなります。

annotations

annotations（値：boolean, object）の設定は、PHP ソースコード内の注釈を圧縮するのに使用されます。 true に設定すると、PHPDoc スタイルの注釈はすべて PHP ファイルに圧縮されます。また、無視する注釈のリストを指定することもでき、注釈を保護しながら残りを削除できます。

box.json

   {
       "annotations": {
           "ignore": [
               "author",
               "package",
               "version",
               "see"
           ]
       }
   }

以下の Web サイトで、一般的に無視される注釈の一覧を確認することができます。

banner (stub-banner)

banner（値：string）の設定は、新しいスタブが生成されたときに使用されるバナーコメントです。この設定の値は、自動的に実行されるため、コメントブロック内に囲まれている必要はありません。

banner-file

banner-file（値：string）の設定は、コメントを含むファイルへのパスを除いて、banner と同じです。 banner と同様に、コメントはコメントブロックに囲まれていてはなりません。

base-path

base-path（値：string）の設定は、すべての相対ファイルパスを解決する場所を指定するために使用します。しかし、これはビルドされた Phar がどこに格納（出力）されるかには影響しません（outputを参照）。デフォルトでは、基本パスは設定ファイルを含むディレクトリです。

blacklist

blacklist（値：string, array）の設定は、追加しないファイルのリストです。ブラックリストに載っているファイルは、directories, directories-bin, files, files-bin, finder, finder-bin など、他の利用可能な設定を使って見つかったファイルが対象になります。また、ディレクトリセパレータはプラットフォーム固有のものに自動的に修正されます。

ベースディレクトリのパスが /home/user/project であると仮定して、以下の設定が設定ファイルでされている場合：

box.json

   {
       "blacklist": [
           "path/to/file/1"
           "path/to/file/2"
       ],
       "directories": ["src"]
   }

次のファイルがブラックリストに登録されます。

/home/user/project/src/path/to/file/1
/home/user/project/src/path/to/file/2

以下のファイルはブラックリストには登録されません。

/home/user/project/src/another/path/to/file/1
/home/user/project/src/another/path/to/file/2

bootstrap

bootstrap（値：string）の設定では、build コマンドまたは add コマンドが使用される前に読み込む PHP ファイルを指定できます。これは、compactors オプションで設定されたサードパーティ製の圧縮（minify）クラスでファイルコンテンツを圧縮する場合に便利です。

chmod

chmod（値：string）の設定は、新しく構築された Phar ファイルのアクセス権を変更するために使用されます。文字列には8進値：0755 が含まれています。モードを10進数で指定する場合は、モードの前に接頭語の「0（ゼロ）」を付ける必要があります。

compactors

compactors（値：string, array）の設定は、登録が必要なコンパクター（ファイル圧縮, minify）クラスのリストです。ファイル圧縮（minify）クラスを使用して、特定のファイルタイプのサイズを縮小します。以下は簡単な例です：

class-mycompactor.php

   use Herrera\Box\Compactor\CompactorInterface;

   class MyCompactor implements CompactorInterface
   {
       public function compact($contents)
       {
           return trim($contents);
       }

       public function supports($file)
       {
           return (bool) preg_match('/\.txt/', $file);
       }
   }

また、Box には次のコンパクター・クラスが含まれています：

compression

compression（値：string, integer）の設定は、Phar の構築時に使用する圧縮アルゴリズムです。圧縮は Phar 内の個々のファイルに影響し、Phar 全体ではありません（Phar::compressFiles()）。

以下は、ヘルプページにリストされている署名アルゴリズムのリストです。

BZ2 (Phar::BZ2)
GZ (Phar::GZ)
NONE (Phar::NONE)

directories

directories（値：string, array）の設定は、base-path を基準にしたディレクトリパスのリストです。これらのパス内の.php で終わるすべてのファイルは自動的に圧縮、そしてプレースホルダ値が置き換えられて Phar に追加されます。ブラックリスト設定にリストされているファイルは追加されません。

directories-bin

directories-bin（値：string, array）の設定は directories に似ていますが、すべてのファイルタイプが変更されずに Phar に追加されます。これは、イメージやその他のバイナリデータを含むディレクトリに適しています。

extract

extract（boolean）の設定は、生成されたスタブが phar を抽出するためにクラスを含むべきかどうかを決定します。このクラスはpharが利用できない場合に使用されます。（これはスタブのファイルのサイズを増やします）

files

files（値：string, array）の設定は、base-path を基準にしたファイルパスのリストです。指定された各ファイルは、圧縮（minify）とプレースホルダーの置き換えの後、Pharに追加されます。この設定はブラックリスト設定の影響を受けません。

files-bin

The files-bin (string, array) setting is similar to files, except that all files are added to the Phar unmodified. This is suitable for files such as images or those that contain binary data.

finder

The finder (array) setting is a list of JSON objects. Each object key is a name, and each value an argument for the methods in the Symfony\Component\Finder\Finder class. If an array of values is provided for a single key, the method will be called once per value in the array.
Note that the paths specified for the "in" method are relative to base-path.

finder-bin

The finder-bin (array) setting performs the same function, except all files found by the finder will be treated as binary files, leaving them unmodified.

It may be useful to know that Box imports files in the following order:

finder
finder-bin
directories
directories-bin
files
files-bin

datetime

The datetime (string) setting is the name of a placeholder value that will be replaced in all non-binary files by the current datetime.

Example: 2015-01-28 14:55:23

datetime_format

The datetime_format (string) setting accepts a valid PHP date format. It can be used to change the format for the datetime setting.

Example: Y-m-d H:i:s

git-commit

The git-commit (string) setting is the name of a placeholder value that will be replaced in all non-binary files by the current Git commit hash of the repository.

Example: e558e335f1d165bc24d43fdf903cdadd3c3cbd03

git-commit-short

The git-commit-short (string) setting is the name of a placeholder value that will be replaced in all non-binary files by the current Git short commit hash of the repository.

Example: e558e33

git-tag

The git-tag (string) setting is the name of a placeholder value that will be replaced in all non-binary files by the current Git tag of the repository.

Examples:

2.0.0

2.0.0-2-ge558e33

git-version

The git-version (string) setting is the name of a placeholder value that will be replaced in all non-binary files by the one of the following (in order):

The git repository's most recent tag.
The git repository's current short commit hash.

The short commit hash will only be used if no tag is available.

intercept

The intercept (boolean) setting is used when generating a new stub. If setting is set to true, the Phar::interceptFileFuncs(); method will be called in the stub.

key

The key (string) setting is used to specify the path to the private key file. The private key file will be used to sign the Phar using the OPENSSL signature algorithm. If an absolute path is not provided, the path will be relative to the current working directory.

key-pass

The key-pass (string, boolean) setting is used to specify the passphrase for the private key. If a string is provided, it will be used as is as the passphrase. If true is provided, you will be prompted for the passphrase.

main

The main (string) setting is used to specify the file (relative to base-path) that will be run when the Phar is executed from the command line. If the file was not added by any of the other file adding settings, it will be automatically added after it has been compacted and had its placeholder values replaced. Also, the #! line will be automatically removed if present.

map

The map (array) setting is used to change where some (or all) files are
stored inside the phar. The key is a beginning of the relative path that
will be matched against the file being added to the phar. If the key is
a match, the matched segment will be replaced with the value. If the key
is empty, the value will be prefixed to all paths (except for those
already matched by an earlier key).

box.json

   {
     "map": [
       { "my/test/path": "src/Test" },
       { "": "src/Another" }
     ]
   }

(with the files)

my/test/path/file.php
my/test/path/some/other.php
my/test/another.php

(will be stored as)

src/Test/file.php
src/Test/some/other.php
src/Another/my/test/another.php

metadata

The metadata (any) setting can be any value. This value will be stored as metadata that can be retrieved from the built Phar (Phar::getMetadata()).

mimetypes

The mimetypes (object) setting is used when generating a new stub. It is a map of file extensions and their mimetypes. To see a list of the default mapping, please visit:

http://www.php.net/manual/en/phar.webphar.php

mung

The mung (array) setting is used when generating a new stub. It is a list of server variables to modify for the Phar. This setting is only useful when the web setting is enabled.

not-found

The not-found (string) setting is used when generating a new stub. It specifies the file that will be used when a file is not found inside the Phar. This setting is only useful when web setting is enabled.

The output (string) setting specifies the file name and path of the newly built Phar. If the value of the setting is not an absolute path, the path will be relative to the current working directory.

The replacements (object) setting is a map of placeholders and their values. The placeholders are replaced in all non-binary files with the specified values.

The shebang (string) setting is used to specify the shebang line used when generating a new stub. By default, this line is used:

#!/usr/bin/env php

The shebang line can be removed altogether if false or an empty string is provided.

The stub (string, boolean) setting is used to specify the location of a stub file, or if one should be generated. If a path is provided, the stub file will be used as is inside the Phar. If true is provided, a new stub will be generated. If false (or nothing) is provided, the default stub used by the Phar class will be used.

The web (boolean) setting is used when generating a new stub. If true is provided, Phar::webPhar() will be called in the stub.

PHP の Phar アーカイバ「BOX v2」の build コマンドと box.json で利用できる設定

使い方:

オプション:

ヘルプ:

設定ファイルのオプション項目：

algorithm

alias

annotations

banner (stub-banner)

banner-file

base-path

blacklist

bootstrap

chmod

compactors

compression

directories

directories-bin

extract

files

files-bin

finder

finder-bin

datetime

datetime_format

git-commit

git-commit-short

git-tag

git-version

intercept

key

key-pass

main

map

metadata

mimetypes

mung

not-found