spinen/laravel-version

Helpers to keep track of the version of your Laravel application.

1.5.0 2023-03-12 18:01 UTC

README

Latest Stable Version Latest Unstable Version Total Downloads License

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 Build Status Code Coverage Scrutinizer Code Quality
Master Build Status Code Coverage Scrutinizer Code Quality

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