拡張アプリ

目次

名前空間

拡張アプリでの拡張方法を見て行く前に、拡張アプリでの名前空間を説明します。

名前空間

ファイルのパスと命名規則はPSR4に従います。(ただし下位互換性を保つため一部したがっていない場合があります)

extension/plugins の名前空間は Acms\Plugins になります。

パス extension/plugins/SamplePlugin/ServiceProvider.php

クラス名 Acms\Plugins\SamplePlugin\ServiceProvider
記述例 <?php

namespace Acms\Plugins\SamplePlugin;

class ServiceProvider extends \ACMS_App
{
}

拡張アプリ開発の基本

拡張アプリとして拡張機能を作ることにより、様々な拡張を1パッケージにして、ブログ単位でインストール出来るようになります。

拡張できる機能

  • 校正オプションの拡張
  • フック処理の拡張
  • Validatorの拡張
  • 独自GETモジュールの追加
  • 独自POSTモジュールの追加
  • テンプレートの挿入(テンプレートの拡張)

最低限必要なファイル

拡張アプリを作るためには、以下のファイルが最低限必要になります。

  • extension/拡張アプリのディレクトリ/ServiceProvider.php

このファイルがあれば、最小限の拡張アプリとして成立し、管理画面からインストールもできるようになります。このファイルは、アプリのバージョンや説明やインストール・アップデート時の処理や起動の初期処理を記述できるファイルになっています。詳しく見ていきましょう。

ServiceProvider.php

下のコードは、 ServiceProvider.php の 基本的なコードになります。

<?php

namespace Acms\Plugins\SamplePlugin;

use ACMS_App;

class ServiceProvider extends ACMS_App
{
    /**
     * @var string
     */
    public $version = '1.0.0';

    /**
     * @var string
     */
    public $name = 'SamplePlugin';

    /**
     * @var string
     */
    public $author = 'com.appleple';

    /**
     * @var bool
     */
    public $module = false;

    /**
     * @var bool|string
     */
    public $menu = false;

    /**
     * @var string
     */
    public $desc = 'サンプルのプラグインです。';

    /**
     * サービスの初期処理
     */
    public function init()
    {

    }

    /**
     * インストールする前の環境チェック処理
     *
     * @return bool
     */
    public function checkRequirements()
    {
        return true;
    }

    /**
     * インストールするときの処理
     * データベーステーブルの初期化など
     *
     * @return void
     */
    public function install()
    {

    }

    /**
     * アンインストールするときの処理
     * データベーステーブルの始末など
     *
     * @return void
     */
    public function uninstall()
    {

    }

    /**
     * アップデートするときの処理
     *
     * @return bool
     */
    public function update()
    {
        return true;
    }

    /**
     * 有効化するときの処理
     *
     * @return bool
     */
    public function activate()
    {
        return true;
    }

    /**
     * 無効化するときの処理
     *
     * @return bool
     */
    public function deactivate()
    {
        return true;
    }
}

プロパティ


プロパティ名 説明
$version バージョンを指定します。バージョン表記に決まりはありませんが、セマンティックバージョニングで付けるといいと思います。
$name 拡張アプリの名前を指定します。ここの名前が管理画面に表示されます。特に命名規則はありません
$author 作者を指定します。
$module ここにString(英数字)を指定すると、その名前でモジュールID作成の時、選択肢として表示されます。(非推奨)
$menu ここにString(英数字)を指定すると、そのURLで拡張アプリの管理画面が作成されます。
例: 'sample_index'
URL: /bid/1/admin/app_sample_index/
パス: themes/system/admin/app/sample/index.html
$desc 拡張アプリの詳細を記述します。管理画面で表示されます。

メソッド


メソッド名 説明
init インストールされた場合に動作し初期処理を記述できます。
例えば、Hook処理のバインドやテンプレートの挿入処理、autoloadの設定などに利用します。
checkRequirements インストール前のチェックに利用します。「false」を返すとインストールが出来ません。
install ルートブログのアプリ管理画面からアプリのインストール時に実行されます。データベースの初期化処理などに利用ください。
uninstall ルートブログのアプリ管理画面からアプリのアンインストール時に実行されます。データベースの削除処理などに利用ください。
update 拡張アプリのアップデート時に利用します。データ構造の変更などある場合に利用します。
activate 拡張アプリの有効時(ブログ単位)に動作します。インストール時にもここが実行されます。
deactivate 拡張アプリを無効化時(ブログ単位)に動作します。アンインストール時にもここが実行されます。

ポイント

  • extension/plugins/ の名前空間は 「Acms\Plugins」 です。
  • \ACMS_App を継承します。

これで拡張アプリ開発の基本は終了です。次から実際の拡張方法について見ていきます。

モジュールの拡張

拡張アプリでのモジュールの拡張方法を見ていきます。基本的には、通常の拡張方法と同様ですが名前空間・クラス名に気をつけましょう。

GET・POST モジュールは、extension/plugins/独自ディレクトリ/(GET|POST) ディレクトリ以下に設置します。

例: extension/plugins/SamplePlugin/GET/Sample.php

