フック

各フックには、フック自体の説明（エントリポイントやこのフックの目的など）とパラメーターの説明（PHPフックの場合のみ）を含むコメントが必要です。

フックベースは、こちら（英語）から入手できます。

一般情報

  1. フックは、開発者が機能を拡張するために使用します。したがって、フックにはできるだけ多くのパラメーターを含めることが望ましいです。
  2. フックの名前には、関数の名前が含まれている必要があります。
  3. プレフィックス（接頭辞）は禁止されています。サフィックス（接尾辞）のみが許可されます。
  4. 多数のフックを含む複雑な関数がある場合は、次の例を使用してフックに名前を付けることができます。

関数

get_cart_product_data

フック

fn_set_hook('get_cart_product_data_post_options', $product['product_id'], $_pdata, $product);
  1. フックのパラメータを列挙するときは、必ず関数で受け付けるパラメータを最初に配置してください。SQLフックだけは例外で、必要なものはすべてparams変数に含まれています。
  2. クラス内のフックには、名前に呼び出し元のクラスの名前が含まれている必要があります。
  3. クラス内のフックは、常にクラスのインスタンスを最初のパラメータとして渡す必要があります。
<?php

class Patterns
{
    public function save($style_id, $style, $uploaded_data)
    {
        ...

        /**
         * Executes before saving the uploaded pattern files, allows you to modify the uploaded files and their location.
         *
         * @param \Tygh\Themes\Patterns $this          Patterns instance
         * @param string                $style_id      Style name
         * @param array                 $style         Style data
         * @param array                 $uploaded_data Uploaded files
         * @param string                $path          Path where patterns will be saved
         * @param string                $rel_path      Relative patterns path
         */
        fn_set_hook('patterns_save', $this, $style_id, $style, $uploaded_data, $path, $rel_path);

        ...

フックを追加する方法と場所

各関数には、少なくとも2つのフックが含まれている必要があると定義しています。

  1. 関数の最初にある get_product_name_pre のようなプリフィックス。関数が受け取るすべてのパラメーターは、このフックに渡される必要があります。
  2. 関数の最後にある get_product_name_postのようなポストプリフィックス。まず関数が受け取るすべてのパラメータ、次に関数が返すパラメータ、そしてその他の補助的なパラメータの順で、パラメータをリストアップします。

また、他の追加のフックがあるかもしれません。

  1. get_product_name のようなSQLフック。すべてのSQL変数がこのフックに渡されます。不要だと思われる場合でも $fields, $condition, $sorting, $limit などの値はすべて作成することをお勧めします。空のままでもかまいません。例えば：

例

fn_set_hook('get_product_name', $product_id, $lang_code, $as_array, $field_list, $join, $condition);
  1. 追加フック。例として、商品選択で説明します。
fn_set_hook('get_products_before_select', $params, $join, $condition, $u_condition, $inventory_join_cond, $sortings, $total, $items_per_page, $lang_code, $having);

一部のフックはこれらの規格に準拠していません。

この場合、次のようなコメントを追加します。

/**
 * 非推奨：このフックはバージョン 4.x または 3.3.x で削除されます。代わりに get_product_price_pre を使用してください。
 */

そして、規格に従ったフックも追加します。

私たちの場合は get_product_price_pre です。

関数に新しいパラメーターを追加するとき、古いフックを廃止したり、新しいフックを追加したりすることはありません。代わりに、このパラメーターを既存のフックの最後に追加します。この場合、パラメータの正しい順序は無視できます。

フックの標準形式

フックベースから、コメントの形式を以下に示します。

PHPのフックと関数

コメントの形式は、PHP Documentor から借りました。

このフォーマットは、あらゆる場所およびすべての機能に適用されます。

Doxygen は、ドキュメントを生成するために使用されます（マニュアル）。

コメントの書き方：主なルールと推奨事項

  1. コメントは大文字で始まります。コメントの最後にピリオドはありません。
  2. 機能の目的を説明する動詞は、三人称単数形で使用されます。例：Gets user data
  3. 変数の名前と値、ファイルパス、ファイル名、その他の固有名詞をイタリック体で強調表示します（HTMLタグで使用）。例：関数foo(in foo/bar/functions)はパラメーター$barを受け取ります
  4. 説明では、関数はclass::function;として定義されています。クラスのない関数はとして定義され::functionます。例えば：<？php / ** … * –period-定義されている場合、期間ごとにページを取得します。:: fn_create_periods </ li> * … * / ？>
  5. 変数を説明して、この関数で変数が使用される理由を明確にします。
  1. コメントは大文字で始まります。コメントの最後にピリオドはありません。
  2. 関数の目的を説明する動詞は、三人称単数形で使用されます。たとえば、Gets user dataなどです。
  3. 変数の名前と値、ファイルパス、ファイル名、その他の固有名詞を斜体で強調表示します（HTMLタグで使用）。例：Function foo(in foo/bar/functions) accepts parameter $bar
  4. 説明の中では、関数は class::functionと定義され、クラスのない関数は::functionとして定義されます。

例

<?php

/** ...
*      - period - If defined, get pages by time period. ::fn_create_periods</li>
* ...
*/
?>
  1. なぜその変数がこの関数で使われているのかがわかるように記述します。

例

<?php

/**
 * Processes cart data after calculating all prices and other data (taxes, shippings etc)
 *
 * @param array  $cart               Cart data
 * @param array  $cart_products      Cart products
 * @param array  $auth               Auth data
 * @param string $calculate_shipping // 1-letter flag
 *      A - calculate all available methods
 *      E - calculate selected methods only (from cart[shipping])
 *      S - skip calculation
 * @param bool $calculate_taxes       Flag determines if taxes should be calculated
 * @param bool $apply_cart_promotions Flag determines if promotions should be applied to the cart
 */
fn_set_hook('calculate_cart', $cart, $cart_products, $auth, $calculate_shipping, $calculate_taxes, $apply_cart_promotions);
?>

<?php

/**
 * Change SQL parameters for product data select
 *
 * @param int $product_id Product ID
 * @param string $field_list List of fields for retrieving
 * @param string $join String with the complete JOIN information (JOIN type, tables and fields) for an SQL-query
 * @param mixed $auth Array with authorization data
 * @param string $lang_code Two-letter language code (e.g. 'en', 'ru', etc.)
 * @param string $condition Condition for selecting product data
 */
fn_set_hook('get_product_data', $product_id, $field_list, $join, $auth, $lang_code, $condition);
?>

コメントはフックの直前に配置する必要があります。

TPLフック

Smarty テンプレート

{** Dynamic menu item (on the navigation) *}
{hook name="index:dynamic_menu_item"}
...
{/hook}

{** Hooks for CSS styles *}
{hook name="index:styles"}{/hook}

開始タグは常に2つの「*」を使用し、終了タグは1つの「*」を使用する必要があります。このようにして、通常のコメントはフックコメントと区別されます。

JSフック

例

/**
 * Hook description
 */
var hook_data = {
    'append_obj_content': append_obj_content, // int Id of bla bla
    'var_prefix': prefix, // string Prefix of var
    'object_html': unescape(append_obj.html()), // string Object
    'var_id': id, // int ID of var
    'item_id': js_items[id] // int Item ID
};

$.ceEvent('trigger', 'ce.picker_add_js_item', [hook_data]);

最初にイベントの説明を含むコメント、2番目にパラメーターを含むオブジェクトの変数、3番目にイベントの呼び出しを行います。

渡されたパラメーターへのコメントでは、最初の単語は変数のタイプであり、残りは説明です。