fostam/buildinfo

Store and use build time information. Useful for automated builds where information like the application version needs to be retrieved at build time, e.g. from a Git tag.

v1.1.0 2020-09-12 06:05 UTC

Requires

• php: >=7.2
• ext-json: *

Requires (Dev)

• phpunit/phpunit: 8.5.*

Apache-2.0

• Stefan Stammler

README

Store and use build time information. Useful for automated builds where information like the application version needs to be retrieved at build time, e.g. from a Git tag.

Features

• Create build information file
• Store information like version, build number, build time etc.
• Read build information in your application and easily use it

Install

The easiest way to install buildinfo is by using composer.

Library

With the BuildInfo library (buildinfo), the buildinfo parameters created with buildinfo-create can be read and used in the actual application.

$> composer require fostam/buildinfo

Creation Tool

With the creation tool (buildinfo-create), the buildinfo parameter file is created while the application is built. This package is only required during build phase, not in the final application.

$> composer require fostam/buildinfo-create

After installation, the build time tool can be called from the following location:

$> vendor/bin/buildinfo

Usage Overview

Create build info file during the build phase for bundling it into the release (using buildinfo-create):

buildinfo create buildinfo.php --set-version 2.1.0 --set-commit d921970aadf03b3cf0e71becdaab3147ba71cdef

Reading build info file from the application (using buildinfo):

$buildInfo = BuildInfo::fromFile('buildinfo.php');
echo "my application version: " . $buildInfo->getVersion();

Build Info Creation

To create a build info file, pass the desired filename to the tool along with the build information you want to store.

The file location is relative to the current working directory, unless you give an absolute path.

Buildinfo File Types

Currently, two file types are supported, PHP and JSON. PHP is faster to read and cachable, whereas JSON is useful if the build info needs to be processed from outside PHP, too (e.g. JavaScript).

The file type is specified by the file extension. As you can give multiple build info targets, you can let both a PHP and JSON file be created.

Example:

buildinfo create dist/buildinfo.php dist/buildinfo.json --set-version 2.1.0

Build Info Parameters

There are a couple of predefined build information parameters:

--set-name my-application-name
--set-time 2019-07-23T15:34:12Z
--set-version 2.1.0
--set-build-number 3541
--set-branch master
--set-commit d921970aadf03b3cf0e71becdaab3147ba71cdef

NOTE: if the time parameter is omitted, it is automatically set to a string of the current time in the RFC 3339 format.

Additionally, arbitrary custom parameters can be given using the --set option:

--set author=[e-mail]
--set "comment=this is the final release"

Build Information Usage

The predefined build info parameters can be retrieved with the following methods:

use Fostam\Buildinfo;

$buildInfo = BuildInfo::fromFile('buildinfo.json');
echo $buildInfo->getName();
echo $buildInfo->getTime();
echo $buildInfo->getVersion();
echo $buildInfo->getBuildNumber();
echo $buildInfo->getBranch();
echo $buildInfo->getCommit();

The custom parameters can be retrieved with a generic get() method:

echo $buildInfo->get('author');
echo $buildInfo->get('comment');

For convenience, the build time can be also retrieved as DateTime object:

$dt = $buildInfo->getTimeAsDateTime();
echo $dt->format(DateTime::RFC3339);