Friendica アドオン/プラグイン開発

アドオンやプラグインの機能の使い方の実例については、サンプルアドオン 'randplace' を参照してください。Facebook アドオンは、「アドオン」と「モジュール」の機能の両方を統合した例です。アドオンはイベントフックをインターセプトすることで動作します。アドオンは登録しなければなりません。モジュールは、特定のページリクエストを (URL パスによって) インターセプトすることで動作します。

プラグイン名にはスペースその他の区切り文字を含めることはできず、プラグイン名がファイル名および関数名として使われます。コメントブロック内で「わかりやすい」名前を付けることができます。各アドオンには、そのアドオン/プラグインの名前をベースにした install 関数と uninstall 関数の両方が含まれていなければなりません。たとえば、"plugin1name_install()" などです。これら 2 つの関数は引数を取らず、通常はそのプラグインで必要となるイベントフックの登録 (と登録解除) を行います。install 関数と uninstall 関数は、インストール後にプラグインが変更された場合にも呼び出されます (つまり再インストールされます)。したがって、uninstall 関数ではデータを破壊してはならず、install 関数ではデータがすでに存在している可能性を前提に動作するようにする必要があります。今後の拡張では、"setup" と "remove" が用意されるかもしれません。

プラグインには、次の 4 つのパラメータを持つコメントブロックが含まれている必要があります。

/*
* Name: My Great Plugin 
* Description: This is what my plugin does. It's really cool
* Version: 1.0
* Author: John Q. Public <john@myfriendicasite.com>
*/

インストール中にプラグインのフックを登録します。

register_hook($hookname, $file, $function);

$hookname は文字列で、既知の Friendica フックに対応します。

$file は Friendica トップレベルディレクトリからの相対パス名です。通常、これは 'addon/plugin_name/plugin_name.php' となる必要があります

$function は文字列で、フックが呼び出されたときに実行される関数の名前です。

フックコールバック関数は、少なくとも 1 つ、場合によっては 2 つの引数を渡されて呼び出されます。

function myhook_function(&$a, &$b) {


}

呼び出し側のデータを変更したい場合は、関数宣言時にこれらを参照変数 ('&' 付き) として宣言しなければなりません。

$a は Friendica の 'App' クラスで、Friendica の現在の状態に関するさまざまな情報が収められています。たとえば、呼び出されたのはどのモジュールか、構成に関する情報、フックが呼び出された時点でのページのコンテンツ、プロファイル、ユーザー情報などです。ほかの場所での使い方と統一するためにも、この引数については '$a' と呼ぶことを推奨します。

$b には好きな名前を付けることができます。この情報は現在の処理対象のフックに固有の情報で、一般的には即座に処理される情報や、使用、表示、または変更できる情報が含まれています。情報の内容を変更する場合は、必ず '&' を付けて宣言します。

モジュール

プラグイン/アドオンは「モジュール」としてふるまうこともでき、ある与えられた URL パスに対するすべてのページリクエストをインターセプトします。プラグインをモジュールとしてふるまうようにするには、そのプラグインで関数 "plugin_name_module()" を定義する必要があります。この関数は引数を取らず、関数内では何もする必要はありません。

この関数が存在する場合、"http://my.web.site/plugin_name" に対するすべてのページリクエストを受け取ることになり、追加の引数として任意の数の URL 要素が渡されます。これらの URL 要素は解析されて配列 $a->argv に収められ、URL 要素の数は $a->argc に収められます。たとえば、http://my.web.site/plugin/arg1/arg2 は "plugin" という名前のモジュールを探し、このモジュールの関数に $a という App 構造体 (これは多くのコンポーネントで利用できます) を渡します。その内容は具体的には次のようになります。
$a->argc = 3
$a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');

モジュールの関数にはしばしば関数 plugin_name_content(&$a) が含まれており、この関数はページボディのコンテンツを定義して返します。モジュールの関数には plugin_name_post(&$a) を含めることができ、この関数は _content 関数の前に呼び出され、一般に POST フォームの結果を処理します。また、plugin_name_init(&$a) という関数も用意することができ、この関数は早い時期に呼び出され、しばしばモジュールの初期化を行います。

現在用意されているフック:

'authenticate' - ユーザーがログインを試みたときに呼び出されます。
$b は配列です。
'username' => 入力されたユーザー名
'password' => 入力されたパスワード
'authenticated' => ユーザーを認証するには 0 以外の値をセットします。
'user_record' => 認証が成功した場合は、データベースから有効なユーザーレコードを返さなければなりません。

'logged_in' - ユーザーのログインが成功したときに呼び出されます。
$b には $a->user 配列が含まれます。

'display_item' - 投稿に書式設定して表示するときに呼び出されます。
$b は配列です。
'item' => データベースから取り出された項目 (配列) の詳細
'output' => ページに追加される前のこの項目の (文字列) HTML 表現

'post_local' - 近況の投稿またはコメントがローカルシステムに入力されたときに呼び出されます。
$b は、データベースに格納される情報の項目の配列です。
{注意: ボディコンテンツは bbcode で、HTML ではありません)

