Pickles 2 には、プラグインを組み込む機能があります。
プラグインは、次の手順で組み込みます。
composer.json の require にプラグインパッケージ情報を設定する$ composer update を実行し、プラグインパッケージをインストールするpx-files/config.php の $conf->funcs にプラグインを設定するPackagist に登録されているパッケージを利用する場合は、require にパッケージ名とバージョンを追加します。
{
"require": {
"pickles2/px2-sitemapexcel": "^2.0"
}
}
パッケージが Packagist に登録されていない場合、次のように、repositories にパッケージのURLを設定する必要があります。
{
"repositories": [
{
"type": "git",
"url": "https://github.com/tomk79/px2-page-list-generator.git"
}
],
"require": {
"tomk79/px2-page-list-generator": "dev-master"
}
}
更新したパッケージ情報を反映します。
$ composer update
パッケージのインストールが成功したら、px-files/config.php に、プラグインを設定します。プラグインの設定方法やオプションは、プラグインによってそれぞれ異なります。詳しくはプラグインのドキュメントを参照してください。
次の記述例は、config.php の $conf->funcs->before_sitemap にプラグインを設定した例です。
<?php
return call_user_func( function(){
/* 中略 */
// -------- functions --------
$conf->funcs = new stdClass;
// funcs: Before sitemap
// サイトマップ読み込みの前に実行するプラグインを設定します。
$conf->funcs->before_sitemap = [
// PX=clearcache
'picklesFramework2\commands\clearcache::register' ,
// PX=config
'picklesFramework2\commands\config::register' ,
// PX=phpinfo
'picklesFramework2\commands\phpinfo::register' ,
// sitemapExcel
'tomk79\pickles2\sitemap_excel\pickles_sitemap_excel::exec'
];
/* 中略 */
return $conf;
} );
プラグインには次の種類があります。
before_sitemap、before_content、before_output は、 Pickles 2 が処理するすべてのリクエストに対して適用されるプラグインです。
processor は、コンテンツの拡張子によって別々のプラグインを設定することができます。
Pickles 2 の処理は、おおまかに次の順で行われます。
この流れの、それぞれの間でプラグインを実行することができます。
それぞれの実行タイミングに対して複数のプラグイン処理を配列で設定できます。 処理は、配列の先頭から順に実行されます。
パラメータ PX で実行するPXコマンドは、プラグインの1つとして組み込まれています。
次のサンプルのプラグインは、それぞれPXコマンドを登録するように実装されたものです。
$conf->funcs->before_sitemap = [
// PX=clearcache
'picklesFramework2\commands\clearcache::register' ,
// PX=config
'picklesFramework2\commands\config::register' ,
// PX=phpinfo
'picklesFramework2\commands\phpinfo::register'
];
テーマも同様に、processorの1つとして実装されています。次のに示すコードで設定されているのが、 テーマを処理するプラグイン pickles2/px2-multitheme です。
$conf->funcs->processor->html = [
// テーマ
'theme'=>'tomk79\pickles2\multitheme\theme::exec('.json_encode([
'param_theme_switch'=>'THEME',
'cookie_theme_switch'=>'THEME',
'path_theme_collection'=>'./px-files/themes/',
'attr_bowl_name_by'=>'data-contents-area',
'default_theme_id'=>'pickles2'
]).')' ,
];
ここでは、マークダウンコンテンツを処理する processor を例に、プラグイン開発の基礎について、処理の流れを追って説明します。
プラグインを実装したPHPファイルのパスを composer.json の autoload に追記して、ロードするように設定します。
{
"autoload": {
"files": [
"px-files/_sys/php/myplugin.php"
]
}
}
追記したら、composer update を実行してください。
$ composer update
プラグインを導入する設定コードが次のサンプルです。
// px-files/config.php
$conf->funcs->processor->md = [
// Markdown文法を処理する
'myidentity\myplugin\myclass::myfunction' ,
// html の処理を追加
$conf->funcs->processor->html ,
];
$conf->funcs->processor->md に設定された processor は、拡張子に .md が付加されたコンテンツ(例：index.html.md など)に対して有効です。このサンプルでは、マークダウン書式を処理した後に、HTMLに対する一般的な処理を追加するために、最後に $conf->funcs->processor->html を設定しています。
コンフィグに設定された、myidentity\myplugin\myclass::myfunction というメソッドが、プラグインとして呼ばれます。この設定には、名前領域とクラス名、メソッド名までが含まれた名前として与えてください。static に呼び出せる必要があります。
namespace名、クラス名、メソッド名は、制作するプラグインの機能や名前に応じて適宜付け替えてください。他のプラグインとたまたま同じ名前になってしまうとエラーの原因になりえます。namespaceの先頭に開発者の名前やID名などを含めておくとよいでしょう。
myidentity\myplugin\myclass::myfunction({"JSON":"Value"}) のように、引数にJSONを与えることもできます。
次のコードは、受け側のプラグインの実装です。
<?php
/**
* processor "*.md"
*/
namespace myidentity\myplugin;
/**
* processor "*.md" class
*/
class myclass{
/**
* 変換処理の実行
* @param object $px Picklesオブジェクト
* @param object $json プラグイン設定
*/
public static function myfunction( $px, $json ){
foreach( $px->bowl()->get_keys() as $key ){
$src = $px->bowl()->get_clean( $key );
$src = \Michelf\MarkdownExtra::defaultTransform($src);
$px->bowl()->replace( $src, $key );
}
return true;
}
}
処理の内容を見てみます。
public static function myfunction( $px, $json ){
/* 中略 */
return true;
}
引数は、 Pickles 2 のコアオブジェクト $px が渡されます。
この例では使用していませんが、第2引数 $json に、コンフィグに設定した JSON オブジェクトを受け取ることができます。
Pickles Framework は返却値を評価しません。このメソッドは、常に true を返して終了します。
コンテンツが生成したコードは、$px->bowl() オブジェクトに格納されています。
コンテンツコードはキーと値で構造化して管理されています。 $px->bowl()->get_keys() から、すべてのコンテンツのキーを取得しています。
foreach( $px->bowl()->get_keys() as $key ){
/* 中略 */
}
次に、コンテンツのキーを使って、bowl からコンテンツの入出力を行います。
$px->bowl()->get_clean( $key ) でコンテンツコードを取り出し、$px->bowl()->replace( $src, $key ) で格納しなおしています。
foreach( $px->bowl()->get_keys() as $key ){
$src = $px->bowl()->get_clean( $key );
/* 中略 */
$px->bowl()->replace( $src, $key );
}
取り出してすぐのコードを格納しなおしただけでは結果は変わりません。取り出したコード $src を加工しているのが次の部分です。
$src = \Michelf\MarkdownExtra::defaultTransform($src);
この例は、マークダウン文法で書かれたコンテンツコードを受け取り、HTMLに変換して再格納しています(Packagistのパッケージ michelf/php-markdown を利用)。
PXコマンド は、Pickles Framework の独自の拡張機能を提供するインターフェイスです。 $px->pxcmd()->register() を通じて、プラグインから追加することができます。
次のコードは、PXコマンドを追加するプラグインの実装例です。
<?php
/**
* PX Commands "myCommand"
*/
namespace myidentity\myplugin;
/**
* PX Commands "myCommand"
*/
class myCommand{
/**
* Starting function
* @param object $px Picklesオブジェクト
* @param object $json プラグインオプション
*/
public static function myfunction( $px, $json ){
$px->pxcmd()->register('mycommand', function($px){
echo "myCommand!";
exit;
});
}
}
この例では、 myidentity\myplugin\myCommand::myfunction がプラグインの物理名です。このメソッドを、 config.php の $conf->funcs のどこか(多くの場合 before_sitemap が適切です) に設定して使用します。
このPXコマンドを設定して、 $ php .px_execute.php /?PX=mycommand を実行すると、文字列 myCommand が表示されるはずです。
開発したプラグインを公開すれば、composer を通じて誰でも利用できるようになります。
composer が対応していればどこでも利用可能です。Github、Bitbucket などのVCSホスティングサービスが利用できます。詳しくは composer のマニュアルを参照してください。
composer.json をリポジトリのルート階層に置き、次のように編集してください。
作成したパッケージは、PHPのパッケージ管理サービス Packagist に登録すると、簡単に呼び出せるようになります。
Packagistへの登録は必須ではありません。登録しない場合は、利用者側が composer.json の repository にリポジトリ情報を記載することで、利用することができます。