SPINEN's Laravel Version

There are many times that it is nice to know the version of your application. At Spinen, we adhere to Semantic Versioning for our applications using git-flow. We keep a file in the root of our projects named VERSION with the current version. The CI/CD process modifies the VERSION file to append meaningful data. Then in the views we display the version like this <meta name="application-version" content="{{ $version }}">. Additionally, we have a smokescreen test to hit a /version route to make sure that the expected version of the site is running.

Build Status

| Branch | Status | Coverage | Code Quality | | ------ | :----: | :------: | :----------: | | Develop | | | | | Master | | | |

Prerequisite

As side from Laravel >= 8, there are no packages that are required.

Install

Install Version:

$ composer require spinen/laravel-version

The package uses the auto registration feature of Laravel 5.

Description of version file

You need a file, with the Semantic Version of your application. For example...

4.3.6

Then you can add additional data either manually or via your CI/CD pipeline to be similar to this...

4.3.6

feature/some_great_thing
sha:3c40a5b0d0a07973bd117a39b53367c9ff4d4cc0
build:11425
20190220170058+0000

Breakdown of the line of the file

| Line | Content | Source | Purpose | | :----: | ------ | ------ | ------ | | 1 | 4.3.6 | Original content in the VERSION file | Split on . to get major, minor, patch | | 2 | "\n" | (Optional) New line | Readability | | 3 | feature/some_great_thing | Name of branch | Becomes the pre_release | | 4 | sha:3c40a5b0d0a07973bd117a39b53367c9ff4d4cc0 | Git commit SHA | Part of meta | | 5 | build:11425 | Build number | Part of meta | | 6 | 20190220170058+0000 | Datetime stamp of build | Part of meta |

Some notes about the file...

• We assume that the first line is only major.minor.patch
• The first non-empty line after the version will become the pre_release
• If pre_release is master, then it gets ignored
• All of the lines after the line being used as the pre_release get concatenated together with a . to become the meta, so there can be as many lines as you would like

Using the package

The Spinen\Version\Version object loads the configured version file to parse the file into the following public properties on the object...

| Property | Example | | ------ | ------ | | semver | 4.3.6-feature/some_great_thing+sha:3c40a5b0d0a07973bd117a39b53367c9ff4d4cc0.build:11425.20190220170058+0000 | | version | 4.3.6 | | major | 4 | | minor | 3 | | patch | 6 | | pre_release | feature/some_great_thing | | meta | sha:3c40a5b0d0a07973bd117a39b53367c9ff4d4cc0.build:11425.20190220170058+0000 |

You can inject Spinen\Version\Version into your code to gain access to the properties. For our use, here are 3 main uses of the package...

1. $version variable in views
2. /version route
3. version commands

Variable in views

An instance of \Spinen\Version\Version is added to to all views as the $version variable. You can do things like...

• Add version to HTML Header
  • <meta name="application-version" content="{{ $version }}"> to get <meta name="application-version" content="4.3.6-feature/some_great_thing+sha:3c40a5b0d0a07973bd117a39b53367c9ff4d4cc0.build:11425.20190220170058+0000">
  • NOTE: Casting object to string is the same as $version->semver
• Add version to footer of page
  • <small class="app_version">{{ $version->version }}</small> to get <small class="app_version">4.3.6</small>

Route

Visiting /version will return the version...

$ curl https://localhost/version
4.3.6-feature/some_great_thing+sha:3c40a5b0d0a07973bd117a39b53367c9ff4d4cc0.build:11425.20190220170058+0000

Commands

The following artisan commands are added...

| Command | Description | | ------ | ------ | | version | Display full version of the application. | | version:major | Display major version of the application. | | version:meta | Display meta version of the application. | | version:minor | Display minor version of the application. | | version:patch | Display patch version of the application. | | version:pre_release | Display pre_release version of the application. | | version:semver | Display semver version of the application. |

Configuration

Publish the package config file to config/version.php:

$ php artisan vendor:publish --tag version-config

This file is fully documented. You will need to make the changes to that file to suit your needs. There are 3 main configuration items...

1. file - Name of the file that has the version
2. route - Configuration of the route to display the version
3. view - Configuration of the view composer to add the version to the views

Example CI to modify version file

We use GitLab, so here is a partial example job that we have in our .gitlab-ci.yml...

version:
  stage: build

  image: php7.2

  dependencies: []

  script:
    - echo "" >> VERSION
    - echo "${CI_COMMIT_REF_NAME}" >> VERSION
    - echo "sha:${CI_COMMIT_SHA}" >> VERSION
    - echo "build:${CI_PIPELINE_ID}" >> VERSION
    - date +"%Y%m%d%k%M%S%z" >> VERSION

  artifacts:
    name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}-version"
    paths:
      - VERSION
    expire_in: 3 days