How to document PHP Array keys and INI files

Question

When using phpdoc doc blocks, is it possible to describe the keys for an array?

/**
 * @var array
 */
private $smtpSettings
    = array(
        'SMTPDebug' => (bool)true,
        'SMTPSecure' => (string) 'tls',
        'SMTPAuth' => (string)'',
        'Username' => (string)'',
        'Password' => (string)'',
        'Port' => (int)25,
        'Host' => (string)'',
    );

I want to show in the documentation that SMTPSecure can be tls/ssl/none along with details of what the other array keys are used for.

Also, what is best practice for documenting INI files and there default values? Can phpdoc generate any kind of docs for ini files? If not, is there a way to include an ini file in the generated phpdocs with links etc to it?

Thanks

Additional Info :

I had forgotten about the JB ArrayShape, but on testing this is great when your developing the software, but when running phpdoc, the output is not rendered very well :

array{ SMTPDebug: bool Enable debug, SMTPSecure: string Security type to use, SMTPAuth: string, Username: string SMTP Auth username, Password: string SMTP Auth password, Port: int, Host: string }

The info is just formatted into a single line of text that, although it has the details needed, is not very easy to read. Is this maybe more of a phpdoc template issue or is it just a restriction within phpdoc? Thanks

PHPStorm has JetBrains\PhpStorm\ArrayShape attribute that can be used for that. Look for similar alternative for your IDE — Justinas
– Justinas, Commented Sep 28, 2022 at 9:16

koloml · Accepted Answer · 2022-09-28 10:12:56Z

If you're using PhpStorm, you can use array shape syntax. It has some limitations, but works fine. Can be described like that:

/**
 * -- You can just describe all the keys in `{}` braces:
 *
 * @var array{key: string, key2: string} $variable Description of variable.
 *
 * -- Also, you can make it multiline:
 *
 * @var array{
 *     key: string,
 *     key2: string
 * } $variable Description of variable
 */
$variable = [
    'key'  => 'value',
    'key2' => 'value2'
];

/**
 * -- You can also describe deeper arrays:
 *
 * @var array{
 *     key: array{innerKey: string},
 *     key2: string
 * } $deepArray
 */
$deepArray = [
    'key' => [
        'innerKey' => 'value'
    ],
    'key2' => 'value2'
];

Example for the array provided in your question:

/**
 * @var array{
 *     SMTPDebug: bool,
 *     SMTPSecure: string,
 *     SMPTAuth: string,
 *     Username: string,
 *     Password: string,
 *     Port: int,
 *     Host: string
 * } $smtpSettings
 */
private $smtpSettings = array(
    'SMTPDebug'  => (bool)true,
    'SMTPSecure' => (string)'tls',
    'SMTPAuth'   => (string)'',
    'Username'   => (string)'',
    'Password'   => (string)'',
    'Port'       => (int)25,
    'Host'       => (string)'',
);

Collectives™ on Stack Overflow

How to document PHP Array keys and INI files

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related