Skip to content

Commit 6e3e39d

Browse files
carlos-granadoscarlos-granados
committed
Add Assert, AssertIfTrue and AssertIfFalse attributes
1 parent c6784b3 commit 6e3e39d

9 files changed

+703
-0
lines changed

‎doc/Assert.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# `Assert` Attribute
2+
3+
This attribute is the equivalent of the `@assert` annotation. It can be used on class methods or on regular functions.
4+
5+
## Arguments
6+
7+
The attribute accepts one or more strings which describes the assertion that is performed on the parameter. The attribute itself does not have a knowledge of which assertions are valid and which are not and this will depend on the implementation for each particular tool.
8+
9+
We expect that the attribute will be able to accept all the types accepted by static analysis tools for the `@assert` annotation.
10+
11+
The arguments can be named arguments and the assertion is applied to the parameter with the same name in the function or the class.
12+
13+
You can also pass an unnamed argument with a string that contains both the assertion and the name of the parameter, but we recommend using named arguments.
14+
15+
If the function or method has more than one parameter, the assertions for the different parameters can either be declared as a list of strings for a single `Assert` attribute or as a list of `Assert` attributes (or even a combination of both, though we don't expect this to be actually used).
16+
17+
You can also directly apply the attribute to any of the method/function parameters. In that case, the name of the argument is optional and, if added, should match the name of the parameter to which it is applied.
18+
19+
## Example usage
20+
21+
```php
22+
<?php
23+
24+
use PhpStaticAnalysis\Attributes\Assert;
25+
26+
class AssertExample
27+
{
28+
// Single parameter
29+
#[Assert(param: 'string')]
30+
public function methodThatAssertsParamIsString($param)
31+
{
32+
}
33+
34+
// Single parameter with unnamed argument
35+
#[Assert('string $param')]
36+
public function methodThatAssertsParamIsString($param)
37+
{
38+
}
39+
40+
// Multiple params listed in a single attribute
41+
#[Assert(
42+
param1: 'string',
43+
param2: 'Foo',
44+
)]
45+
public function methodThatAssertsBothParameters($param1, $param2)
46+
{
47+
}
48+
49+
// Multiple params listed in multiple attributes
50+
#[Assert(param1: 'string')]
51+
#[Assert(param2: 'Foo')]
52+
public function methodThatAssertsBothParameters($param1, $param2)
53+
{
54+
}
55+
56+
// Attribute applied at parameter level
57+
public function assertOnParam(
58+
#[Assert('string')]
59+
array $param
60+
) {
61+
}
62+
}
63+
```

‎doc/AssertIfFalse.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# `AssertIfFalse` Attribute
2+
3+
This attribute is the equivalent of the `@assert-if-false` annotation. It can be used on class methods or on regular functions.
4+
5+
## Arguments
6+
7+
The attribute accepts one or more strings which describes the assertion that is performed on the parameter and that will the function return false. The attribute itself does not have a knowledge of which assertions are valid and which are not and this will depend on the implementation for each particular tool.
8+
9+
We expect that the attribute will be able to accept all the types accepted by static analysis tools for the `@assert-if-false` annotation.
10+
11+
The arguments can be named arguments and the assertion is applied to the parameter with the same name in the function or the class.
12+
13+
You can also pass an unnamed argument with a string that contains both the assertion and the name of the parameter, but we recommend using named arguments. This later form can also be used to pass more complex assertions on members of the class, for example.
14+
15+
If the function or method has more than one parameter, the assertions for the different parameters can either be declared as a list of strings for a single `AssertIfFalse` attribute or as a list of `AssertIfFalse` attributes (or even a combination of both, though we don't expect this to be actually used).
16+
17+
You can also directly apply the attribute to any of the method/function parameters. In that case, the name of the argument is optional and, if added, should match the name of the parameter to which it is applied.
18+
19+
## Example usage
20+
21+
```php
22+
<?php
23+
24+
use PhpStaticAnalysis\Attributes\AssertIfFalse;
25+
26+
class AssertIfFalseExample
27+
{
28+
// Single parameter
29+
#[AssertIfFalse(param: 'string')]
30+
public function methodThatAssertsParamIsNotString($param): bool
31+
{
32+
}
33+
34+
// Single parameter with unnamed argument
35+
#[AssertIfFalse('string $param')]
36+
public function methodThatAssertsParamIsNotString($param): bool
37+
{
38+
}
39+
40+
// Assert performed on something which is not a param
41+
#[AssertIfFalse('null $this->getName()')]
42+
public function methodThatAssertsThatNameIsNotNull($param): bool
43+
{
44+
}
45+
46+
// Multiple params listed in a single attribute
47+
#[AssertIfFalse(
48+
param1: 'string',
49+
param2: 'Foo',
50+
)]
51+
public function methodThatAssertsBothParameters($param1, $param2): bool
52+
{
53+
}
54+
55+
// Multiple params listed in multiple attributes
56+
#[AssertIfFalse(param1: 'string')]
57+
#[AssertIfFalse(param2: 'Foo')]
58+
public function methodThatAssertsBothParameters($param1, $param2): bool
59+
{
60+
}
61+
62+
// Attribute applied at parameter level
63+
public function assertOnParam(
64+
#[AssertIfFalse('string')]
65+
array $param
66+
): bool {
67+
}
68+
}
69+
```

‎doc/AssertIfTrue.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# `AssertIfTrue` Attribute
2+
3+
This attribute is the equivalent of the `@assert-if-true` annotation. It can be used on class methods or on regular functions.
4+
5+
## Arguments
6+
7+
The attribute accepts one or more strings which describes the assertion that is performed on the parameter and that will the function return true. The attribute itself does not have a knowledge of which assertions are valid and which are not and this will depend on the implementation for each particular tool.
8+
9+
We expect that the attribute will be able to accept all the types accepted by static analysis tools for the `@assert-if-true` annotation.
10+
11+
The arguments can be named arguments and the assertion is applied to the parameter with the same name in the function or the class.
12+
13+
You can also pass an unnamed argument with a string that contains both the assertion and the name of the parameter, but we recommend using named arguments. This later form can also be used to pass more complex assertions on members of the class, for example.
14+
15+
If the function or method has more than one parameter, the assertions for the different parameters can either be declared as a list of strings for a single `AssertIfTrue` attribute or as a list of `AssertIfTrue` attributes (or even a combination of both, though we don't expect this to be actually used).
16+
17+
You can also directly apply the attribute to any of the method/function parameters. In that case, the name of the argument is optional and, if added, should match the name of the parameter to which it is applied.
18+
19+
## Example usage
20+
21+
```php
22+
<?php
23+
24+
use PhpStaticAnalysis\Attributes\AssertIfTrue;
25+
26+
class AssertIfTrueExample
27+
{
28+
// Single parameter
29+
#[AssertIfTrue(param: 'string')]
30+
public function methodThatAssertsParamIsString($param): bool
31+
{
32+
}
33+
34+
// Single parameter with unnamed argument
35+
#[AssertIfTrue('string $param')]
36+
public function methodThatAssertsParamIsString($param): bool
37+
{
38+
}
39+
40+
// Assert performed on something which is not a param
41+
#[AssertIfTrue('!null $this->getName()')]
42+
public function methodThatAssertsThatNameIsNotNull($param): bool
43+
{
44+
}
45+
46+
// Multiple params listed in a single attribute
47+
#[AssertIfTrue(
48+
param1: 'string',
49+
param2: 'Foo',
50+
)]
51+
public function methodThatAssertsBothParameters($param1, $param2): bool
52+
{
53+
}
54+
55+
// Multiple params listed in multiple attributes
56+
#[AssertIfTrue(param1: 'string')]
57+
#[AssertIfTrue(param2: 'Foo')]
58+
public function methodThatAssertsBothParameters($param1, $param2): bool
59+
{
60+
}
61+
62+
// Attribute applied at parameter level
63+
public function assertOnParam(
64+
#[AssertIfTrue('string')]
65+
array $param
66+
): bool {
67+
}
68+
}
69+
```

‎src/Assert.php

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace PhpStaticAnalysis\Attributes;
6+
7+
use Attribute;
8+
9+
#[Attribute(
10+
Attribute::TARGET_METHOD |
11+
Attribute::TARGET_FUNCTION |
12+
Attribute::TARGET_PARAMETER |
13+
Attribute::IS_REPEATABLE
14+
)]
15+
final class Assert
16+
{
17+
public function __construct(
18+
string ...$params
19+
) {
20+
}
21+
}

‎src/AssertIfFalse.php

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace PhpStaticAnalysis\Attributes;
6+
7+
use Attribute;
8+
9+
#[Attribute(
10+
Attribute::TARGET_METHOD |
11+
Attribute::TARGET_FUNCTION |
12+
Attribute::TARGET_PARAMETER |
13+
Attribute::IS_REPEATABLE
14+
)]
15+
final class AssertIfFalse
16+
{
17+
public function __construct(
18+
string ...$params
19+
) {
20+
}
21+
}

‎src/AssertIfTrue.php

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace PhpStaticAnalysis\Attributes;
6+
7+
use Attribute;
8+
9+
#[Attribute(
10+
Attribute::TARGET_METHOD |
11+
Attribute::TARGET_FUNCTION |
12+
Attribute::TARGET_PARAMETER |
13+
Attribute::IS_REPEATABLE
14+
)]
15+
final class AssertIfTrue
16+
{
17+
public function __construct(
18+
string ...$params
19+
) {
20+
}
21+
}

0 commit comments

Comments
 (0)