PHP
バージョン管理
BOX
Phar

PHP アーカイバ「BOX2」と Git で自作 Phar アプリのバージョン番号更新

Pharアプリのバージョン情報やビルド日付を簡単に更新したい

PHP ファイルを Phar にアーカイブしてアプリを配布する際に、アプリのバージョンの更新が面倒な方は、「Box2」(Phar アーカイバー)と Git のコミットやタグ機能を使って管理してはいかがでしょう。

TL;DR

box.phar には PHP ファイルをアーカイブするとき、つまり Phar のビルド時に Git 情報をソース内の任意の文字列に置き換える機能があるbox.json のキーに置換対象の指定と、値に置換する文字列を指定する。[指定できる主なキー]

  • ビルドのソース:
   $version_build = '@build_version@';
   $date_build    = '@build_date@';
  • ビルドのアーカイブ内のソース:
   $version_build = '1b1973c';
   $date_build    = '2018-02-01 18:02:22';

box設定ファイル

box.json
{
    "chmod": "0755",
    "directories": [
        "src"
    ],
    "main": "src/index.php",
    "output": "./HelloWorld.phar",
    "stub": true,
    "git-version": "build_version", ←注目
    "datetime": "build_date" ←注目
}

アーカイブする(Pharに含める)ファイル

src/index.php
<?php

$version_app = '@build_version@'; //この値がアーカイブ時に自動置換される
$build_date  = '@build_date@';    //この値がアーカイブ時に自動置換される

echo "Hello world! (Build:${version_app} at ${build_date})" . PHP_EOL;

確認とビルド(アーカイブの作成)

$ # Git のコミット ID 確認 (最初の7桁が使われる)
$ git show -s --format=%H
1b1973c6453b505e7f6ca7344bfd159765b739aa
$
$ # 登録済みの Git タグの確認
$ git tag
$ # 通常のビルド
$ ./box.phar build -c ./box.json
$ ()
$ # アプリの実行
$ ./HelloWorld.phar
Hello world! (Build:1b1973c at 2018-02-01 21:22:12)
$
$ # Gitにタグをつけて再ビルド
$ git tag 1.0.0
$ ./box.phar build -c ./box.json
$ ()
$ # アプリの実行
$ ./HelloWorld.phar
Hello world! (Build:1.0.0 at 2018-02-01 21:26:15)

TS;DR

Box」とは、PHP のアーカイブ・ファイルである Phar ファイルを作ったり、既存の Phar ファイルを操作するのに便利な PHP コマンドライン・アプリケーションです。Phar クラスを使ってアーカイブに苦労された方は、「Box」を一度試してみる価値はあると思います。

「Box」のダウンロードとインストール

box.phar がない場合は下記のいずれかの方法でインストーラーをダウンロード&インストールして box.phar を作成してください。

  1. cURLを使ってダウンロード&インストール

    curl -LSs https://box-project.github.io/box2/installer.php | php
    
  2. https://box-project.github.io/box2/installer.php のファイルを別途ダウンロードし $php ./installer.php でインストール

インストールが行われると、Phar が作成可能かのチェックを行い、あなたの環境にあった box.phar(Pharアーカイバ) をカレント・ディレクトリに作成してくれます。

サンプルファイルの作成('Hello World' アプリ)

まずは "Hello World" アプリから始め、次に include/require 、クラスのオートロードと徐々に拡張して行くことをおすすめします。

以下のサンプルは、"Hello World!" を表示したのち、アプリのバージョンや Git のコミット情報を echo するサンプルです。

GitHub にもサンプルを公開していますので、そちらの方がピンとくるかもしれません。クローンして適当に編集&コミットしたのち、$git tag vXXXX で適当なバージョン(vXXXX)番号を付けて、ビルドしてみてください。

ディレクトリ構成

━ ./
 ┣━ src/
 ┃  ┗━ index.php
 ┣━ box.json
 ┗━ box.phar

./src/index.php

src/index.php
<?php

