php - PHPDocで配列オプションを文書化する最良の方法は？

Question

関数に渡される配列オプションのマルチツリー構造を説明する、読みやすく理解しやすいドキュメントを作成するのに苦労しています。

配列構造の例を次に示します。

$arr = [
   'fields' => [
       'title' => [
           'name'     => 'Document.title',
           'format'   => 'string',
           'readonly' => true
       ]
   ]
];

上記の配列には多くの可能なオプションがありますが、これはその構造を理解する関数へのパラメーターとして使用されます。

function doSomething(array $arr) { ... }

PHPDocで配列をどのように構造化するかを文書化したいのですが、正しいアプローチが何であるかわかりません。

これが私が今持っているものです。

/**
 * Holds configuration settings for each field in a model.
 * Defining the field options
 *
 * array['fields'] array Defines the feilds to be shown by scaffolding.
 * array['fields'][fieldName] array Defines the options for a field, or just enables the field if array is not applied.
 * array['fields'][fieldName]['name'] string Overrides the field name (default is the array key)
 * array['fields'][fieldName]['model'] string (optional) Overrides the model if the field is a belongsTo assoicated value.
 * array['fields'][fieldName]['width'] string Defines the width of the field for paginate views. Examples are "100px" or "auto"
 * array['fields'][fieldName]['align'] string Alignment types for paginate views (left, right, center)
 * array['fields'][fieldName]['format'] string Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)
 * array['fields'][fieldName]['title'] string Changes the field name shown in views.
 * array['fields'][fieldName]['desc'] string The description shown in edit/create views.
 * array['fields'][fieldName]['readonly'] boolean True prevents users from changing the value in edit/create forms.
 * array['fields'][fieldName]['type'] string Defines the input type used by the Form helper (example 'password')
 * array['fields'][fieldName]['options'] array Defines a list of string options for drop down lists.
 * array['fields'][fieldName]['editor'] boolean If set to True will show a WYSIWYG editor for this field.
 * array['fields'][fieldName]['default'] string The default value for create forms.
 *
 * @param array $arr (See above)
 * @return Object A new editor object.
 **/

私の問題は、HTMLドキュメントが生成されるときに、それがあまりうまくフォーマットされていないことです。さらに、上記がアレイ構造を明確に説明しているのかわかりません。

別のアプローチはありますか？

Answer 1

これは私が代わりにそれを行う方法です：

/**
 * Class constructor.
 *
 * @param array $params Array containing the necessary params.
 *    $params = [
 *      'hostname'     => (string) DB hostname. Required.
 *      'databaseName' => (string) DB name. Required.
 *      'username'     => (string) DB username. Required.
 *      'password'     => (string) DB password. Required.
 *      'port'         => (int) DB port. Default: 1433.
 *      'sublevel'     => [
 *          'key' => (\stdClass) Value description.
 *      ]
 *    ]
 */
 public function __construct(array $params){}

とてもきれいで、どうある$paramsべきかを理解するのは簡単だと思います。

Answer 2

次のようなキーを指定できるphpstormのプラグインを作成しました。

（基本的には、@ siannoneの形式のわずかに厳密なバージョンです）

/**
 * @param array $arr = [
 *     'fields' => [ // Defines the feilds to be shown by scaffolding
 *         $anyKey => [
 *             'name' => 'sale', // Overrides the field name (default is the array key)
 *             'model' => 'customer', // (optional) Overrides the model if the field is a belongsTo associated value.
 *             'width' => '100px', // Defines the width of the field for paginate views. Examples are "100px" or "auto"
 *             'align' => 'center', // Alignment types for paginate views (left, right, center)
 *             'format' => 'nice', // Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)
 *             'title' => 'Sale', // Changes the field name shown in views.
 *             'desc' => 'A deal another person that results in money', // The description shown in edit/create views.
 *             'readonly' => false, // True prevents users from changing the value in edit/create forms.
 *             'type' => 'password', // Defines the input type used by the Form helper
 *             'options' => ['option1', 'option2'], // Defines a list of string options for drop down lists.
 *             'editor' => false, // If set to True will show a WYSIWYG editor for this field.
 *             'default' => '', // The default value for create forms.
 *         ],
 *     ],
 * ]
 */
