README

Env Beacon for Craft CMS

Env Beacon is a lightweight Craft CMS plugin that displays a small environment badge in the Craft control panel and, optionally, on the front-end site.

Use it to make the current environment obvious to editors, admins, and developers:

• Local
• Development
• Staging
• QA
• Production

It is intentionally simple: no database tables, no queues, no external services, and no JavaScript dependency.

Features

• Control panel badge for the current environment
• Optional front-end site badge
• Fixed bottom-right badge position
• Automatic label detection from common environment variables
• Custom environment variable mode
• Custom label mode
• Automatic colors:
  • Production / Live → red
  • Staging / Test / QA → amber
  • Local / Dev / DDEV → blue
• Custom hex color support
• Optional status dot
• Optional hostname display
• Optional admin-only visibility
• Optional login-screen visibility
• Supports project config and config/env-beacon.php overrides

Requirements

• Craft CMS 4.x or 5.x
• PHP 8.0.2 or later

Installation

You can install Env Beacon via the plugin store, or through Composer.

Composer

You can also add the package to your project using Composer and the command line.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to require the plugin, and Craft to install it:

    composer require jainilnagar/env-beacon && php craft plugin/install env-beacon
   

Craft Plugin Store

To install Env Beacon, navigate to the Plugin Store section of your Craft control panel, search for Env Beacon.

Configuration

You can configure Env Beacon from:

Settings → Plugins → Env Beacon

You can also override settings per environment in:

config/env-beacon.php

Example:

<?php

return [
    '*' => [
        'source' => 'auto',
        'colorMode' => 'auto',
        'showOnFrontend' => true,
    ],

    'dev' => [
        'label' => 'Local',
        'source' => 'custom',
        'colorMode' => 'custom',
        'customColor' => '#2563eb',
    ],

    'staging' => [
        'label' => 'Staging',
        'source' => 'custom',
        'colorMode' => 'custom',
        'customColor' => '#d97706',
    ],

    'production' => [
        'label' => 'Production',
        'source' => 'custom',
        'colorMode' => 'custom',
        'customColor' => '#dc2626',
        'adminsOnly' => true,
    ],
];

Visibility behavior

• Control panel pages show the badge when the plugin is enabled.
• Front-end pages show the badge when showOnFrontend is enabled.
• If adminsOnly is enabled, the badge is hidden from non-admin users.
• If showOnLogin is enabled, the login screen shows the badge even when adminsOnly is enabled, because no admin user is authenticated yet.

Environment label detection

When label source is set to auto, Env Beacon checks these values in order:

1. ENV_BEACON_LABEL
2. CRAFT_ENVIRONMENT
3. ENVIRONMENT
4. APP_ENV
5. YII_ENV
6. CRAFT_ENVIRONMENT constant
7. YII_ENV constant
8. Craft’s devMode fallback

Suggested .env values

CRAFT_ENVIRONMENT=dev

CRAFT_ENVIRONMENT=staging

CRAFT_ENVIRONMENT=production

Or use the plugin-specific variable:

ENV_BEACON_LABEL=Staging

License

MIT