Skip to content

Commit 72bc134

Browse files
shochdoerfershochdoerfer
authored
Merge pull request #172 from shochdoerfer/feature/docs_improve
Improve docs
2 parents 4cd232f + 1c50654 commit 72bc134

File tree

2 files changed

+101
-61
lines changed

2 files changed

+101
-61
lines changed

‎README.md‎

Lines changed: 40 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# bitexpert/phpstan-magento
22

3-
This package provides some additional features for PHPStan to make it
4-
work for Magento 2 projects.
3+
This package provides some additional features for PHPStan to make it work for Magento 2 projects.
4+
You can use this PHPStan extension for both Magento module projects and Magento application projects.
55

66
[![Build Status](https://github.com/bitExpert/phpstan-magento/workflows/ci/badge.svg?branch=master)](https://github.com/bitExpert/phpstan-magento/actions)
77
[![Coverage Status](https://coveralls.io/repos/github/bitExpert/phpstan-magento/badge.svg?branch=master)](https://coveralls.io/github/bitExpert/phpstan-magento?branch=master)
@@ -10,12 +10,12 @@ work for Magento 2 projects.
1010

1111
PHP: PHP 7.2 or higher
1212

13-
Magento: Magento 2.3 or higher
13+
Magento: Magento 2.3.0 or higher
1414

1515
PHPStan: PHPStan 1.1
1616

17-
If you are using a Magento version that requires an older version of PHPStan, you need to manually upgrade it before
18-
installing this extension. Change the PHPStan version to 1.1 in your composer.json and run:
17+
If you are using a Magento version that requires an older version of PHPStan (e.g. 0.12.77), you need to manually upgrade it before
18+
installing this extension. in your composer.json Change the PHPStan version to `~1.1` and run:
1919

2020
```
2121
composer update phpstan/phpstan --with-all-dependencies
@@ -30,72 +30,51 @@ You can add `bitexpert/phpstan-magento` as a dev dependency, as follows:
3030
composer.phar require --dev bitexpert/phpstan-magento
3131
```
3232

33-
Include extension.neon and the autoloader.php file in your project's PHPStan config:
33+
### PHPStan configuration
34+
35+
If you have not already a PHPStan configuration file `phpstan.neon` in your project, create a new empty file next to your `composer.json` file.
36+
37+
This PHPStan extension needs to be registered with PHPStan so that PHPStan can load it properly.
38+
The easiest way to do this is to install the `phpstan/extension-installer` package as follows:
39+
40+
```
41+
composer.phar require --dev phpstan/extension-installer
42+
```
43+
44+
As an alternative, you can manually include the extension configuration `vendor/bitexpert/phpstan-magento/extension.neon` in
45+
your `phpstan.neon` file:
3446

3547
```neon
36-
parameters:
37-
bootstrapFiles:
38-
- vendor/bitexpert/phpstan-magento/autoload.php
3948
includes:
4049
- vendor/bitexpert/phpstan-magento/extension.neon
4150
```
4251

43-
## Features
44-
45-
### Class generator for factory & proxy classes
46-
The extension adds a class generator for factory & proxy classes similar as Magento does it. When running PHPStan in
47-
context of a Magento application this is not needed if you point PHPStan also to the generated files folder. When running
48-
Magento in the context of a module, this is required so that PHPStan gets the full picture of all classes needed.
49-
50-
### Mocked classes autoloader
51-
The extension adds an autoloader for "mocked" classes. These are classes that replace the Magento specific implementations
52-
to fix problems with type hints or missing methods in interfaces and such. The autoloader will check if a class, interface,
53-
or trait exists locally in the extension's folder of mocks. If so, it will load the local version instead of the one being
54-
shipped by Magento. Once those problems are fixed in Magento, those mocks can be removed again.
55-
56-
### TestFramework autoloader
57-
The extension provides an autoloader for `Magento\TestFramework` classes to let you run PHPStan also against your test classes.
58-
59-
#### TestFramework ObjectManager type hints
60-
A type extension was added so that `Magento\Framework\TestFramework\Unit\Helper\ObjectManager` calls return the correct return type.
61-
Additionally, a PHPStan rule was added to check that only `Magento\Framework\Data\Collection` sub classes can be passed to
62-
`Magento\Framework\TestFramework\Unit\Helper\ObjectManager::getCollectionMock()`.
63-
64-
### ObjectManager type hints
65-
A type extension was added so that `Magento\Framework\App\ObjectManager` calls return the correct return type.
66-
67-
### Support for magic method calls
68-
For some classes like the `Magento\Framework\DataObject` or `Magento\Framework\Session\SessionManager` logic was added
69-
to be able to support magic method calls.
52+
For the final step, you need to register the custom autoloader that comes with this extension by adding `vendor/bitexpert/phpstan-magento/autoload.php`
53+
as a bootstrap file:
7054

71-
### PHPStan rules
72-
73-
The following rules are available to run checks against your codebase, e.g. if your implementation adheres to the
74-
service contracts specification. Each of the rules can be disabled if needed.
75-
76-
#### Service contracts
77-
78-
Since Magento framework version 100.1.0 entities must not be responsible for their own loading, service contracts should
79-
be used to persist entities.
80-
81-
To disable this rule add the following code to your `phpstan.neon` configuration file:
82-
```
55+
```neon
8356
parameters:
84-
magento:
85-
checkServiceContracts: false
57+
bootstrapFiles:
58+
- vendor/bitexpert/phpstan-magento/autoload.php
8659
```
8760

88-
#### Collections should be used directly via factory
89-
90-
Since Magento framework version 101.0.0 Collections should be used directly via factory instead of calling
91-
`\Magento\Framework\Model\AbstractModel::getCollection()` directly.
92-
93-
To disable this rule add the following code to your `phpstan.neon` configuration file:
94-
```
95-
parameters:
96-
magento:
97-
checkCollectionViaFactory: false
98-
```
61+
## Feature overview
62+
63+
This PHPStan extension works for both Magento module projects and Magento application projects.
64+
65+
- Class generator for factory & proxy classes
66+
- Mocked classes autoloader
67+
- TestFramework autoloader
68+
- Type hints
69+
- TestFramework ObjectManager type hints
70+
- ObjectManager type hints
71+
- Magic method calls
72+
- Extension attributes
73+
- PHPStan rules
74+
- Service contracts
75+
- Collections should be used directly via factory
76+
77+
For a detailed overview, check the feature documentation [here](docs/features.md).
9978

10079
## Contribute
10180

‎docs/features.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Features
2+
3+
## Class generator for factory & proxy classes
4+
This PHPStan extension includes a class generator and autoloader for factory & proxy classes similar to what Magento does. When running PHPStan in
5+
the context of a Magento application this is not needed if you point PHPStan also to the generated files folder. When running
6+
Magento in the context of a stand-alone module the autoloader helps PHPStan to properly resolve the factory & proxy classes.
7+
8+
## Mocked classes autoloader
9+
This PHPStan extension provides an autoloader for "mocked" classes. These are classes that replace the Magento-specific implementations
10+
to fix problems with type hints or missing methods in interfaces and such. The autoloader will check if a class, interface,
11+
or trait exists locally in the extension's folder of mocks. If so, it will load the local version instead of the one being
12+
shipped by Magento. Once those problems are fixed in Magento, those mocked files can be removed again.
13+
14+
## TestFramework autoloader
15+
This PHPStan extension provides an autoloader for `Magento\TestFramework` classes to let you run PHPStan also against your test classes.
16+
17+
## Type hints
18+
19+
### TestFramework ObjectManager type hints
20+
A type extension is provided for `Magento\Framework\TestFramework\Unit\Helper\ObjectManager` method calls to return the correct return type.
21+
Additionally, a PHPStan rule checks that only `Magento\Framework\Data\Collection` sub classes can be passed to
22+
`Magento\Framework\TestFramework\Unit\Helper\ObjectManager::getCollectionMock()`.
23+
24+
### ObjectManager type hints
25+
A type extension is provided so that `Magento\Framework\App\ObjectManager` method calls do return the correct return type.
26+
27+
## Magic method calls
28+
For some classes like `Magento\Framework\DataObject` or `Magento\Framework\Session\SessionManager` PHPStan logic is provided
29+
to be able to let the magic method calls return proper types.
30+
31+
## Extension attributes
32+
This PHPStan extension supports [extension attributes](https://devdocs.magento.com/guides/v2.4/extension-dev-guide/extension_attributes/adding-attributes.html) by parsing the `extension_attributes.xml` files.
33+
34+
## PHPStan rules
35+
36+
The following rules are available to run checks against your codebase, e.g. if your implementation adheres to the
37+
service contracts specification. Each of the rules can be disabled if needed.
38+
39+
### Service contracts
40+
41+
Since Magento framework version 100.1.0 entities must not be responsible for their own loading, [service contracts](https://devdocs.magento.com/guides/v2.4/extension-dev-guide/service-contracts/service-contracts.html) should
42+
be used to persist entities.
43+
44+
To disable this rule add the following code to your `phpstan.neon` configuration file:
45+
```
46+
parameters:
47+
magento:
48+
checkServiceContracts: false
49+
```
50+
51+
### Collections should be used directly via factory
52+
53+
Since Magento framework version 101.0.0 Collections should be used directly via factory instead of calling
54+
`\Magento\Framework\Model\AbstractModel::getCollection()` directly.
55+
56+
To disable this rule add the following code to your `phpstan.neon` configuration file:
57+
```
58+
parameters:
59+
magento:
60+
checkCollectionViaFactory: false
61+
```

0 commit comments

Comments
 (0)