// 'box.json' で置き換え指定する文字列(@〜@)
$git_version      = '@git_version@';
$git_commit_long  = '@git_commit_long@';
$git_commit_short = '@git_commit_short@';
$git_tag          = '@git_tag@';
$date_build       = '@date_build@';

echo 'Hello world!' . PHP_EOL;

echo 'Git version       : ' . $git_version      . PHP_EOL;
echo 'Git commit(long)  : ' . $git_commit_long  . PHP_EOL;
echo 'Git commit(short) : ' . $git_commit_short . PHP_EOL;
echo 'Git tag           : ' . $git_tag          . PHP_EOL;
echo 'Date build        : ' . $date_build       . PHP_EOL;

./box.json

box.json
{
    "chmod": "0755",
    "directories": [
        "./src"
    ],
    "main": "src/index.php",
    "output": "./HelloWorld.phar",
    "stub": true,
    "git-version": "git_version",
    "git-commit": "git_commit_long",
    "git-commit-short": "git_commit_short",
    "git-tag": "git_tag",
    "datetime": "date_build"
}

ビルド(アーカイブの作成)の仕方

基本コマンド
$ ./box.phar build -c [設定JSONファイルのパス]

$ ls -la
drwxr-xr-x   13 admin  staff    442  1 31 12:25 .
drwxr-xr-x   24 admin  staff    816  1 25 15:42 ..
drwxr-xr-x   16 admin  staff    544  1 30 22:07 .git
-rw-r--r--@   1 admin  staff    191  1 27 12:59 box.json
-rwxr-xr-x    1 admin  staff 961620  1 27 11:43 box.phar
drwxr-xr-x    6 admin  staff    204  1 31 20:00 src
$ # Pharのビルド
$ ./box.phar build -c ./box.json

Git 情報

  • 基本コマンド
    • タグの確認: $ git tag
    • タグの追加: $ git tag [任意のタグ]
    • タグの削除: $ git tag -d [削除したいタグ]
    • GitのコミットID確認: $ git show -s --format=%H
Gitのコミットにタグを付けて再ビルドする例
$ ls -la
drwxr-xr-x   13 admin  staff    442  1 31 12:25 .
drwxr-xr-x   24 admin  staff    816  1 25 15:42 ..
drwxr-xr-x   16 admin  staff    544  1 30 22:07 .git
-rwxr-xr-x    1 admin  staff   3466  1 31 23:40 HelloWorld.phar
-rw-r--r--@   1 admin  staff    191  1 27 12:59 box.json
-rwxr-xr-x    1 admin  staff 961620  1 27 11:43 box.phar
drwxr-xr-x    6 admin  staff    204  1 31 20:00 src
$ # Gitのタグ確認
$ git tag

$ # タグが付いていないのでタグを付けてみる
$ git tag 1.0.0
$ # Pharの再ビルド
$ ./box.phar build -c ./box.json
$ # アプリの実行
$ ./HelloWorld.phar
Hello world! (Build:1.0.0)

他にできることないの?

色々できます。box.jsonに以下のキーを使うと、git-versionキーと同様に、用途ごとに文字列を置き換えてくれます。

キー 用途
datetime 任意の置換文字列 ビルドした日付に置き換えます
datetime_format Y-m-d H:i:s 上記datetimeの日付フォーマットをPHP日付フォーマットで指定できます
git-commit 任意の置換文字列 完全長のコミットIDに置き換えます
git-commit-short 任意の置換文字列 コミットIDのショートハッシュ(最初の7桁)に置き換えます
git-tag 任意の置換文字列 Gitのタグに置き換えます

参考文献

  • $ ./box.phar help build

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.

動作検証環境

$ sw_vers
ProductName:    Mac OS X
ProductVersion: 10.12.6
BuildVersion:   16G1114
$ php -v
PHP 7.1.8 (cli) (built: Aug  7 2017 15:02:45) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2017 Zend Technologies
$ ./box.phar -V
Box version 2.7.5 build 8ce371cdc1f0005e087e9ca5c265b52b5f560fd4