'post_local_end' - ローカルな近況の投稿またはコメントがローカルシステムに格納されたときに呼び出されます。
$b は、データベースに格納された情報の項目の配列です。
{注意: ボディコンテンツは bbcode で、HTML ではありません)

'post_remote' - ほかのソースから投稿を受信したときに呼び出されます。このフックは、ローカルなアクティビティまたはシステムの生成したメッセージを投稿する場合にも使われます。
$b は、データベースに格納される情報の項目の配列で、項目のボディは bbcode です。

'settings_form' - ユーザーの [Settings] ページの HTML を生成するときに呼び出されます。
$b は、最後の '</form>' タグの前の [Settings] ページの (文字列) HTML です。

'settings_post' - [Settings] ページが送信されたときに呼び出されます。
$b は $_POST 配列です。

'plugin_settings' - [Addon Settings] ページの HTML を生成するときに呼び出されます。
$b は、最後の '</form>' タグの前の [Addon Settings] ページの (文字列) HTML です。

'plugin_settings_post' - [Addon Settings] ページが送信されたときに呼び出されます。
$b は $_POST 配列です。

'profile_post' - プロファイルページが送信されたときに呼び出されます。
$b は $_POST 配列です。

'profile_edit' - プロファイル編集ページの出力の前に呼び出されます。
$b は配列です。
'profile' => データベースのプロファイル (配列) レコード
'entry' => 生成されたエントリの (文字列) HTML

'profile_advanced' - ユーザーのプロファイルページの [Profile] タブに対応する 'Advanced profile' の HTML が生成されたときに呼び出されます。
$b は、生成されたプロファイルの (文字列) HTML 表現です。
(プロファイル配列の詳細は $a->profile に格納されています)

'directory_item' - 項目に書式設定して表示するときに [Directory] ページから呼び出されます。
$b は配列です。
'contact' => データベースの該当ユーザーのコンタクト (配列) レコード
'entry' => 生成されたエントリの (文字列) HTML

'profile_sidebar_enter' - ページのサイドバーの「短い」プロファイルを生成する前に呼び出されます。
$b は (配列で) 該当ユーザーのプロファイルの配列です。

'profile_sidebar' - ページのサイドバーの「短い」プロファイルを生成するときに呼び出されます。
$b は配列です。
'profile' => データベースの該当ユーザーのプロファイル (配列) レコード
'entry' => 生成されたエントリの (文字列) HTML

'contact_block_end' - プロファイルのサイドバーのコンタクト/友達の書式設定が完了したときに呼び出されます。
$b は配列です。
'contacts' => コンタクトの配列
'output' => コンタクトブロックの (文字列) 生成された HTML

'bbcode' - bbcode から html への変換中に呼び出されます。
$b は (文字列) 変換されたテキストです。

'html2bbcode' - html から bbcode への変換中 (リモートメッセージ投稿など) に呼び出されます。
$b は (文字列) 変換されたテキストです。

'page_header' - ページナビゲーションセクションの構築後に呼び出されます。
$b は、ナビゲーション領域の (文字列) HTML です。

'personal_xrd' - 個人の XRD ファイルへの出力前に呼び出されます。
$b は配列です。
'user' => 該当する人のユーザーレコード
'xml' => 出力される完全な XML

'home_content' - ログインしていないユーザーに表示されるホームページのコンテンツの出力前に呼び出されます。
$b は、セクション領域の (文字列) HTML です。

'contact_edit' - [Contacts] ページから個人のコンタクトの詳細を編集するときに呼び出されます。
$b は (配列) です。
'contact' => 対象となるコンタクトのコンタクトレコード (配列)
'output' => コンタクト編集ページの (文字列) 生成された HTML

'contact_edit_post' - コンタクト編集ページを送信するときに呼び出されます。
$b は $_POST 配列です。

'init_1' - データベースがオープンされた直後、セッションがスタートする前に呼び出されます。
$b は使われないか、または渡されません。

'page_end' - HTML コンテンツ関連関数が完了した後に呼び出されます。
$b はコンテンツ div の (文字列) HTML です。

'avatar_lookup' - アバターを参照するときに呼び出されます。
$b は (配列) です。
'size' => 参照するアバターのサイズ
'email' => アバターを参照する電子メールアドレス
'url' => アバターの (文字列) 生成された URL

すべてのフックコールバックの完全なリストと出現ファイル (2012 年 2 月 14 日生成): 上に文書化されていないフックの詳細については、ソースを参照してください。

boot.php: call_hooks('login_hook',$o);

boot.php: call_hooks('profile_sidebar_enter', $profile);

boot.php: call_hooks('profile_sidebar', $arr);

boot.php: call_hooks("proc_run", $arr);

include/contact_selectors.php: call_hooks('network_to_name', $nets);

include/api.php: call_hooks('logged_in', $a->user);

include/api.php: call_hooks('logged_in', $a->user);

include/queue.php: call_hooks('queue_predeliver', $a, $r);

include/queue.php: call_hooks('queue_deliver', $a, $params);

include/text.php: call_hooks('contact_block_end', $arr);

include/text.php: call_hooks('smilie', $s);

