Craft 4 でシステム設定を定義する際の注意点について

Craft CMS ではシステムの一般設定を config/general.php に定義します。

従来であればここに各種サービスの API Key であったり、ページ分割のデフォルト件数であったり、ユーザー定義のカスタム設定を自由に追記することができました。ところが、Craft 4 からカスタム設定を別ファイルに定義する形となりました。

そこでカスタム設定の定義方法について、ご紹介します。
これは Craft CMS Advent Calendar 2022 11日目の記事です。

config/general.php に定義できるのは？

公式ドキュメントの Geenral Settings に記載されている項目だけ、と考えておくのが無難です。

General Settings | Craft CMS Documentation | 4.x
https://craftcms.com/docs/4.x/config/general.htm

それ以外は、カスタム設定として別ファイルに定義しましょう。

カスタム定義を config/general.php に定義すると、どうなるか？

フロントエンド、管理画面ともに 500 エラーとなります。

An Error occurred while handling another error:
yii\base\UnknownPropertyException: Invalid general config setting: customConfig. You can set custom config settings from config/custom.php. in /pathTo/craft4core/vendor/craftcms/cms/src/config/GeneralConfig.php:3086
Stack trace:

devMode がオンの環境であれば、このようなエラーメッセージが表示されます。（customConfig がカスタム設定として追記されています。）

カスタム設定は config/custom.php へ

ユーザー定義のカスタム設定は config/custom.php を新しく作成し、そこに記述します。general.php と同様、環境ごとに設定を上書きすることもできます。

<?php
use craft\helpers\App;

return [
    // Global settings
    '*' => [
        'sampleKey' => 'カスタム設定のサンプル',
    ],

    // Dev environment settings
    'dev' => [
        'sampleKey' => App::env('SAMPLE_VALUE'),
    ],
];

.env の値を参照したければ、App::env を利用しましょう。

テンプレートからカスタム設定を参照するには

一般設定とカスタム設定の参照方法はほとんど一緒ですので、あわせて覚えてしまいましょう。

config/general.php の場合

craft.app.config.general. に続けて、取得したい項目名を指定します。

{{ craft.app.config.general.timezone }}

config/custom.php の場合

craft.app.config.custom. に続けて、取得したい項目名を指定します。

{{ craft.app.config.custom.sampleKey }}

最後に

今回は Craft 4 から変更になったユーザー定義のカスタム設定の記述方法についてご紹介しました。

Craft 3 に慣れているとアップグレードの際にエラーになりがちですので、ご注意ください。

comments powered by Disqus