<?php

namespace Acms\Plugins\SamplePlugin\GET;

use ACMS_GET;
use Template;
use ACMS_Corrector;

/**
 * テンプレート上では、標準のGETモジュールと同様に、
 * '<!-- BEGIN_MODULE Sample --><!--END_MODULE Sample -->' で呼び出されます。
 */
class Sample extends ACMS_GET
{
    function get()
    {
        $Tpl = new Template($this->tpl, new ACMS_Corrector());
        $data = array();

        return $Tpl->render($obj);
    }
}

気をつける点としては、「GET」 は 全て大文字 なので注意してください。あとは、モジュールの開発 を参照ください。

校正オプションの拡張

拡張アプリでの校正オプションの拡張の仕方を見ていきます。名前空間・クラス名に気をつけましょう。

ファイル名は任意ですが、わかりやすくする為、Corrector.php とします。

例: extension/plugins/SamplePlugin/Corrector.php

<?php

namespace Acms\Plugins\SamplePlugin;

class Corrector
{
    /**
     * sample
     * 校正オプションのサンプルメソッド
     *
     * @param  string $txt  - 校正オプションが適用されている文字列
     * @param  array  $args - 校正オプションの引数 {var}[sample('ここの値')]
     * @return string       - 校正後の文字列
     */
    public function sample($txt, $args = array())
    {
        // 例 {var}[sample('hoge','fuga')]
        // {var}の中は,'a-blogcms' とする

        $hoge = isset($args[0]) ? $args[0] : null; // 'hoge'
        $fuga = isset($args[1]) ? $args[1] : null; // 'fuga'

        return $hoge.$fuga.'+'.$txt; // 'hogefuga+a-blog cms'
    }
}

ServiceProviderの設定

これだけでは、通常の拡張方法と違い動作しません。動作させるためには、このクラスのオブジェクトをa-blog cmsに登録する必要があります。

ServiceProviderで校正オプションの実装クラスを登録する

拡張アプリの基本で作成した ServiceProviderに少し手を加えます。

<?php

namespace Acms\Plugins\SamplePlugin;

use ACMS_App;
use Acms\Services\Common\CorrectorFactory;

class ServiceProvider extends ACMS_App
{
    /* 省略... */

    /**
     * サービスの初期処理
     */
    public function init()
    {
        $corrector = CorrectorFactory::singleton();
        $corrector->attach('SampleCorrector', new Corrector);
    }

    /* 省略... */
}

ポイント

Acms\Services\Common\CorrectorFactory のオブジェクトを

CorrectorFactory::singleton();

で取得して 先ほど作成した Acms\Plugins\SamplePlugin\Correctorattach します。

  • 第一引数: 被らないような任意の文字列
  • 第2引数: 実装クラスのオブジェクト

これで拡張アプリをインストールすれば、Corrector.php で実装した校正オプションが利用できるようになります。

フックの拡張

拡張アプリでのフックの拡張の仕方を見ていきます。名前空間・クラス名に気をつけましょう。

ファイル名は任意ですが、わかりやすくする為、Hook.php とします。

例: extension/plugins/SamplePlugin/Hook.php

<?php

namespace Acms\Plugins\SamplePlugin;

class Hook
{
    /**
     * 例: グローバル変数の拡張
     *
     * @param array &$globalVars
     */
    public function extendsGlobalVars(&$globalVars)
    {
         $globalVars->set('SAMPLE', 'サンプルのグローバル変数です');
    }
}

ServiceProviderの設定

これだけでは、通常の拡張方法と違い動作しません。動作させるためには、このクラスのオブジェクトをa-blog cmsに登録する必要があります。

ServiceProviderでHook実装クラスを登録する

拡張アプリの基本で作成した ServiceProviderに少し手を加えます。

<?php

namespace Acms\Plugins\SamplePlugin;

use ACMS_App;
use Acms\Services\Common\HookFactory;

class ServiceProvider extends ACMS_App
{
    /* 省略... */

    /**
     * サービスの初期処理
     */
    public function init()
    {
        $hook = HookFactory::singleton();
        $hook->attach('SampleHook', new Hook);
    }

    /* 省略... */
}

ポイント

Acms\Services\Common\HookFactory のオブジェクトを

HookFactory::singleton();

で取得して 先ほど作成した Acms\Plugins\SamplePlugin\Hookattach します。

  • 第一引数: 被らないような任意の文字列
  • 第2引数: 実装クラスのオブジェクト

これで拡張アプリをインストールすれば、Hook.php で実装したHookが利用できるようになります。

Validatorの拡張

拡張アプリでのValidatorの拡張の仕方を見ていきます。名前空間・クラス名に気をつけましょう。

ファイル名は任意ですが、わかりやすくする為、Validator.php とします。

例: extension/plugins/SamplePlugin/Validator.php

<?php

namespace Acms\Plugins\SamplePlugin;