public static function processForm($arr)
{
    $fieldName = 'sale';
    $arr['fields'][$fieldName][''];
}

@returnキーを指定することもできます。

/**
 * @return array [
 *     'success' => true,
 *     'formObject' => new Form,
 *     'errors' => [],
 * ]
 */
public static function processForm($arr);

Answer 3

いくつかの表を追加するだけで、見栄えが良く、理解しやすくなります

/**
 * Holds configuration settings for each field in a model.
 * Defining the field options
 *
 * array['fields']              array Defines the fields to be shown by scaffolding.
 *          [fieldName]         array Defines the options for a field, or just enables the field if array is not applied.
 *              ['name']        string Overrides the field name (default is the array key)
 *              ['model']       string (optional) Overrides the model if the field is a belongsTo associated value.
 *              ['width']       string Defines the width of the field for paginate views. Examples are "100px" or "auto"
 *              ['align']       string Alignment types for paginate views (left, right, center)
 *              ['format']      string Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)
 *              ['title']       string Changes the field name shown in views.
 *              ['desc']        string The description shown in edit/create views.
 *              ['readonly']    boolean True prevents users from changing the value in edit/create forms.
 *              ['type']        string Defines the input type used by the Form helper (example 'password')
 *              ['options']     array Defines a list of string options for drop down lists.
 *              ['editor']      boolean If set to True will show a WYSIWYG editor for this field.
 *              ['default']     string The default value for create forms.
 *
 * @param array $arr (See above)
 * @return Object A new editor object.
 **/

ネストされたリストのアプローチ：

<ul>
    <li>
        array['fields'] array Defines the fields to be shown by scaffolding.
        <ul>
            <li>
                [fieldName]             array Defines the options for a field, or just enables the field if array is not applied.
                <ul>
                    <li> ['name']       <i><u>string</u></i> Overrides the field name (default is the array key) </li>
                    <li> ['model']      <i><u>string</u></i> (optional) Overrides the model if the field is a belongsTo associated value.</li>
                    <li> ['width']      <i><u>string</u></i> Defines the width of the field for paginate views. Examples are "100px" or "auto"</li>
                    <li> ['align']      <i><u>string</u></i> Alignment types for paginate views (left, right, center)</li>
                    <li> ['format']     <i><u>string</u></i> Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)</li>
                    <li> ['title']      <i><u>string</u></i> Changes the field name shown in views.</li>
                    <li> ['desc']       <i><u>string</u></i> The description shown in edit/create views.</li>
                    <li> ['readonly']   <i><u>boolean</u></i> True prevents users from changing the value in edit/create forms.</li>
                    <li> ['type']       <i><u>string</u></i> Defines the input type used by the Form helper (example 'password')</li>
                    <li> ['options']    <i><u>array</u></i> Defines a list of string options for drop down lists.</li>
                    <li> ['editor']     <i><u>boolean</u></i> If set to True will show a WYSIWYG editor for this field.</li>
                    <li> ['default']    <i><u>string</u></i> The default value for create forms.</li>
                </ul>
            </li>
        </ul>
    </li>
 </ul>

結果：

• array['fields']arrayスキャフォールディングによって表示されるフィールドを定義します。
  • [fieldName] arrayフィールドのオプションを定義します。配列が適用されていない場合は、フィールドを有効にします。
    • ['name'] stringフィールド名をオーバーライドします（デフォルトは配列キーです）
    • ['model'] string（オプション）フィールドがbelongsToに関連付けられた値である場合、モデルをオーバーライドします。
    • ['width'] 文字列ページ分割ビューのフィールドの幅を定義します。例は「100px」または「auto」です
    • ['align'] stringページ分割ビューの配置タイプ（左、右、中央）
    • ['format'] 文字列ページ番号フィールドのフォーマットオプション。オプションには、（'currency'、'nice'、'niceShort'、'timeAgoInWords'または有効なDate（）形式）が含まれます。
    • ['title'] stringビューに表示されるフィールド名を変更します。
    • ['desc'] 文字列編集/作成ビューに表示される説明。
    • ['readonly'] boolean Trueは、ユーザーが編集/作成フォームの値を変更できないようにします。
    • ['type'] stringフォームヘルパーが使用する入力タイプを定義します（例'password'）
    • ['options'] arrayドロップダウンリストの文字列オプションのリストを定義します。
    • ['editor'] boolean Trueに設定すると、このフィールドのWYSIWYGエディターが表示されます。
    • ['default'] stringフォーム作成のデフォルト値。