include/text.php: call_hooks('prepare_body_init', $item);

include/text.php: call_hooks('prepare_body', $prep_arr);

include/text.php: call_hooks('prepare_body_final', $prep_arr);

include/nav.php: call_hooks('page_header', $a->page['nav']);

include/auth.php: call_hooks('authenticate', $addon_auth);

include/bbcode.php: call_hooks('bbcode',$Text);

include/oauth.php: call_hooks('logged_in', $a->user);

include/acl_selectors.php: call_hooks($a->module . 'pre' . $selname, $arr);

include/acl_selectors.php: call_hooks($a->module . 'post' . $selname, $o);

include/acl_selectors.php: call_hooks('contact_select_options', $x);

include/acl_selectors.php: call_hooks($a->module . 'pre' . $selname, $arr);

include/acl_selectors.php: call_hooks($a->module . 'post' . $selname, $o);

include/acl_selectors.php: call_hooks($a->module . 'pre' . $selname, $arr);

include/acl_selectors.php: call_hooks($a->module . 'post' . $selname, $o);

include/notifier.php: call_hooks('notifier_normal',$target_item);

include/notifier.php: call_hooks('notifier_end',$target_item);

include/items.php: call_hooks('atom_feed', $atom);

include/items.php: call_hooks('atom_feed_end', $atom);

include/items.php: call_hooks('atom_feed_end', $atom);

include/items.php: call_hooks('parse_atom', $arr);

include/items.php: call_hooks('post_remote',$arr);

include/items.php: call_hooks('atom_author', $o);

include/items.php: call_hooks('atom_entry', $o);

include/bb2diaspora.php: call_hooks('bb2diaspora',$Text);

include/cronhooks.php: call_hooks('cron', $d);

include/security.php: call_hooks('logged_in', $a->user);

include/html2bbcode.php: call_hooks('html2bbcode', $text);

include/Contact.php: call_hooks('remove_user',$r[0]);

include/Contact.php: call_hooks('contact_photo_menu', $args);

include/conversation.php: call_hooks('conversation_start',$cb);

include/conversation.php: call_hooks('render_location',$locate);

include/conversation.php: call_hooks('display_item', $arr);

include/conversation.php: call_hooks('render_location',$locate);

include/conversation.php: call_hooks('display_item', $arr);

include/conversation.php: call_hooks('item_photo_menu', $args);

include/conversation.php: call_hooks('jot_tool', $jotplugins);

include/conversation.php: call_hooks('jot_networks', $jotnets);

include/plugin.php:if(!function_exists('call_hooks')) {

include/plugin.php:function call_hooks($name, &$data = null) {

index.php: call_hooks('init_1');

index.php:call_hooks('app_menu', $arr);

index.php:call_hooks('page_end', $a->page['content']);

mod/photos.php: call_hooks('photo_post_init', $_POST);

mod/photos.php: call_hooks('photo_post_file',$ret);

mod/photos.php: call_hooks('photo_post_end',$foo);

mod/photos.php: call_hooks('photo_post_end',$foo);

mod/photos.php: call_hooks('photo_post_end',$foo);

mod/photos.php: call_hooks('photo_post_end',intval($item_id));

mod/photos.php: call_hooks('photo_upload_form',$ret);

mod/friendica.php: call_hooks('about_hook', $o);

mod/editpost.php: call_hooks('jot_tool', $jotplugins);

mod/editpost.php: call_hooks('jot_networks', $jotnets);

mod/parse_url.php: call_hooks('parse_link', $arr);

mod/home.php: call_hooks('home_init',$ret);

mod/home.php: call_hooks("home_content",$o);

mod/contacts.php: call_hooks('contact_edit_post', $_POST);

mod/contacts.php: call_hooks('contact_edit', $arr);

mod/settings.php: call_hooks('plugin_settings_post', $_POST);

mod/settings.php: call_hooks('connector_settings_post', $_POST);

mod/settings.php: call_hooks('settings_post', $_POST);

mod/settings.php: call_hooks('plugin_settings', $settings_addons);

mod/settings.php: call_hooks('connector_settings', $settings_connectors);

mod/settings.php: call_hooks('settings_form',$o);

mod/register.php: call_hooks('register_account', $newuid);

mod/like.php: call_hooks('post_local_end', $arr);

mod/xrd.php: call_hooks('personal_xrd', $arr);

mod/item.php: call_hooks('post_local_start', $_REQUEST);

mod/item.php: call_hooks('post_local',$datarray);

mod/item.php: call_hooks('post_local_end', $datarray);

mod/profile.php: call_hooks('profile_advanced',$o);

mod/profiles.php: call_hooks('profile_post', $_POST);

mod/profiles.php: call_hooks('profile_edit', $arr);

mod/tagger.php: call_hooks('post_local_end', $arr);

mod/cb.php: call_hooks('cb_init');

mod/cb.php: call_hooks('cb_post', $_POST);

mod/cb.php: call_hooks('cb_afterpost');

mod/cb.php: call_hooks('cb_content', $o);

mod/directory.php: call_hooks('directory_item', $arr);