README

Common utilities and building blocks for LindemannRock Craft CMS plugins.

Overview

This package provides shared functionality for all LindemannRock plugins:

• Traits for Settings models (displayName, database persistence, config overrides)
• Twig Extensions for plugin name helpers in templates
• Helpers for common plugin initialization tasks and geographic utilities
• Templates for shared components (plugin-credit, info-box, ip-salt-error)
• GeoHelper for ISO 3166-1 country code lookups (249 countries)

Requirements

• Craft CMS 5.0+
• PHP 8.2+

Installation

Via Composer

cd /path/to/project
composer require lindemannrock/craft-plugin-base

Using DDEV

cd /path/to/project
ddev composer require lindemannrock/craft-plugin-base

Usage

In Settings Model

use lindemannrock\base\traits\SettingsConfigTrait;
use lindemannrock\base\traits\SettingsDisplayNameTrait;
use lindemannrock\base\traits\SettingsPersistenceTrait;

class Settings extends Model
{
    use SettingsDisplayNameTrait;
    use SettingsPersistenceTrait;
    use SettingsConfigTrait;

    public string $pluginName = 'My Plugin';

    protected static function tableName(): string
    {
        return 'myplugin_settings';
    }

    protected static function pluginHandle(): string
    {
        return 'my-plugin';
    }

    // Optional: specify field types for database persistence
    protected static function booleanFields(): array
    {
        return ['enableFeature', 'debugMode'];
    }

    protected static function integerFields(): array
    {
        return ['cacheTimeout', 'maxItems'];
    }

    protected static function jsonFields(): array
    {
        return ['excludePatterns', 'customSettings'];
    }
}

In Main Plugin Class

use lindemannrock\base\helpers\PluginHelper;

public function init(): void
{
    parent::init();

    // Bootstrap base module (registers Twig extension + logging)
    PluginHelper::bootstrap($this, 'myPluginHelper', ['myPlugin:viewLogs']);

    // Apply plugin name from config file
    PluginHelper::applyPluginNameFromConfig($this);
}

In Templates

{# Plugin name helpers (via Twig extension) #}
{{ myPluginHelper.displayName }}       {# "My Plugin" #}
{{ myPluginHelper.fullName }}          {# "My Plugin Manager" #}
{{ myPluginHelper.pluralDisplayName }} {# "My Plugins" #}
{{ myPluginHelper.lowerDisplayName }}  {# "my plugin" #}

{# Shared components #}
{% include 'lindemannrock-base/_components/plugin-credit' %}

{% include 'lindemannrock-base/_components/info-box' with {
    message: 'This is an informational message',
    type: 'info'  {# 'info', 'success', 'warning' #}
} %}

{% include 'lindemannrock-base/_components/ip-salt-error' with {
    pluginHandle: 'my-plugin',
    envVarName: 'MY_PLUGIN_IP_SALT'
} %}

Components

Traits

Templates

Helpers

GeoHelper Usage

use lindemannrock\base\helpers\GeoHelper;

// Get country name from code
$name = GeoHelper::getCountryName('US');  // "United States"
$name = GeoHelper::getCountryName('GB');  // "United Kingdom"
$name = GeoHelper::getCountryName('XX');  // "XX" (returns code if unknown)

// Get all countries
$countries = GeoHelper::getAllCountries();  // ['AD' => 'Andorra', 'AE' => 'United Arab Emirates', ...]

// Validate country code
$valid = GeoHelper::isValidCountryCode('US');  // true
$valid = GeoHelper::isValidCountryCode('XX');  // false

Support

• Documentation: https://github.com/LindemannRock/craft-plugin-base
• Issues: https://github.com/LindemannRock/craft-plugin-base/issues
• Email: support@lindemannrock.com

License

This plugin is licensed under the MIT License. See LICENSE.md for details.

Developed by LindemannRock