あなたがそれを派手に見せたいのなら、少しのCssでそれは不思議に思うでしょう！xd

Answer 4

広く受け入れられているキータイプのドキュメント形式の中で、ここで人気のあるものをいくつか挙げておきます。

詩篇/ PHPStan /ファンフォーマット

/** @param array{foo: string, bar: int} $args */

ボーナスとして、ツールを使用した静的コード分析にも使用できます

Wordpressフォーマット

/**
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 */

_{両方ともdeep-assoc-completionプラグインでサポートされています}

Answer 5

配列の代わりにオブジェクトを使用できますか？それは文書化を容易にするでしょう。

class Field {

    /**
     * The name of the thing.
     * @var string
     */
    protected $name;

    protected $model;
    protected $width;
    //...

    public function getName() {...}
    public function setName() {...}
    //...
}

class FieldList implements SomeKindOfIterator {

    /**
     * Some fields.
     * @var Field[]
     */
    protected $fields = array();

    /**
     * ...
     */
    public function push(Field $field) {
         $this->fields[] = $field;
    }

    //...
}

次に、クラスが必要な場所でタイプヒントを使用できます。

/**
 * Do something.
 * @param FieldList $field_list The field.
 */
function doSomething(FieldList $field_list) {...}

Answer 6

オブジェクト表記のマークダウン構文（MSON）の方が適している場合があります。

例

/**
 * @param array $config
 *   + app (string, required) - app directory name
 *   + view (string, required) - view directory name
 *   + type (enum[string]) - site type
 *     + pc - PC version
 *     + wap - mobile version
 *     + other - other, default value
 *   + table_prefix (string) - database table prefix
 */

Answer 7

私はちょっとこれが好きです：

 * @param array $doc
 *          'type'=>Doc::MY_DOC_TYPE,
 *          'created'=>$now,
 *          'modified'=>$now

初期化された場所からコードを貼り付けるだけで、すばやく簡単にできます。

Answer 8

PHPの配列は、実際には匿名の構造体に似ています。

任意のデータ構造の場合、スキーマバリデーターは多数ありますが、残念ながら、型ヒントでは広くサポートされていません。おそらく、いくつかの一般的なスキームにはプラグインがありますか？問題は、1つまたはいくつかの場所でしか機能しないことです。IDEで正しいことが機能するかもしれませんが、静的分析を実行すると、すべてが地獄に落ちる可能性があります。

プラグインなど、スキームをサポートしていない他のツールが単にそれを無視するように、物事を分離するように注意する必要があります。

PHPDocはどこでもサポートされる傾向がありますが、非常に制限されています。

多くの場合、提案がありますが、実際に良い基準はありません。ほとんどのソリューションは非標準であり、広くサポートされていない、制限のある部分的なハッキングまたは純粋に表面的なものです（ドキュメント）。

特定の場所に特定の実装がありますが、PHP自体に広く普及しているものはありません。PHP IDEで独自のスキーマを作成することはできますが、名前にPHPが含まれている場合でも、適切なコードブリッジが不足している傾向があります。

フィールド構造体は個別に定義する必要があります。外部データ構造は、@key fields field[]多次元配列として表すのではなく、擬似コードとして使用されます。概念的かつ紛らわしいことに、次のことまで行うことができます。

@start struct custom
@key \stdClass *
@end struct

@start struct fields
@key string hostname
@key string databaseName
@key string password
@key int port=1433
@key custom|undefined sublevel
@end struct

@start struct connection
@key fields fields
@end struct

または、Cから盗んで、言語を発明します...

struct connection {
    struct fields {
        string hostname;
        string databaseName;
        string password;
        int port = 1433;
        custom optional sublevel {
            stdClass *;
        };
    };
};

構造体に基づいてスキーマを発明し、フラットとネストの両方を許可できます。ネストをデフォルトにする必要があります。再利用するために必要なだけアクセスできるように定義する必要があります。

