Skip to content
Permalink
Browse files

Add separate file for adding_assertions

  • Loading branch information...
muglug committed Jun 19, 2019
1 parent 95fc208 commit 51e31ba9c957142782ca8a59417532e3aa425fb0
Showing with 1 addition and 101 deletions.
  1. +1 −101 docs/annotating_code/supported_annotations.md
@@ -93,107 +93,7 @@ function addString(?string $s) {

### `@psalm-assert`, `@psalm-assert-if-true` and `@psalm-assert-if-false`

These annotations allow you to specify very basic facts about how a class of functions operate.

For example, if you have a class that verified its input is an array of strings, you can make that clear to Psalm:

```php
/** @psalm-assert string[] $arr */
function validateStringArray(array $arr) : void {
foreach ($arr as $s) {
if (!is_string($s)) {
throw new UnexpectedValueException('Invalid value ' . gettype($s));
}
}
}
```

This enables you to call the `validateStringArray` function on some data and have Psalm understand that the given data *must* be an array of strings:

```php
function takesString(string $s) : void {}
function takesInt(int $s) : void {}
function takesArray(array $arr) : void {
takesInt($arr[0]); // this is fine
validateStringArray($arr);
takesInt($arr[0]); // this is an error
foreach ($arr as $a) {
takesString($a); // this is fine
}
}
```

Similarly, `@psalm-assert-if-true` and `@psalm-assert-if-false` will filter input if the function/method returns `true` and `false` respectively:

```php
class A {
public function isValid() : bool {
return (bool) rand(0, 1);
}
}
class B extends A {
public function bar() : void {}
}
/**
* @psalm-assert-if-true B $a
*/
function isValidB(A $a) : bool {
return $a instanceof B && $a->isValid();
}
/**
* @psalm-assert-if-false B $a
*/
function isInvalidB(A $a) : bool {
return $a instanceof B || !$a->isValid();
}
function takesA(A $a) : void {
if (isValidB($a)) {
$a->bar();
}
if (isInvalidB($a)) {
// do something
} else {
$a->bar();
}
$a->bar(); //error
}
```

As well as getting Psalm to understand that the given data must be a certain type, you can also show that a variable must be not null:

```php
/**
* @psalm-assert !null $value
*/
function assertNotNull($value): void {
// Some check that will mean the method will only complete if $value is not null.
}
```

And you can check on null values:

```php
/**
* @psalm-assert-if-true null $value
*/
function isNull($value): bool {
return ($value === null);
}
```

A list of acceptable assertions [can be found here](assertion_syntax.md).
See [Adding assertions](adding_assertions.md).

### `@psalm-ignore-nullable-return`

0 comments on commit 51e31ba

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