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

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

---

# 使い方:
    build [-c|--configuration="..."]

# オプション:
|オプション|説明|
|:---|:---|
| --configuration (-c)  |設定ファイルを指定する場合のパス|
| --help (-h)           |このヘルプを表示|
| --quiet (-q)          |メッセージを非表示|
| --verbose (-v|vv|vvv) |表示の冗長レベル：I通常出力の場合は1、冗長出力の場合は2、デバッグの場合は3|
| --version (-V)        |box.pharのバージョン|
| --ansi                |ANSI で出力を強制|
| --no-ansi             |ANSI 出力を無効|
| --no-interaction (-n) |対話型の質問をさせない|

# ヘルプ:

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

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

1. `box.json`
2. `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 サイトで、一般的に無視される注釈の一覧を確認することができます。

   https://github.com/herrera-io/php-annotations

## 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`](https://github.com/box-project/box2/blob/2.0/src/lib/KevinGH/Box/Command/Build.php) コマンドまたは [`add`](https://github.com/box-project/box2/blob/2.0/src/lib/KevinGH/Box/Command/Add.php) コマンドが使用される前に読み込む 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` には次のコンパクター・クラスが含まれています：

- [`Herrera\Box\Compactor\Json`](https://github.com/box-project/box2-lib/blob/master/src/lib/Herrera/Box/Compactor/Json.php)
- [`Herrera\Box\Compactor\Php`](https://github.com/box-project/box2-lib/blob/master/src/lib/Herrera/Box/Compactor/Php.php)

## 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)


   1. my/test/path/file.php
   2. my/test/path/some/other.php
   3. my/test/another.php


 (will be stored as)


   1. src/Test/file.php
   2. src/Test/some/other.php
   3. 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.