class Validator
{
    /**
     * sample
     * バリデーターのサンプルメソッド
     *
     * @param  string $val - その変数の値
     * @param  string $arg - <input type="hidden" name="var:v#sample" value="ここの値">
     * @return boolean     - 入力が正しい場合は "ture" そうでない場合は "false" を返す
     */
    function sample($val, $arg)
    {
        /**
         * 例:
         * <input type="text" name="var" value="{var}">
         * <input type="hidden" name="field[]" value="var">
         * <input type="hidden" name="var:v#sample" value="cms">
         *
         * <!-- BEGIN var:validator#sample -->
         *   <p class="acms-admin-text-error">cmsという文字列を含めてください。</p>
         * <!-- END var:validator#sample -->
         *
         * {var}の中は,'a-blogcms' とする
         */

        // name="var:v#sample" value="cms" で指定した
        // 文字列が含まれていなかったらエラーを出す
        return (strpos($val, $arg) !== false);
    }
}

ServiceProviderの設定

これだけでは、通常の拡張方法と違い動作しません。動作させるためには、このクラスのオブジェクトをa-blog cmsに登録する必要があります。

ServiceProviderでValidator実装クラスを登録する

拡張アプリの基本で作成した ServiceProviderに少し手を加えます。

<?php

namespace Acms\Plugins\SamplePlugin;

use ACMS_App;
use Acms\Services\Common\ValidatorFactory;

class ServiceProvider extends ACMS_App
{
    /* 省略... */

    /**
     * サービスの初期処理
     */
    public function init()
    {
        $validator = ValidatorFactory::singleton();
        $validator->attach('SampleValidator', new Validator);
    }

    /* 省略... */
}

ポイント

Acms\Services\Common\ValidatorFactory のオブジェクトを

ValidatorFactory::singleton();

で取得して 先ほど作成した Acms\Plugins\SamplePlugin\Validatorattach します。

  • 第一引数: 被らないような任意の文字列
  • 第2引数: 実装クラスのオブジェクト

これで拡張アプリをインストールすれば、Validator.php で実装したValidatorが利用できるようになります。

テンプレートの挿入

拡張アプリで様々な拡張をする場合、プログラムだけではなく管理ページを拡張したい場合があると思います。例えば、モジュールID化したいため、モジュール選択肢のテンプレートを拡張したい、拡張アプリ用の管理画面ページ(コンフィグページ)を作りたいなどです。

テンプレートの挿入方法

テンプレートを挿入するためには、ServiceProviderの initメソッド で 挿入処理を書く必要があります。

例: extension/plugins/SamplePlugin/ServiceProvider.php

<?php

namespace Acms\Plugins\SamplePlugin;

use ACMS_App;
use Acms\Services\Common\InjectTemplate;

class ServiceProvider extends ACMS_App
{
    /* 省略... */

    /**
     * サービスの初期処理
     */
    public function init()
    {
        $inject = InjectTemplate::singleton();
        $inject->add('admin-module-select', PLUGIN_DIR . 'SamplePlugin/template/module-select.html');
    }

    /* 省略... */
}

ポイント

Acms\Services\Common\InjectTemplate のオブジェクトを

$inject = InjectTemplate::singleton();

で取得して addメソッド でテンプレートを挿入します。

$inject->add('挿入先', 'テンプレートのパス');
  • 第一引数: 挿入先の識別子
  • 第2引数: 挿入するテンプレートパス(PLUGIN_DIR定数 を使うと便利です)

挿入先の仕込み

テンプレートはどこでも挿入できるわけではなく、挿入先に仕込みがされています。

例えば、モジュールIDのセレクトの選択肢のテンプレート(themes/system/admin/module/select.html)を見ると以下のような記述があります。

<!-- BEGIN_MODULE Admin_InjectTemplate id="admin-module-select" --><!-- END_MODULE Admin_InjectTemplate -->

この Admin_InjectTemplateモジュールid に指定されている識別子が、テンプレートを挿入するときに使う Acms\Services\Common\InjectTemplateaddメソッド の第一引数に指定されます。

挿入先一覧


識別子 挿入先パス 説明
admin-main themes/system/admin.html 管理ページのメインHTMLを追加
admin-action themes/system/admin/action.html アクションボックスに追加
admin-topicpath themes/system/admin/topicpath-list.html 管理画面のトピックパスを追加
admin-module-select themes/system/admin/module/select.html モジュールIDの選択肢を追加
admin-module-config-%{MODULE_NAME} themes/system/admin/module/edit.html モジュール編集ページに追加。%{MODULE_NAME} はモジュール名に変更する。
例: Sampleモジュール -> admin-module-config-Sample
admin-form themes/system/admin/form/edit.html フォームID編集ページに追加
admin-entry-field themes/system/admin/entry/edit.html エントリーのカスタムフィールドを追加
admin-entry-field-foot themes/system/admin/entry/edit.html エントリーのカスタムフィールドを追加
admin-category-field themes/system/admin/category/edit.html カテゴリーのカスタムフィールドを追加
admin-blog-field themes/system/admin/blog/edit.html ブログのカスタムフィールドを追加
admin-user-field themes/system/admin/user/edit.html ユーザーのカスタムフィールドを追加