README

This is a simple tool to obtain "versions" for projects in PHP.

Installation

Installation through composer:

composer require naneau/project-versioner=~0

Examples

This library is based around a "Versioner", which accepts one or more "Readers".

Using Git

If your project is maintained using Git, you can look at it for versions.

Commit

Use the last commit as a version:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\Git\Commit\Exec as GitCommitReader;

// Create a versioner
$versioner = new Versioner(array(new GitCommitReader));

// Short commit hash like "gd8587c8"
$version = $versioner->get('/foo/bar');

Tag

Use the latest tag (reachable from this commit):

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\Git\Tag\Exec as GitTagReader;

// Create a versioner
$versioner = new Versioner(array(new GitTagReader));

// Last tag
$version = $versioner->get('/foo/bar');

Described Version

Use the output of git describe, which combines the latest (reachable) tag and subsequent commits:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\Git\Tag\Exec as GitTagReader;

// Create a versioner
$versioner = new Versioner(array(new GitTagReader));

// Last tag + commit info, like 4.3.2-9-gd504031
$version = $versioner->get('/foo/bar');

Using Files

Reading Version From A Single File

Imagine you maintain a file called VERSION that you (or your CI stack) fills with a version.

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\File as FileReader;

// Create a versioner
$versioner = new Versioner(array(
    // Reader for "VERSION" file
    new FileReader('VERSION')
));

// Retrieve version from versioner
$version = $versioner->get('/foo/bar');

Using MTime

In a common scenario, a set of files is (independently) updated, and you want to use the highest/most recent time (mtime) as a version. This version can be used to bust caches, etc.:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\Finder\MTime as MTimeReader;

// Create a versioner
$versioner = new Versioner(array(
    new MTimeReader('*.txt') // Look at all *.txt files
));

// Highest mtime, like 1410806782
$version = $versioner->get('/foo/bar');

Using Contents

Using a different reader it is possible to use the contents of the files found:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\Finder\Contents as ContentsReader;

$versioner = new Versioner(array(
    new ContentsReader('*.jpg')
));

// Short hash of file contents, like gd504031
$version = $versioner->get('/foo/bar');

Composer

If your project depends on a set of Composer dependencies, you can use the Composer readers to obtain a version based on installed packages.

All Packages

To look at all packages combined:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\Composer as ComposerReader;

$versioner = new Versioner(array(new ComposerReader));

// Short hash like "ae9b8a"
$version = $versioner->get('/foo/bar');

Using A Specific Package

Or, looking for a specific package:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\ComposerPackage as ComposerPackageReader;

$versioner = new Versioner(array(
    new ComposerPackageReader('symfony/filesystem')
));

// Composer Version (SemVer) like "v2.5.4"
$version = $versioner->get('/foo/bar');

Combining Readers

For some projects you may want to combine readers, for instance as a fallback mechanism if one reader does not provide output, or to get a version composed of more than one reader's output.

Combining Composer and Git:

use Naneau\ProjectVersioner\Versioner;
use Naneau\ProjectVersioner\Reader\ComposerPackage as ComposerPackageReader;
use Naneau\ProjectVersioner\Reader\Git\Tag\Exec as GitTagReader;

$versioner = new Versioner(array(
    new ComposerPackageReader('symfony/filesystem'),
    new GitTagReader
));

// First version found
$version = $versioner->get('/foo/bar');

// Composite of all readers, like "v0.3.4-gd504031"
$combinedVersion = $versioner->getCombined('/foo/bar');

// You can specify the separator
$combinedVersionUnderscore = $versioner->getCombined('/foo/bar', '_');

Notes

Obtaining a version inevitably uses (potentially expensive) I/O. You may want to cache the results.
The exec based Git readers are UN*X only for now

naneau / project-versioner

Maintainers

Details