Magentoのエクステンションを作ってみよう〜初級編〜

前回はMagentoのディレクトリ構成や、エクステンションのディレクトリ構成をご紹介しました。
いよいよ今回からは実際にエクステンションを作っていきたいと思います。

初級編で取り上げる内容は、「管理画面から設定した任意の値を画面に出力するエクステンション」です。
システム設定で設定したコンテンツを公開画面側に表示させてみたいと思います。

ディレクトリの作成と必要なファイルの作成
システム設定画面を確認
画面表示周りの調整
表示を確認しよう
今回のまとめ

ディレクトリの作成と必要なファイルの作成

ディレクトリの作成

最初にエクステンションを配置するディレクトリを作成しましょう。
app/code下に次図のような構成のディレクトリを作成してください。
(Magentoディレクトリは最初からあると思うのでそのまま触らずに、My以下のディレクトリを作成してください。また、Message.phpなどのファイルは後ほど作成しますので、ここではディレクトリのみ作成してください)

registration.phpと設定ファイルの作成

次にregistration.phpと設定ファイルを作成します。registration.phpはMagentoフレームワークにエクステンションやテーマの存在を認識させるために必要なファイルです。

registration.phpの内容は決まっていて、以下のように書きます。

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'My_Example',
    __DIR__
);

内容を書き終えたら保存しておいてください。

次にetcディレクトリ下に設定ファイルを作成していきます。
作成する設定ファイルは以下の3つです。

module.xml
adminhtml/system.xml
config.xml

module.xml

module.xmlはエクステンションのバージョン番号や、他のモジュールとの依存関係を定義します。
今回の場合は以下のように記述しておいてください。

<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="My_Example" setup_version="1.0.0" />
</config>

adminhtml/system.xml

system.xmlはシステム設定画面の定義を行います。
Magento1にもありましたが、XML定義は大きく変わっています。
今回は任意のコンテンツを表示させたいので、以下の設定項目を定義します。

表示のオン・オフを切り替えるドロップダウン
表示するコンテンツを入力するテキストエリア

定義例は以下のとおりです。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="myextension" translate="label" sortOrder="999">
            <label>My Extension</label>
        </tab>
        <section id="myextension" translate="label" sortOrder="1" showInDefault="1" showInWebsite="1" showInStore="1">
            <class>separator-top</class>
            <label>My first extension configuration</label>
            <tab>myextension</tab>
            <resource>My_Extension::config_format</resource>
            <group id="message" translate="label" type="text" sortOrder="1" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Message</label>
                <field id="enable" translate="label" type="select" sortOrder="1" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Enable</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
                <field id="message" translate="label" type="textarea" sortOrder="1" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Message</label>
                    <depends>
                        <field id="enable">1</field>
                    </depends>
                </field>
            </group>
        </section>
    </system>
</config>

この他にも色々な項目を定義できるので、ほかのエクステンションや公式のdevdocsを参照してみてください。

config.xml

config.xmlはシステム設定値のデフォルト値を定義するファイルです。
system.xmlで定義した項目に対応する内容を定義することで、エクステンションのインストール直後の状態でも最低限の設定をもたせることができます。

今回の場合は設定項目が2個だけなので、次のように定義します。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
    <default>
        <myextension>
            <message>
                <enable>1</enable>
                <message></message>
            </message>
        </myextension>
    </default>
</config>

一旦ここまでできたら、エクステンションを有効化してみましょう。

エクステンションが正しくMagentoに認識されるかどうかは、次のコマンドを実行するとわかります。

php bin/magento module:status

My_Exampleというエクステンション名が「List of disabled modules:」のところに表示されていれば、ここまで作成してきた内容でMagentoが正しくエクステンションを認識してくれていることになります。
では、以下のコマンドを実行して、エクステンションを有効化・インストールしましょう。

php bin/magento module:enable My_Extension
php bin/magento setup:upgrade

エラーが出なければ、標準モード、またはdeveloperモードの場合はこれでエクステンションの有効化・インストールは完了です。

システム設定画面を確認

エクステンションで定義した内容が正しく動いているか確認するために、ここでMagentoの管理画面にログインしてみましょう。
先程system.xmlで定義したメニューが「店舗」メニューの設定からアクセスできるシステム設定画面に追加されていればOKです。

Magentoのシステム設定画面。左側メニューの「My first extension configuration」が今回定義したもの。

値が保存されるか試してみよう

せっかくなので、設定画面で値をセットしてみましょう。
適当な値を入力し、保存ボタンをクリックすると、値がデータベースに保存されます。

データベースの設定値はconfig.xmlよりも優先度が高いので、先程入力した値がフィールドにセットされていると思います。
値が保存されていることが確認できたら、次はいよいよ表示処理の作成に取り掛かりましょう。

画面表示周りの調整

Blockの作成

設定ファイルができたら、次はBlockクラスを定義します。
BlockクラスはPHPによる画面上の部品描画を担当するクラスです。

クラスの定義

最初にクラスの定義を行います。
Blockディレクトリの下に、「Message.php」を作成し、以下のように記述します。

<?php
namespace My\Example\Block;

use \Magento\Framework\View\Element\Template;

class Message extends Template
{

}

処理の記述

システム設定値を読み出すには、所定のクラスを介して行う必要があります。
幸い、Blockクラスの基底クラスにはそのためのプロパティが定義されています。

作成したBlockクラスに以下のメソッドを定義し、システム設定値を読み出せるようにしましょう。
(先ほど作成したMessage.phpの{...}内に記述します)

    /**
     * config value path for custom message
     */
    const XML_CONFIG_MESSAGE_PATH = 'myextension/message/message';
    /**
     * config value path for custom message enabling flag
     */
    const XML_CONFIG_MESSAGE_ENABLE_PATH = 'myextension/message/enable';

    /**
     * retrieve custom message from config data
     *
     * @return mixed
     */
    public function getCustomMessage()
    {
        return $this->_scopeConfig->getValue(self::XML_CONFIG_MESSAGE_PATH);
    }

    /**
     * retrieve custom message is enabled or not
     *
     * @return mixed
     */
    public function isEnable()
    {
        return $this->_scopeConfig->getValue(self::XML_CONFIG_MESSAGE_ENABLE_PATH);
    }

テンプレートの作成

続いてBlockクラスが使うテンプレートを作成しましょう。
MagentoのPHPプログラム部分が使うテンプレートファイルは拡張子「phtml」で作成します。
view/frontend/templatesの下に、「message.phtml」を作成し、以下のように記述します。

<?php /** @var \My\Example\Block\Message $block */?>
<?php if($block->isEnable()) :?>
<?= $block->getCustomMessage();?>
<?php endif;?>

if文などに使うメソッドは先程Blockクラスの定義で使用したものを使います。

レイアウトXMLの作成

Blockクラスとテンプレートが作成できたら、仕上げにレイアウトXMLを作成します。
レイアウトXMLはMagentoのページレイアウトを定義するファイルです。レイアウトXMLを理解することがMagentoのデザインカスタマイズでは非常に重要な要素となっています。

レイアウトはアクション単位で作成するため、作成したブロックをどのアクションが出力するページコンテンツのどの場所に表示させるかを考える必要があります。

今回は全ページのフッターに表示させてみることにします。
この場合、レイアウトXMLはdefault.xmlという名前で作成します。
view/frontend/layout下に、default.xmlを作成し、以下の内容を書き込んでください。

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="footer">
            <block class="My\Example\Block\Message" name="my.example.message" template="My_Example::message.phtml" />
        </referenceContainer>
    </body>
</page>