README

Introduction
Installation
Configuration
Rendering the Banner
Banner Data
License

Introduction

Laravel Environment Banner publishes information about the running application into a single <meta> tag, allowing a browser extension to display a banner that makes it obvious which environment, which application, and which git worktree you are looking at. The package renders the tag; deciding what the banner looks like is the responsibility of the extension reading it.

Installation

You may install Laravel Environment Banner using the Composer package manager:

composer require intrfce/laravel-environment-banner-bext

The package's service provider is registered automatically via package discovery.

Configuration

The package works without any configuration. If you wish to customise it, you may publish the configuration file using the vendor:publish Artisan command:

php artisan vendor:publish --tag=environment-banner-config

This command will place an environment-banner.php file within your application's config directory.

Rendering the Banner

Place the @envBanner Blade directive within the <head> element of your application's layout:

<head>
    <meta charset="utf-8">
    @envBanner
</head>

The directive renders a single meta tag named if-env-info, whose content is the banner data encoded as JSON:

<meta name="if-env-info" content="{&quot;environment&quot;:&quot;staging&quot;,&quot;app&quot;:&quot;Acme&quot;,&quot;worktree&quot;:&quot;feature-login&quot;}">

The JSON is escaped for use within an HTML attribute, so values containing quotes are safe to publish.

If you need the same data elsewhere, such as an Inertia prop or an API response, you may resolve the EnvironmentBanner class from the container and call its toArray method:

use Intrfce\LaravelEnvironmentBannerBext\EnvironmentBanner;

$data = app(EnvironmentBanner::class)->toArray();

Warning

The directive renders in every environment, including production, so your application's name and environment will appear in the HTML of every page that includes it. If you do not want this, wrap the directive in an @production check or a condition of your own.

Banner Data

The meta tag always contains the environment, app, and worktree keys. The colour and extra keys are only included once you have configured them.

Environment and Application Name

The environment and app keys are read from your application's existing configuration, using config('app.env') and config('app.name') respectively. No further setup is required.

Worktrees

When you serve more than one checkout of the same application, such as when using git worktrees, the environment and application name are identical in each one. To tell them apart, define the ENV_WORKTREE_NAME environment variable within the .env file of a given checkout:

ENV_WORKTREE_NAME=feature-login

The value is published as the worktree key. Checkouts without this variable publish null.

Colours

To suggest a colour for the banner, define the colour configuration value as a three or six digit hex string:

'colour' => '#f00',

Colours are normalised to lowercase, six digit form before they are published, so the value above is rendered as #ff0000. Values that are not valid hex colours throw an InvalidColourException.

If you would like the colour to vary by environment, you may provide an array keyed by environment name instead:

'colour' => [
    'production' => '#dc2626',
    'staging' => '#f59e0b',
    'local' => '#22c55e',
],

The optional default key is used for any environment that is not listed. Without it, unlisted environments publish no colour at all:

'colour' => [
    'production' => '#dc2626',
    'default' => '#22c55e',
],

An exact environment match always takes precedence over the default key. To publish no colour for a particular environment while still using a default for the rest, set that environment to null:

'colour' => [
    'production' => null,
    'default' => '#22c55e',
],

Every colour in the array is validated, not only the one belonging to the current environment, so a mistyped production colour surfaces while you are working locally rather than after you deploy.

Extra Data

You may publish additional key / value pairs for the banner to display, such as the current branch or the release currently deployed. Typically, you should register this data within the boot method of your application's AppServiceProvider class:

use Intrfce\LaravelEnvironmentBannerBext\EnvironmentBanner;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    EnvironmentBanner::extraData([
        'branch' => 'feature/login',
        'release' => 'v1.4.2',
    ]);
}

The data is published under the extra key:

{"environment":"staging","app":"Acme","worktree":null,"extra":{"branch":"feature/login","release":"v1.4.2"}}

Repeated calls to the extraData method are merged, with later keys replacing earlier ones, so several service providers may each contribute their own data. You may inspect the registered data using the getExtraData method, and discard it using the flushExtraData method.

Only string keys and string values are accepted; anything else throws an InvalidExtraDataException. Values should be cast before they are registered:

EnvironmentBanner::extraData([
    'queue_size' => (string) $size,
]);

Note

PHP casts numeric string keys to integers, so a key such as '1' becomes an integer and is rejected. Prefix keys of this kind so that they remain strings.

License

Laravel Environment Banner is open-sourced software licensed under the MIT license.

intrfce / laravel-environment-banner-bext

Package info

Security

Statistics