Yesterday Iâve pushed new sniffs to ZendCodingStandard library with sniffs to check params, return type and throws in function. Iâve started preparing PR, first for zend-expressive-hal to check how it works with these sniffs and I have found several issues:
-
mixed/mixed[] type is sometimes useful, especially in tests, when we have for example:
public function invalidAttributeNames()
{
return [
'null' => [null],
'false' => [false],
'true' => [true],
'zero' => [0],
'int' => [1],
'zero-float' => [0.0],
'float' => [1.1],
'empty-string' => [''],
'array' => [['attribute']],
'object' => [(object) ['name' => 'attribute']],
];
}
I think then we should allow using it.
- What type we should define for multidimensional arrays, like:
return [
'foo' => 'bar',
'id' => 12345678,
'_links' => [
'self' => [
'href' => '/api/foo',
],
'about' => [
['href' => '/doc/about'],
['href' => '/doc/resources/foo'],
],
],
'_embedded' => [
'bar' => [
'bar' => 'baz',
'_links' => [
'self' => ['href' => '/api/bar'],
],
],
'baz' => [
[
'baz' => 'bat',
'id' => 987654,
'_links' => [
'self' => ['href' => '/api/baz/987654'],
],
],
[
'baz' => 'bat',
'id' => 987653,
'_links' => [
'self' => ['href' => '/api/baz/987653'],
],
],
],
],
];
In that case mixed[] can be a bit confusing (as it is not one-level array). Any ideas? Maybe we should allow just array?
- It is not always possible to specify type for
array/iterable/\Traversable, for example:
https://github.com/zendframework/zend-hydrator/blob/master/src/ExtractionInterface.php#L18
Another example would be from zend-expressive-hal:
https://github.com/zendframework/zend-expressive-hal/blob/master/src/ResourceGenerator/ExtractCollection.php#L44
These methods are very generic and we canât provide better specifications.
I think we shouldnât force it. Of course it should be allowed to provide better specification, because in some cases it will be possible and useful.
-
Type Generator - functions with yield, for example:
https://github.com/zendframework/zend-expressive-hal/blob/master/test/Metadata/MetadataMapFactoryTest.php#L105-L117
Itâs kinda similar to Traversable, in perfect world we would like to have better specification but I think it is not always possible or pretty hard to do.
-
Tag @inheritDoc and {@inheritDoc}
https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#61-making-inheritance-explicit-using-the-inheritdoc-tag
The difference is:
-
@inheritDoc when we inherit everything from parent method and we are not providing anything extra,
-
{@inheritDoc} - when we inherit everything from parent and we extend description or specify type, more throws etc.
What do you think, should we allow using both of them? Currently I do not support any of them, and require define params/return type/throws always (only when needed as we agreed), but I can imagine in some cases with inheritance it will be duplicated many times.
-
Arrays with non-integer keys - let say array of strings with strings keys.
Here: http://www.icosaedro.it/phplint/phplint2/doc/reference.htm?p=docblocks#literalarrays
is suggested to use string[string] (old notation was array[string]string). If we go with string[string] PHPStorm doesnât support it at all - and thinks that type is string not even string[].
Of course if keys are integers we should omit int in square brackets (as it is default).
Another notation Iâve seen is: array(string => string) (also not supported by PHPStorm).
-
Arrays with mixed values: but only (let say) int and string:
https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#arrays
Itâs suggested there to use (int|string)[]. As I know, many people used int[]|string[] in that case, but I think (int|string)[] is more accurate - it means (for me) âarray which contains ints and strings (at the same time)â, when int[]|string[] means âarray of ints XOR array of stringsâ.
-
Generic types:
https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#collections
For example:
/**
* @param \ArrayObject<string>
*/
Should we allow that style of definition?
- Defining array values:
https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#examples-12
/**
* @param array $options {
* @var bool $required Whether this element is required
* @var string $label The display name for this element
* }
*/
We do something similar here:
It is not supported by PHPStorm as far as I know.
Should we implement it or not?
Thatâs it for now. Please let me know what do you think on each of above points.
Below I prepared short questionnaire for all above points, hope it will help 
1. Allow mixed / mixed[] types
- yes
- no
- another suggestion
2. Multidimensional arrays:
mixed[]- just
array
- another suggestion
3. Do not require better specification for following types:
arrayiterable\Travesable\Generator- always require better specification for above types
- another suggestion
4. Generators (included in point 4)
5. @inheritDoc and {@inheritDoc}
- disallow using both, always params/return type/throws need to be provided
- allow using both (CS checks cannot be done on method when one of these tags is provided)
- another suggestion
6. Array with non-integers keys (array of strings with string keys):
-
string[] is enough
- use
string[string]
- use
array[string]string
- use
array(string => string)
- another suggestion
7. Array with mixed values (int and string only):
- allow
(int|string)[]
-
int[]|string[] is clear enough and use it
- another suggestion
8. Generic types:
- allow
\ArrayObject<key-type, value-type>
- it is useless
- another suggestion
9. Defining array values:
- use PSR-5 proposed standard with
@var for each key
- keep old âstandardâ (as it is in zend-code) with
@configkey tag
- we donât need any standards
- another suggestion
