[wp-trac] [WordPress Trac] #57299: Implement array key type notation

[WordPress Trac]

#57299: Implement array key type notation
-------------------------+-------------------------------------
 Reporter:  johnbillion  |       Owner:  (none)
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  General      |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  2nd-opinion  |     Focuses:  docs, coding-standards
-------------------------+-------------------------------------

Comment (by GaryJ):

 When the keys are known, you can also use ''Array Shapes'':

 - https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
 - https://blog.jetbrains.com/phpstorm/2022/12/phpstorm-2022-3-whats-
 new/#support_iteration_over_list_array_shapes
 - https://psalm.dev/docs/annotating_code/type_syntax/array_types/#array-
 shapes

 It's a step further than the regular `array<string, array>` format (which
 itself is more descriptive than just `array`), but relatively well
 supported amongst tooling.

 As an example, the `add_settings_field()` DocBlock would have a
 [https://github.com/WordPress/wordpress-develop/blob/6.1/src/wp-
 admin/includes/template.php#L1651-L1659 last param tag] go from the custom
 WP format of:

 {{{
  * @param array    $args {
  *     Optional. Extra arguments that get passed to the callback function.
  *
  *     @type string $label_for When supplied, the setting title will be
 wrapped
  *                             in a `<label>` element, its `for` attribute
 populated
  *                             with this value.
  *     @type string $class     CSS Class to be added to the `<tr>` element
 when the
  *                             field is output.
  * }
 }}}

 to:

 {{{
  * @param array{label_for: string, class: string} $args
 }}}

 ... which can then be used by IDEs for autocompletion and validated
 against with static analysis tooling.

 One concern might be that there's no longer room for a description by each
 key. It would need testing in the tooling, but it may be that the rest of
 the param tag description is unaffected and so the following may work for
 every reader:

 {{{
  * @param array{label_for: string, class: string} $args {
  *     Optional. Extra arguments that get passed to the callback function.
  *
  *     @type string $label_for When supplied, the setting title will be
 wrapped
  *                             in a `<label>` element, its `for` attribute
 populated
  *                             with this value.
  *     @type string $class     CSS Class to be added to the `<tr>` element
 when the
  *                             field is output.
  * }
 }}}

 Or these array key descriptions could be moved into the main DocBlock
 description:

 {{{
  * When the label_for argument is supplied, the setting title will be
 wrapped...
  * The class argument is the CSS class to be added to the `<tr>`
 element...
  * ...
  * @param array{label_for: string, class: string} $args
 }}}

 That keeps all of the descriptions in one place, and avoids key and key-
 type duplications, and allows the actual param tag to follow exactly what
 tooling expects.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/57299#comment:5>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform