Elevate Your Laravel Development: Implementing an Effective Versioning System

Elevate Your Laravel Development: Implementing an Effective Versioning System

Latarips
Latarips
change logs

Keeping users informed about the changes in your application is vital. We introduce a straightforward versioning system to achieve just that.

This method involves creating a designated folder, which we’ll refer to as “change-logs.” In this folder, significant changes that users need to know with each version update are added.

Additionally, we include a class that will read and display these logs to the user:

namespace App\Classes;

use Illuminate\Mail\Markdown;

class ChangeLog
{
    static $FILE_NAME = "_changelog.md";
    static $FOLDER_NAME = "change-logs";
    static $MAX_NUN_SHOW_VERSIONS = 3;

    static public function RENDER($onlyLastVersion = false)
    {
        $files = scandir(base_path(self::$FOLDER_NAME));
        $versions = [];
        foreach ($files as $file) {
            if ($file !== '.' && $file !== '..') {
                $portions = explode("_", $file);
                $versions[] = $portions[0];
            }
        }
        usort($versions, 'version_compare');
        $html = "";
        $index = 1;

        $maxNumShowVersions = $onlyLastVersion ? 1 : self::$MAX_NUN_SHOW_VERSIONS;

        foreach (array_reverse($versions) as $version) {
            if ($index <= $maxNumShowVersions) {
                if ($index !== 1) $html .= '<div class="my-5"></div>';
                if ($file !== '.' && $file !== '..') {
                    $file = file_get_contents(base_path( self::$FOLDER_NAME . "/" . $version . self::$FILE_NAME));
                    $html .= Markdown::parse($file);
                }                
            } else break;
            $index++;
        }
        return $html;
    }
}

The PHP usort method with the version_compare parameter effectively sorts our files. This is crucial since versions often aren’t alphabetically ordered. For instance, versions like 1.9.09 and 1.10.00 won’t sort correctly without this logic.

PHP version_compare function documentation

Following this, versions’ files to be displayed in Markdown format are added to the “change-logs” folder. An example of Markdown would look like this:

./change-logs/0.0.1_changelog.md

**version 0.0.1**

- Users can login with google account.

./change-logs/0.0.2_changelog.md

**version 0.0.2**

- Users can login with facebook account.

These logs can be displayed through a Laravel component:

php artisan make:component ShowChangeLog

For simplicity, we’ve showcased this on a freshly installed project using sail on Getting Started On macOS. But work with all operating systems with Docker installed.

curl -s "https://laravel.build/laravel-app" | bash

The output can be presented in an offcanvas, modal, page, or other options, depending on your application’s structure.

<x-show-change-log />

As a final tip, we recommend installing the Tailwind CSS Typography Plugin to ensure correct HTML display of Markdown on your page, especially if you’re using Tailwind. This library is common in Laravel applications as it comes included in Laravel’s Starter Kits.

Moreover, adding the ‘prose lg:prose-xl’ css class will format the Markdown content, improving its visual presentation.

File ./resources/views/components/show-change-log.blade.php

<div class="prose lg:prose-xl">
    {!! App\Classes\ChangeLog::RENDER() !!}
</div>

Implementing this versioning system in your Laravel application ensures clear and effective communication of changes to your users.

Just an example we put result in welcome.blade.php file:

final result

#helpers #utils