Skip to content
Permalink
Browse files

Break out docblock_type_syntax.md into separate files

  • Loading branch information...
muglug committed Jun 27, 2019
1 parent af1decf commit 0d3f5af18c2013bc1c3999d276253a7f7e823516
@@ -65,13 +65,7 @@ There are two main inspirations for Psalm:
- [Docblock Type Syntax](annotating_code/docblock_type_syntax.md)
- [Supported Annotations](annotating_code/supported_annotations.md)
- [Template Annotations](annotating_code/templated_annotations.md)
- Type syntax:
- [Array types](annotating_code/type_syntax/array_types.md)
- [Callable types](annotating_code/type_syntax/callable_types.md)
- [Object types](annotating_code/type_syntax/object_types.md)
- [Scalar types](annotating_code/type_syntax/scalar_types.md)
- [Value types](annotating_code/type_syntax/value_types.md)
- Manipulating code:
- [Fixing code](manipulating_code/fixing.md)
- [Refactoring code](manipulating_code/refactoring.md)

@@ -1,91 +1,5 @@
# Docblock Type Syntax

## Atomic types

Atomic types are the basic building block of all type information used in Psalm. Multiple atomic types can be combined, either with [union types](#union-types) or [intersection types](#intersection_types). Psalm allows many different sorts of atomic types to be expressed in docblock syntax:

### [Scalar types](type_syntax/scalar_types.md)

- [`int`](type_syntax/scalar_types.md)
- [`float`](type_syntax/scalar_types.md)
- [`string`](type_syntax/scalar_types.md)
- [`class-string` and `class-string<Foo>`](type_syntax/scalar_types.md#class-string)
- [`trait-string`](type_syntax/scalar_types.md#trait-string)
- [`callable-string`](type_syntax/scalar_types.md#callable-string)
- [`numeric-string`](type_syntax/scalar_types.md#numeric-string)
- [`bool`](type_syntax/scalar_types.md)
- [`array-key`](type_syntax/scalar_types.md#array-key)
- [`numeric`](type_syntax/scalar_types.md#numeric)
- [`scalar`](type_syntax/scalar_types.md#scalar)

### [Object types](type_syntax/object_types.md)

- [`object`](type_syntax/object_types.md)
- [`Exception`, `Foo\MyClass` and `Foo\MyClass<Bar>`](type_syntax/object_types.md)

### [Array types](type_syntax/array_types.md)

- [`array` & `non-empty-array`](type_syntax/array_types.md)
- [`string[]`](type_syntax/array_types.md#phpdoc-syntax)
- [`array<int, string>`](type_syntax/array_types.md#generic-arrays)
- [`array{foo: int, bar: string}`](type_syntax/array_types.md#object-like-arrays)

### [Callable types](type_syntax/callable_types.md)

- [`callable`, `Closure` and `callable(Foo, Bar):Baz`](type_syntax/callable_types.md)

### [Value types](type_syntax/value_types.md)

- [`null`](type_syntax/value_types.md#null)
- [`true`, `false`](type_syntax/value_types.md#true-false)
- [`6`, `7.0`, `"fourty-two"` and `'fourty two'`](type_syntax/value_types.md#some_string-4-314)
- [`Foo\Bar::MY_SCALAR_CONST`](type_syntax/value_types.md#regular-class-constants)

### Magical types

- `key-of<Foo\Bar::ARRAY_CONST>`
- `value-of<Foo\Bar::ARRAY_CONST>`
- `T[K]`

### Other

- `iterable` - represents the [`iterable` pseudo-type](https://php.net/manual/en/language.types.iterable.php). Like arrays, iterables can have type parameters e.g. `iterable<string, Foo>`.
- `void` - can be used in a return type when a function does not return a value.
- `empty` - a type that represents a lack of type - not just a lack of type information (that's where [mixed](#mixed) is useful) but where there can be no type. A good example is the type of the empty array `[]`. Psalm types this as `array<empty, empty>`.
- `mixed` represents a lack of type information. Psalm warns about mixed when the `totallyTyped` flag is turned on.
- `resource` represents a [PHP resource](https://www.php.net/manual/en/language.types.resource.php).
- `no-return` is the 'return type' for a function that can never actually return, such as `die()`, `exit()`, or a function that
always throws an exception. It may also be written as `never-return` or `never-returns`, and is also known as the *bottom type*.

## Union Types

An annotation of the form `Type1|Type2|Type3` is a _Union Type_. `Type1`, `Type2` and `Type3` are all acceptable possible types of that union type.

`Type1`, `Type2` and `Type3` are each [atomic types](#atomic-types).

Union types can be generated in a number of different ways, for example in ternary expressions:

```php
$rabbit = rand(0, 10) === 4 ? 'rabbit' : ['rabbit'];
```

`$rabbit` will be either a `string` or an `array`. We can represent that idea with Union Types – so `$rabbit` is typed as `string|array`. Union types represent *all* the possible types a given variable can have.

PHP builtin functions also have union-type returns - `strpos` can return `false` in some situations, `int` in others. We represent that union type with `int|false`.

## Intersection types

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).

For example, after this statement in a PHPUnit test:
```php
$hare = $this->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. Only *object types* may be used within an intersection.

## Backwards compatibility
All docblock types are either [atomic types](atomic_types.md), [union types](union_types.md) or [intersection types](intersection_types.md).

Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/guides/types.html), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).
@@ -0,0 +1,56 @@
# Atomic types

Atomic types are the basic building block of all type information used in Psalm. Multiple atomic types can be combined, either with [union types](#union-types) or [intersection types](#intersection_types). Psalm allows many different sorts of atomic types to be expressed in docblock syntax:

## [Scalar types](scalar_types.md)

- [`int`](scalar_types.md)
- [`float`](scalar_types.md)
- [`string`](scalar_types.md)
- [`class-string` and `class-string<Foo>`](scalar_types.md#class-string)
- [`trait-string`](scalar_types.md#trait-string)
- [`callable-string`](scalar_types.md#callable-string)
- [`numeric-string`](scalar_types.md#numeric-string)
- [`bool`](scalar_types.md)
- [`array-key`](scalar_types.md#array-key)
- [`numeric`](scalar_types.md#numeric)
- [`scalar`](scalar_types.md#scalar)

## [Object types](object_types.md)

- [`object`](object_types.md)
- [`Exception`, `Foo\MyClass` and `Foo\MyClass<Bar>`](object_types.md)

## [Array types](array_types.md)

- [`array` & `non-empty-array`](array_types.md)
- [`string[]`](array_types.md#phpdoc-syntax)
- [`array<int, string>`](array_types.md#generic-arrays)
- [`array{foo: int, bar: string}`](array_types.md#object-like-arrays)

## [Callable types](callable_types.md)

- [`callable`, `Closure` and `callable(Foo, Bar):Baz`](callable_types.md)

## [Value types](value_types.md)

- [`null`](value_types.md#null)
- [`true`, `false`](value_types.md#true-false)
- [`6`, `7.0`, `"fourty-two"` and `'fourty two'`](value_types.md#some_string-4-314)
- [`Foo\Bar::MY_SCALAR_CONST`](value_types.md#regular-class-constants)

## Magical types

- `key-of<Foo\Bar::ARRAY_CONST>`
- `value-of<Foo\Bar::ARRAY_CONST>`
- `T[K]`

## Other

- `iterable` - represents the [`iterable` pseudo-type](https://php.net/manual/en/language.types.iterable.php). Like arrays, iterables can have type parameters e.g. `iterable<string, Foo>`.
- `void` - can be used in a return type when a function does not return a value.
- `empty` - a type that represents a lack of type - not just a lack of type information (that's where [mixed](#mixed) is useful) but where there can be no type. A good example is the type of the empty array `[]`. Psalm types this as `array<empty, empty>`.
- `mixed` represents a lack of type information. Psalm warns about mixed when the `totallyTyped` flag is turned on.
- `resource` represents a [PHP resource](https://www.php.net/manual/en/language.types.resource.php).
- `no-return` is the 'return type' for a function that can never actually return, such as `die()`, `exit()`, or a function that
always throws an exception. It may also be written as `never-return` or `never-returns`, and is also known as the *bottom type*.
@@ -0,0 +1,12 @@
# Intersection types

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
$hare = $this->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. Only *object types* may be used within an intersection.
@@ -0,0 +1,15 @@
# Union Types

An annotation of the form `Type1|Type2|Type3` is a _Union Type_. `Type1`, `Type2` and `Type3` are all acceptable possible types of that union type.

`Type1`, `Type2` and `Type3` are each [atomic types](atomic_types.md).

Union types can be generated in a number of different ways, for example in ternary expressions:

```php
$rabbit = rand(0, 10) === 4 ? 'rabbit' : ['rabbit'];
```

`$rabbit` will be either a `string` or an `array`. We can represent that idea with Union Types – so `$rabbit` is typed as `string|array`. Union types represent *all* the possible types a given variable can have.

PHP builtin functions also have union-type returns - `strpos` can return `false` in some situations, `int` in others. We represent that union type with `int|false`.

0 comments on commit 0d3f5af

Please sign in to comment.
You can’t perform that action at this time.