Best Way to Document Array Options in PHPdoc

Best way to document Array options in PHPDoc?

Just adding some tabulation will make it look good and easy to understand

/**
 * 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.
 **/

A nested list approach:

<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>

Result:

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.

If you want it to look fancy, with a bit of Css it will make wonders! xd

How to document an array of [type]?

From the documentation of phpDocumentor

The value represented by Type can be an array. The type MUST be defined following the format of one of the following options:

unspecified, no definition of the contents of the represented array is given. Example: @return array

specified containing a single type, the Type definition informs the reader of the type of each array element. Only one Type is then expected as element for a given array.

Example: @return int[]

Please note that mixed is also a single type and with this keyword it is possible to indicate that each array element contains any possible type.

specified containing multiple types, the Type definition informs the reader of the type of each array element. Each element can be of any of the given types. Example: @return (int|string)[]

Note
many IDEs probably do not support this notation yet.

Is there a way for phpDoc to document an array of objects as a parameter?

New version of PHP doc support /** @var sometype[] */ syntax. Even more complicated: /** @var (sometype|othertype)[] */. http://www.phpdoc.org/docs/latest/guides/types.html#arrays
PHPStorm also support this syntax.

PHP: How to document array when they are method parameters

If you have such a complex array with constraints for every single member, I wouldn't use an anonymous array but rather a well defined object. With an array, you can never be sure what it holds, that's somewhat like passing "Object" in e.g. Java, which you rarely would consider a good choice.

However, there is the possibility of a little hinting, when you array contains objects of a certain type as explained here, but that's not a really good answer to your question.

If you really need the parameter as an array, you might document it the way you proposed in the method's description; however, if you use an object as parameter, you'd have additional support in modern IDEs (IntelliSense and so on).

EDIT: I mean, for me the question would be "why would I want to use an anonymous array instead of a self defined type" - and besides simplicity (which will backfire as technical debt later if you maintain and extend your code), I cannot think of a reason, especially compared to what you gain in using a user defined type (self documented code, constraints visible and made explicit by standard methods and so on).

If you just need a dump of data, you might want to go with a simple array, but since you're already thinking about optional and required keys, that screams for a user defined type.

EDIT2: Regarding your comment about if your already have an array as source: I'm not sure whether you need to pass it on as an array or do "mapping" operations as soon as you receive the array (e.g. as $_POST or as return value from some third party library or PHP internal functions or such).

I suppose one could argue that it's not the model's business to interpret data generated by views (e.g. HTML forms which POST data), but rather the controller's resonsibility to react accordingly to the input and transfer the model in the appropriate state. What I mean by this is that you could do something like this if you receive e.g. an array as $_POST:

$customer = new Customer();
$customer->setId($_POST['id']);
$customer->setName($_POST['name']);
$customer->setTown($_POST['town']);

And handle errors as soon as you access the $customer, e.g. throwing exceptions if the name is not set (i.e. $_POST['name'] was empty or such). This way, you use the source array to call setters on the object instead of e.g. passing the array to a factory like Customer::buildByHttpPostData(array $data) and thereby delegating the knowledge of the view's details (names of HTML input tags and such).

Bottom line is, there's no "standard" way to declare required or optional array keys, and of course you can describe those constraints in the method description, but perhaps you can circumvent this by keeping with supported ways like PHPDoc comments on setters or getters.

Of course, there may be better ways to approach the problem, and perhaps somebody comes up with a better answer how to handle it.

How can I specify array of objects in PhpDoc

phpdoc themselves describe the use of arrays here:

1.4.4. Arrays
undefined: @return array
single type: @return int[]
multi type: @return (int|string)[]

The same should apply to variable definitions:

/* @var Type[] $arr */

Specify an array index type

In general, PhpStorm only support simple syntax, just as Sam has stated, e.g.

/**
 * @param string[] $options
 */

The code above described parameter which is array of strings.

Install Options completion plugin -- it supports new proposed syntax for hashes (describing array keys and its' types) in PHPDoc: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-describing-hashes

This plugin will add code completion for array keys.

<?php
class Element {
    /**
     * Initializes this class with the given options.
     *
     * @param array $options {
     *     @var bool   $required Whether this element is required
     *     @var string $label    The display name for this element
     * }
     */
    public function __construct(array $options = array())
    {
        // some code here
    }
}

new Element(['label' => 'Bob', '|' ]);
//                              | Ctrl+Space will show supported attributes

NOTE: Main purpose of this plugin is to offer array keys completion -- I'm not sure how well it supports type resolutions for each of array elements (in case if they are different like in your example).

Comment associative array in PHP Documentor

You can't document each key, but you can tell phpDocumentor what type it is.

You could do something like this:

/**
 * Form the array like this:
 * <code>
 * $array = array(
 *   'id'      => 'foo',          // the id
 *   'class'   => 'myClass',     // the class
 * );
 * 
 * </code>
 *
 * @var array[string]string 
 */
$array;

PHPDoc type hinting for array of objects?

Use:

/* @var $objs Test[] */
foreach ($objs as $obj) {
    // Typehinting will occur after typing $obj->
}

when typehinting inline variables, and

class A {
    /** @var Test[] */
    private $items;
}

for class properties.

Previous answer from '09 when PHPDoc (and IDEs like Zend Studio and Netbeans) didn't have that option:

The best you can do is say,

foreach ($Objs as $Obj)
{
    /* @var $Obj Test */
    // You should be able to get hinting after the preceding line if you type $Obj->
}

I do that a lot in Zend Studio. Don't know about other editors, but it ought to work.

Best Way to Document Array Options in PHPdoc