珍しいアプローチは、代わりにオブジェクトを使用することです。これは、配列アクセスなどのインターフェースの使用を伴う必要はありません。PHPでは、オブジェクトはプロパティの配列をラップします。配列をオブジェクト（実装なし、プロパティのみ）にキャストして戻すことができます。

代わりにオブジェクトを連想配列として使用する場合（$ array[$key]対$object->{$ key}）、ダミーオブジェクトを作成して少なくともIDEをだますことができます...

final class PersonStruct {
    /** @var int */
    public $x;

    /** @var int $y */

    public int $z;
}

これらの3つのオプションのうち、機能する場合と機能しない場合は、使用するツールによって異なります。

その後、嘘をつくことができます...

/** @var PersonStruct $ps */
$ps = (object)['x' => 0, 'y' => 1, 'z' => 2];

/**
 * @param PersonStruct $ps
 * @return PersonStruct
 */
function f(object $ps):object {
    return $ps;
}

/**
 * @param PersonStruct $ps
 * @return PersonStruct
 */
function f(stdClass $ps):stdClass {
    return $ps;
}

これに伴う問題は、配列をオブジェクトに変換することを意味することです。これには、パフォーマンスへの影響と、値渡しから参照渡しへの変更の両方があります。どちらが速いかは議論の余地があります。理論的には配列の方が高速ですが、オブジェクトにはデフォルトで参照という利点があり、PHPとは異なりオブジェクトを配列から分離するJSONでより適切に機能します。

->{key}オブジェクトのプロパティは単なるPHP配列ですが（の代わりに使用）、オブジェクトは型ヒントに関してあまり適切に設定されていない可能性のあるプロパティもサポートしていません[key]。他の奇妙なことの可能性があります。

パフォーマンスが本当に懸念される場合は、PHPをコンパイル言語に変えることができます。同様に、インターフェイスを拡張してオブジェクトをコンパイル可能にすることができます。これは、OOPとオートコンプリートですべてを実行できる場合と同じですが、ラップするプロパティを指定してクラスをインライン化するのと同じことを実行できます。使用法をマッチングメソッドの内容にほぼ置き換えるためのリフレクション。いくつかの追加ビットが必要です（インライン化または手続き型への変換、ラップする単一のプロパティ、または複数のプロパティなどをマークします）。

概念は、ボクシングとアンボクシングに似ています。SAのサポートと、IDE（オートコンプリート、チェックなど）、アナライザー、ツールなどの幅広いサポートに本当に夢中になっている場合は、それが唯一の方法かもしれません。

Answer 9

これはディレクティブではなく純粋に表示であり、ドキュメント内のスペースの書式設定を保持する必要があるため、文字の壁ではなくインデントを使用して読みやすくする傾向があります。

 * array['fields'] array Defines the feilds to be shown by scaffolding.
 *           [fieldName] array Defines the options for a field, or just enables
 *                             the field if array is not applied.
 *                 ['name'] string Overrides the field name (default is the
 *                                  array key)
 *                 ['model'] string (optional) Overrides the model if the field is
 *                                  a belongsTo assoicated value.
 *                 ['width'] string Defines the width of the field for paginate
 *                                  views.
 *                                  Examples are "100px" or "auto"
 *                 ['align'] string Alignment types for paginate views (left, 
 *                                 right, center)
 *                 ['format'] string Formatting options for paginate fields.
 *                                   Options include 'currency', 'nice',
 *                                  'niceShort', 'timeAgoInWords' or a valid 
 *                                  Date() format)
 *                 ['title'] string Changes the field name shown in views.
 *                 ['desc'] string The description shown in edit/create views.
 *                 ['readonly'] boolean True prevents users from changing the
 *                                 value in edit/create forms.
 *                 ['type'] string Defines the input type used by the Form helper
 *                                  (example 'password')
 *                 ['options'] array Defines a list of string options for drop-
 *                                  down lists.
 *                 ['editor'] boolean If set to True will show a WYSIWYG editor
 *                                  for this field.
 *                 ['default'] string The default value for create forms.

インデント付きの実際のPHP配列定義を使用すると、さらにクリーンになります。