diff --git a/docs/annotating_code/type_syntax/array_types.md b/docs/annotating_code/type_syntax/array_types.md index 36173b41d64..9a6ff692e75 100644 --- a/docs/annotating_code/type_syntax/array_types.md +++ b/docs/annotating_code/type_syntax/array_types.md @@ -3,12 +3,14 @@ In PHP, the `array` type is commonly used to represent three different data structures: [List](https://en.wikipedia.org/wiki/List_(abstract_data_type)): + ```php 'hello', 5 => 'goodbye']; @@ -16,6 +18,7 @@ $b = ['a' => 'AA', 'b' => 'BB', 'c' => 'CC'] ``` Makeshift [Structs](https://en.wikipedia.org/wiki/Struct_(C_programming_language)): + ```php 'Psalm', 'type' => 'tool']; @@ -28,6 +31,7 @@ Psalm has a few different ways to represent arrays in its type system: ## Generic arrays Psalm uses a syntax [borrowed from Java](https://en.wikipedia.org/wiki/Generics_in_Java) that allows you to denote the types of both keys *and* values: + ```php /** @return array */ ``` @@ -37,6 +41,7 @@ You can also specify that an array is non-empty with the special type `non-empty ### PHPDoc syntax PHPDoc [allows you to specify](https://docs.phpdoc.org/latest/guide/references/phpdoc/types.html#arrays) the type of values a generic array holds with the annotation: + ```php /** @return ValueType[] */ ``` @@ -179,14 +184,12 @@ Optional keys can be denoted by a specifying keys for all elements and specifyin List shapes are essentially n-tuples [from a type theory perspective](https://en.wikipedia.org/wiki/Tuple#Type_theory). - ## Unsealed array and list shapes Starting from Psalm v5, array shapes and list shapes can be marked as open by adding `...` as their last element. Here we have a function `handleOptions` that takes an array of options. The type tells us it has a single known key with type `string`, and potentially many other keys of unknown types. - ```php /** @param array{verbose: string, ...} $options */ function handleOptions(array $options): float { diff --git a/docs/annotating_code/type_syntax/intersection_types.md b/docs/annotating_code/type_syntax/intersection_types.md index e7a94dc2311..a1449678ba8 100644 --- a/docs/annotating_code/type_syntax/intersection_types.md +++ b/docs/annotating_code/type_syntax/intersection_types.md @@ -3,16 +3,19 @@ An annotation of the form `Type1&Type2&Type3` is an _Intersection Type_. Any value must satisfy `Type1`, `Type2` and `Type3` simultaneously. `Type1`, `Type2` and `Type3` are all [atomic types](atomic_types.md). For example, after this statement in a PHPUnit test: + ```php createMock(Hare::class); ``` + `$hare` will be an instance of a class that extends `Hare`, and implements `\PHPUnit\Framework\MockObject\MockObject`. So `$hare` is typed as `Hare&\PHPUnit\Framework\MockObject\MockObject`. You can use this syntax whenever a value is required to implement multiple interfaces. Another use case is being able to merge object-like arrays: + ```php /** * @psalm-type A=array{a: int} @@ -27,6 +30,7 @@ function foo($a, $b) { return $a + $b; } ``` + The returned type will contain the properties of both `A` and `B`. In other words, it will be `{a: int, b: int}`. Intersections are only valid for lists of only *object types* and lists of only *object-like arrays*. diff --git a/docs/annotating_code/type_syntax/scalar_types.md b/docs/annotating_code/type_syntax/scalar_types.md index cc2f6a2afc1..df8fb182395 100644 --- a/docs/annotating_code/type_syntax/scalar_types.md +++ b/docs/annotating_code/type_syntax/scalar_types.md @@ -21,12 +21,12 @@ Examples: * `int` (equivalent to `non-positive-int`) * `int` (equivalent to `int`) -## `int-mask<1, 2, 4>` +## int-mask<1, 2, 4> Represents the type that is the result of a bitmask combination of its parameters. `int-mask<1, 2, 4>` corresponds to `0|1|2|3|4|5|6|7`. -## `int-mask-of` +## int-mask-of<MyClass::CLASS_CONSTANT_*> Represents the type that is the result of a bitmask combination of its parameters. This is the same concept as [`int-mask`](#int-mask1-2-4) but this type is used with a reference to constants in code: `int-mask-of` will correspond to `0|1|2|3|4|5|6|7` if there are three constants called `CLASS_CONSTANT_{A,B,C}` with values 1, 2 and 4. diff --git a/docs/annotating_code/type_syntax/top_bottom_types.md b/docs/annotating_code/type_syntax/top_bottom_types.md index 3500cfbc97c..ead9ffcfd4e 100644 --- a/docs/annotating_code/type_syntax/top_bottom_types.md +++ b/docs/annotating_code/type_syntax/top_bottom_types.md @@ -10,6 +10,7 @@ This is the _top type_ in PHP's type system, and represents a lack of type infor It can be aliased to `no-return` or `never-return` in docblocks. Note: it replaced the old `empty` type that used to exist in Psalm This is the _bottom type_ in PHP's type system. It's used to describe a type that has no possible value. It can happen in multiple cases: + - the actual `never` type from PHP 8.1 (can be used in docblocks for older versions). This type can be used as a return type for functions that will never return, either because they always throw exceptions or always exit() - an union type that have been stripped for all its possible types. (For example, if a variable is `string|int` and we perform a is_bool() check in a condition, the type of the variable in the condition will be `never` as the condition will never be entered) - it can represent a placeholder for types yet to come — a good example is the type of the empty array `[]`, which Psalm types as `array`, the content of the array is void so it can accept any content diff --git a/docs/annotating_code/type_syntax/utility_types.md b/docs/annotating_code/type_syntax/utility_types.md index c62a8dd36e7..32b10cadd63 100644 --- a/docs/annotating_code/type_syntax/utility_types.md +++ b/docs/annotating_code/type_syntax/utility_types.md @@ -2,7 +2,7 @@ Psalm supports some _magical_ utility types that brings superpower to the PHP type system. -## `key-of` +## key-of<T> (Psalm 5.0+)