Improve helper option/HTML attribute discoverability #19508

Problem

Some helper APIs use a single $options array for both helper-specific configuration and raw HTML attributes. This works, but it is less discoverable than APIs such as FormHelper::select(), radio(), and multiCheckbox(), where choices/options and element attributes are separate parameters.

public function select(string $fieldName, iterable $options = [], array $attributes = []): string

A recent example is FormHelper::button(): adding a CSS class is supported via ['class' => '...'], but this is not obvious from the method shape because $options also contains semantic helper options such as type, escape, templateVars, etc.

Proposed direction for 5.next

Improve consistency and discoverability without breaking existing code:

• Audit helper methods where $options mixes helper config and HTML attributes.
• Document the target element for passthrough attributes consistently in API docs and cookbook examples.
• Where feasible in 5.x, add clearer aliases/wording such as “HTML attributes may be included in $options and are applied to <button>/<input>/<a>.”
• For a future major, consider whether selected APIs should grow a separate $attributes parameter, similar to select(), radio(), and multiCheckbox().

Candidate methods

FormHelper methods with overloaded $options:

• button()
• submit()
• postButton()
• postLink()
• create()
• control()
• checkbox()
• file()
• hidden()
• textarea()
• magic/simple inputs such as text(), email(), password(), number(), search()
• date/time methods such as dateTime(), month(), time(), year()

Other helper APIs with similar discoverability concerns:

• HtmlHelper::link()
• HtmlHelper::image()
• HtmlHelper::tag()
• HtmlHelper::script(), css(), meta(), scriptBlock()
• HtmlHelper::tableCell(), tableRow(), tableCells()
• PaginatorHelper::sort(), prev(), next(), first(), last(), numbers()

Notes

This does not require changing behavior. The immediate 5.next improvement could be documentation/API doc clarity and examples. Any signature changes should be considered separately for a future major because they could affect custom helpers and userland calls.