Document array shapes for parameters and complex `array` structures?

[Ocramius]

Problem Statement

Hey there! I was working on a codebase this morning, and noticed that Sentry does not really document the various keys that could be passed to functions like Sentry\init().

For example:

    \Sentry\init([
        'dsn' => '<SNIP>',
        'environment' => some_env(),
        'send_default_pii' => true,
        'prefixes' => [
            realpath(__DIR__),
        ],
        'before_send' => new RemoveApiKeyBeforeSending(),
        'traces_sample_rate' => 0.001,
        'profiles_sample_rate' => 1.0,
    ]);

There are tons of configuration options, and tools like PHPStan and Psalm can pick these up.

Solution Brainstorm

It would be nice to declare the the types in the Sentry SDK directly, both for documentation and for type-checking purposes:

/**
 * Creates a new Client and Hub which will be set as current.
 *
- * @param array<string, mixed> $options The client options
+ * @param array{
+ *   dsn?: non-empty-string,
+ *   environment?: non-empty-string,
+ *   send_default_pii?: bool,
+ *   prefixes?: non-empty-list<non-empty-string>,
+ * ...
+ * } $options The client options
 */
function init(array $options = []): void
{
    $client = ClientBuilder::create($options)->getClient();

    SentrySdk::init()->bindClient($client);
}

Note: the 3 ... at the end are part of the type signature (more keys allowed), but obviously, my example is far from exhaustive :D

This can generally be done with functions and methods in the SDK, over time :-)