Skip to content

Commit b66b1f3

Browse files
paulbalandanpaulbalandan
committed
Extract type inference to separate doc
1 parent 89fe461 commit b66b1f3

File tree

2 files changed

+116
-46
lines changed

2 files changed

+116
-46
lines changed

‎README.md‎

Lines changed: 1 addition & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,7 @@
99

1010
This extension provides the following features:
1111

12-
### Type Inference
13-
14-
* Provides precise return types for `config()` and `model()` functions.
15-
* Provides precise return types for `service()` and `single_service()` functions.
16-
* Provides precise return types for `fake()` helper function.
17-
* Provides precise return types for `CodeIgniter\Model`'s `find()`, `findAll()`, and `first()` methods.
18-
* Allows dynamic return type transformation of `CodeIgniter\Model` when `asArray()` or `asObject()` is called.
12+
* [Type inference](docs/type-inference.md)
1913

2014
### Rules
2115

@@ -58,45 +52,6 @@ Development in this repository uses **PHP 8.1+**.
5852
Starting [v1.1.0](https://github.com/CodeIgniter/phpstan-codeigniter/releases/tag/v1.1.0), releases come with a downgraded
5953
version to suit lower PHP versions. Currently, lowest supported downgraded PHP version is **PHP 7.4**.
6054
61-
## Configuration
62-
63-
This extension adds the default namespace for `config()` and `model()` functions as `Config\` and `App\Models\`, respectively,
64-
when searching for possible classes. If your application uses other namespaces, you can configure this extension
65-
in your `phpstan.neon` to recognize those namespaces:
66-
67-
```yml
68-
parameters:
69-
codeigniter:
70-
additionalConfigNamespaces:
71-
- Acme\Blog\Config\
72-
- Foo\Bar\Config\
73-
additionalModelNamespaces:
74-
- Acme\Blog\Models\
75-
76-
```
77-
78-
For the `service()` and `single_service()` functions, you can instruct PHPStan to consider your own
79-
services factory classes. **Please note that it should be a valid class extending `CodeIgniter\Config\BaseService`!**
80-
81-
```yml
82-
parameters:
83-
codeigniter:
84-
additionalServices:
85-
- Acme\Blog\Config\ServiceFactory
86-
```
87-
88-
When the model passed to `fake()` has the property `$returnType` set to `array`, this extension will give a precise
89-
array shape based on the allowed fields of the model. Most of the time, the formatted fields are strings. If not a string,
90-
you can indicate the format return type for the particular field.
91-
92-
```yml
93-
parameters:
94-
codeigniter:
95-
notStringFormattedFields: # key-value pair of field => format
96-
success: bool
97-
user_id: int
98-
```
99-
10055
## Caveats
10156
10257
1. The behavior of factories functions relative to how they load classes is based on codeigniter4/framework v4.4. If you are

‎docs/type-inference.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,87 @@ All type inference capabilities of this extension are summarised below:
44

55
## Dynamic Function Return Type Extensions
66

7+
### FactoriesFunctionReturnTypeExtension
8+
9+
This extension provides precise return types for the `config()` and `model()` functions.
10+
11+
**Before:**
12+
```php
13+
\PHPStan\dumpType(config('bar')); // BaseConfig|null
14+
\PHPStan\dumpType(config('App')); // BaseConfig|null
15+
\PHPStan\dumpType(model(BarModel::class)); // Model|null
16+
17+
```
18+
19+
**After:**
20+
```php
21+
\PHPStan\dumpType(config('bar')); // null
22+
\PHPStan\dumpType(config('App')); // Config\App
23+
\PHPStan\dumpType(model(BarModel::class)); // CodeIgniter\PHPStan\Tests\Fixtures\Type\BarModel
24+
25+
```
26+
27+
> [!NOTE]
28+
> **Configuration:**
29+
>
30+
> This extension adds the default namespace for `config()` and `model()` functions as `Config\`
31+
> and `App\Models\`, respectively, when searching for possible classes. If your application uses
32+
> other namespaces, you can configure this extension in your `phpstan.neon` to recognize those namespaces:
33+
>
34+
> ```yml
35+
> parameters:
36+
> codeigniter:
37+
> additionalConfigNamespaces:
38+
> - Acme\Blog\Config\
39+
> - Foo\Bar\Config\
40+
> additionalModelNamespaces:
41+
> - Acme\Blog\Models\
42+
>
43+
> ```
44+
45+
### FakeFunctionReturnTypeExtension
46+
47+
This extension provides precise return type for the `fake()` function.
48+
49+
**Before:**
50+
```php
51+
\PHPStan\dumpType(fake('baz')); // array|object
52+
\PHPStan\dumpType(fake(BarModel::class)); // array|object
53+
\PHPStan\dumpType(fake(UserModel::class)); // array|object
54+
\PHPStan\dumpType(fake(UserIdentityModel::class)); // array|object
55+
\PHPStan\dumpType(fake(LoginModel::class)); // array|object
56+
\PHPStan\dumpType(fake(TokenLoginModel::class)); // array|object
57+
\PHPStan\dumpType(fake(GroupModel::class)); // array|object
58+
59+
```
60+
61+
**After:**
62+
```php
63+
\PHPStan\dumpType(fake('baz')); // never
64+
\PHPStan\dumpType(fake(BarModel::class)); // stdClass
65+
\PHPStan\dumpType(fake(UserModel::class)); // CodeIgniter\Shield\Entities\User
66+
\PHPStan\dumpType(fake(UserIdentityModel::class)); // CodeIgniter\Shield\Entities\UserIdentity
67+
\PHPStan\dumpType(fake(LoginModel::class)); // CodeIgniter\Shield\Entities\Login
68+
\PHPStan\dumpType(fake(TokenLoginModel::class)); // CodeIgniter\Shield\Entities\Login
69+
\PHPStan\dumpType(fake(GroupModel::class)); // array{user_id: int, group: string, created_at: string}
70+
71+
```
72+
73+
> [!NOTE]
74+
> **Configuration:**
75+
>
76+
> When the model passed to `fake()` has the property `$returnType` set to `array`, this extension will give
77+
> a precise array shape based on the allowed fields of the model. Most of the time, the formatted fields are
78+
> strings. If not a string, you can indicate the format return type for the particular field.
79+
>
80+
> ```yml
81+
> parameters:
82+
> codeigniter:
83+
> notStringFormattedFields: # key-value pair of field => format
84+
> success: bool
85+
> user_id: int
86+
> ```
87+
788
### ServicesFunctionReturnTypeExtension
889
990
This extension provides precise return types for the `service()` and `single_service()` functions.
@@ -19,6 +100,26 @@ This extension provides precise return types for the `service()` and `single_ser
19100
\PHPStan\dumpType(service('cache')); // CodeIgniter\Cache\CacheInterface
20101
```
21102
103+
> [!NOTE]
104+
> **Configuration:**
105+
>
106+
> You can instruct PHPStan to consider your own services factory classes.
107+
> **Please note that it should be a valid class extending `CodeIgniter\Config\BaseService`!**
108+
>
109+
> ```yml
110+
> parameters:
111+
> codeigniter:
112+
> additionalServices:
113+
> - Acme\Blog\Config\ServiceFactory
114+
> ```
115+
116+
## Dynamic Method Return Type Extension
117+
118+
### ModelFindReturnTypeExtension
119+
120+
This extension provides precise return types for `CodeIgniter\Model`'s `find()`, `findAll()`, and `first()` methods.
121+
This also allows dynamic return type transformation of `CodeIgniter\Model` when `asArray()` or `asObject()` is called.
122+
22123
## Dynamic Static Method Return Type Extensions
23124
24125
### ReflectionHelperGetPrivateMethodInvokerReturnTypeExtension
@@ -61,6 +162,7 @@ public function testSomePrivateMethod(): void
61162
```
62163
63164
> [!NOTE]
165+
> **Configuration:**
64166
>
65167
> If you are using `ReflectionHelper` outside of testing, you can still enjoy the precise return types by adding a
66168
> service for the class using this trait. In your `phpstan.neon` (or `phpstan.neon.dist`), add the following to
@@ -115,3 +217,16 @@ class MyService extends \Config\Services
115217
}
116218
117219
```
220+
221+
> [!NOTE]
222+
> **Configuration:**
223+
>
224+
> You can instruct PHPStan to consider your own services factory classes.
225+
> **Please note that it should be a valid class extending `CodeIgniter\Config\BaseService`!**
226+
>
227+
> ```yml
228+
> parameters:
229+
> codeigniter:
230+
> additionalServices:
231+
> - Acme\Blog\Config\ServiceFactory
232+
> ```

0 commit comments

Comments
 (0)