PHPackages                             justenough/craft-siteawareconfig - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. justenough/craft-siteawareconfig

ActiveCraft-plugin[Utility & Helpers](/categories/utility)

justenough/craft-siteawareconfig
================================

Set & retrieve site-aware config values

1.0.3(4y ago)0152MITPHP

Since Feb 17Pushed 4y ago1 watchersCompare

[ Source](https://github.com/justenoughco/craft-siteawareconfig)[ Packagist](https://packagist.org/packages/justenough/craft-siteawareconfig)[ RSS](/packages/justenough-craft-siteawareconfig/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (3)Used By (0)

Multi Site Config plugin for Craft CMS 3.x
==========================================

[](#multi-site-config-plugin-for-craft-cms-3x)

What?
-----

[](#what)

Set & retrieve Craft CMS config file values that are site-aware, with a clean API and easy defaults.

Why?
----

[](#why)

When working with [multi-site Craft CMS installs](https://craftcms.com/docs/3.x/sites.html#creating-a-site), you may find yourself needing config values than should exist for all sites in an install, but vary in value between the sites themselves.

This plugin allows you to share your template code / partials across sites, while always getting the correct value for the current site (or for a different site, if required).

Example usecases:

- API keys
- GA / GTM IDs
- Social network links
- Asset paths (logos etc)

### Why use this instead of

[](#why-use-this-instead-of)

- **Logic in my templates?** That works, but it's ugly as sin, and quickly gets repetitive. As much as possible, templates should just format and display data that is passed from PHP
- **A Craft global?** You could, but this is much faster (no DB / fields overhead), more lightweight and allows for both defaults and sharing values between sites / groups of sites if required
- **Environment variables?** You should use Environment Variables for config whenever you can! But with multi-site installs they're often not enough on their own. You can (and should) use `App::env()` inside your `config/siteware.php` to set values that belong in the environment (like API keys) that you may need to maintain per-site.
- **Custom key in `config/general.php`?** For basic use cases, this works fine, but again setting defaults / fallback values gets complex quickly.

How?
----

[](#how)

This plugin uses Craft's built-in [`ConfigHelper::localizedValue()`](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) helper to parse values in a `config/siteaware.php` config file and make them site aware. You can then consume them in your template / PHP code without having to worry about getting the right value for the right site.

See [configuration](#configuration) below for config file syntax.

### Requirements

[](#requirements)

This plugin requires PHP 7.4+ and Craft CMS 3.5 or later. It will *probably* work with older versions of Craft, but is untested with them.

### Installation

[](#installation)

```
cd /path/to/project
composer require justenoughco/craft-siteawareconfig
./craft plugin/install site-aware-config
```

### Configuration

[](#configuration)

Edit the config file at `config/siteaware.php` to set your config values.

```
// Craft's multi-environment config syntax is (optionally) supported
    '*' => [
        'staticValue' => 'I am the same for every site',
        'myCustomConfigKey' => [
            // value for the default site
            'default' => 'defaultValue',
            // value for another site
            'aSecondSite' => 'alternateValue',
        ],
        // be careful with nested array values - per site values
        // are replaced, not merged. e.g. [1] below
        'aDeepNestedKey' => [
            'default' => [
                'apiKey' => 'API_KEY_FOR_DEFAULT_SITE',
                'apiSecret' => 'API_SECRET_FOR_DEFAULT_SITE',
                'deeper' => [
                    'foo' => 'bar',
                    'baz' => 'cux',
                ],
            ],
            // [1] Because we've overwritten aDeepNestedKey for this site,
            // craft.siteAwareConfig.forSite('aSecondSite').aDeepNestedKey.deeper
            // will throw a missing key Error in Twig / UnknownPropertyException
            // in PHP
            'aSecondSite' => [
                'apiKey' => 'API_KEY_FOR_A_SECOND_SITE',
                'apiSecret' => 'API_SECRET_FOR_A_SECOND_SITE',
            ],
        ],
        // Callable example
        'myDynamicKey' => function (string $siteHandle = ''): int {
            return $siteHandle[0] == 'd' ? 1 : 2;
        },
    ],
    // overide a setting in dev environment only
    'dev' => [
        'myCustomConfigKey' => [
            'aSecondSite' => 'aDevOnlyValue',
        ],
        // multi-environment configs are merged, not replaced,
        // so in dev craft.siteAwareConfig.forSite('default').aDeepNestedKey.deeper
        // will work here
        'aDeepNestedKey' => [
            'default' => [
                'apiKey' => 'API_KEY_FOR_DEFAULT_SITE',
            ],
        ],
    ],
```

### Retrieving config values

[](#retrieving-config-values)

#### Templating

[](#templating)

Config values for the current Site are exposed to Twig under `craft.siteAwareConfig.currentSite`:

```
{{ craft.siteAwareConfig.currentSite.perSiteConfigKey }}
```

If needed, you can access the config for any site by passing its handle to `craft.siteAwareConfig.forSite()`

```
{% set defaultSiteConfig = craft.siteAwareConfig.forSite('siteHandle') }}
```

#### PHP

[](#php)

An instance of `justenough\siteawareconfig\services\Config` is what gets exposed to Twig. Should you need to, you can also access site aware config settings from PHP-land:

```
use justenough\siteawareconfig\Plugin as SiteAwareConfigPlugin;

$currentSiteConfig = SiteAwareConfigPlugin::getInstance()->config->config;
$otherSiteConfig = SiteAwareConfigPlugin::getInstance()->config->forSite('siteHandle');
```

The returned `SiteAwareConfig` extends Yii's [`BaseObject`](https://www.yiiframework.com/doc/api/2.0/yii-base-baseobject).

### Caveats / Potential "Gotchas"

[](#caveats--potential-gotchas)

While values in multi-environment configs are **merged**, site-aware values using the array syntax are **replaced**. This is usually only an issue if you are using an associative array for your config value (for example to group related values together).

If you need to merge values between sites either flatten your values, or use a callable to handle the merging/default logic.

Attributions
------------

[](#attributions)

Brought to you by [Just Enough Consulting](https://justenough.co/)

Icon by [Arthur Shlain via the NounProject.com](https://thenounproject.com/icon/config-900563/)

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

2

Last Release

1539d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a4a6c669cfbf869013a978c80f24947fc5d600c2ca15416d38fdb56a1322457f?d=identicon)[justenough](/maintainers/justenough)

---

Top Contributors

[![tomdavies](https://avatars.githubusercontent.com/u/136308?v=4)](https://github.com/tomdavies "tomdavies (4 commits)")

---

Tags

cmsCraftcraftcmscraft-pluginSite Aware config

###  Code Quality

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/justenough-craft-siteawareconfig/health.svg)

```
[![Health](https://phpackages.com/badges/justenough-craft-siteawareconfig/health.svg)](https://phpackages.com/packages/justenough-craft-siteawareconfig)
```

###  Alternatives

[pennebaker/craft-architect

CraftCMS plugin to generate content models from JSON/YAML data.

72148.5k5](/packages/pennebaker-craft-architect)[doublesecretagency/craft-cpjs

Add custom JavaScript to your Control Panel.

43163.7k](/packages/doublesecretagency-craft-cpjs)[nystudio107/craft-webperf

Webperf helps you build & maintain high quality websites through Real User Measurement of your website's performance

2540.9k1](/packages/nystudio107-craft-webperf)[superbig/craft3-mobiledetect

Use Mobile\_Detect for detecting mobile devices (including tablets)

1953.3k](/packages/superbig-craft3-mobiledetect)[billythekid/conditional-fields

Show or hide fields based on the value of other fields.

138.1k](/packages/billythekid-conditional-fields)[wbrowar/craft-grid

A field that lets you content manage CSS Grid in Craft CMS.

171.1k](/packages/wbrowar-craft-grid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)