Improve docs

bitExpert · Dec 23, 2021 · 1c50654 · 1c50654
1 parent 4cd232f
commit 1c50654
Show file tree

Hide file tree

Showing 2 changed files with 101 additions and 61 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # bitexpert/phpstan-magento
 
-This package provides some additional features for PHPStan to make it
-work for Magento 2 projects.
+This package provides some additional features for PHPStan to make it work for Magento 2 projects.
+You can use this PHPStan extension for both Magento module projects and Magento application projects.
 
 [![Build Status](https://github.com/bitExpert/phpstan-magento/workflows/ci/badge.svg?branch=master)](https://github.com/bitExpert/phpstan-magento/actions)
 [![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.
 
 PHP: PHP 7.2 or higher
 
-Magento: Magento 2.3 or higher
+Magento: Magento 2.3.0 or higher
 
 PHPStan: PHPStan 1.1
 
-If you are using a Magento version that requires an older version of PHPStan,  you need to manually upgrade it before 
-installing this extension. Change the PHPStan version to 1.1 in your composer.json and run:
+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 
+installing this extension. in your composer.json Change the PHPStan version to `~1.1` and run:
 
 ```
 composer update phpstan/phpstan --with-all-dependencies
@@ -30,72 +30,51 @@ You can add `bitexpert/phpstan-magento` as a dev dependency, as follows:
 composer.phar require --dev bitexpert/phpstan-magento
 ```
 
-Include extension.neon and the autoloader.php file in your project's PHPStan config:
+### PHPStan configuration
+
+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.
+
+This PHPStan extension needs to be registered with PHPStan so that PHPStan can load it properly.
+The easiest way to do this is to install the `phpstan/extension-installer` package as follows:
+
+```
+composer.phar require --dev phpstan/extension-installer
+```
+
+As an alternative, you can manually include the extension configuration `vendor/bitexpert/phpstan-magento/extension.neon` in
+your `phpstan.neon` file:
 
 ```neon
-parameters:
-	bootstrapFiles:
-		- vendor/bitexpert/phpstan-magento/autoload.php
 includes:
 	- vendor/bitexpert/phpstan-magento/extension.neon
 ```
 
-## Features
-
-### Class generator for factory & proxy classes
-The extension adds a class generator for factory & proxy classes similar as Magento does it. When running PHPStan in 
-context of a Magento application this is not needed if you point PHPStan also to the generated files folder. When running 
-Magento in the context of a module, this is required so that PHPStan gets the full picture of all classes needed.
-
-### Mocked classes autoloader
-The extension adds an autoloader for "mocked" classes. These are classes that replace the Magento specific implementations 
-to fix problems with type hints or missing methods in interfaces and such. The autoloader will check if a class, interface, 
-or trait exists locally in the extension's folder of mocks. If so, it will load the local version instead of the one being 
-shipped by Magento. Once those problems are fixed in Magento, those mocks can be removed again.
-
-### TestFramework autoloader
-The extension provides an autoloader for `Magento\TestFramework` classes to let you run PHPStan also against your test classes.
-
-#### TestFramework ObjectManager type hints
-A type extension was added so that `Magento\Framework\TestFramework\Unit\Helper\ObjectManager` calls return the correct return type. 
-Additionally, a PHPStan rule was added to check that only `Magento\Framework\Data\Collection` sub classes can be passed to  
-`Magento\Framework\TestFramework\Unit\Helper\ObjectManager::getCollectionMock()`.
-
-### ObjectManager type hints
-A type extension was added so that `Magento\Framework\App\ObjectManager` calls return the correct return type.
-
-### Support for magic method calls
-For some classes like the `Magento\Framework\DataObject` or `Magento\Framework\Session\SessionManager` logic was added 
-to be able to support magic method calls.
+For the final step, you need to register the custom autoloader that comes with this extension by adding `vendor/bitexpert/phpstan-magento/autoload.php`
+as a bootstrap file:
 
-### PHPStan rules
-
-The following rules are available to run checks against your codebase, e.g. if your implementation adheres to the 
-service contracts specification. Each of the rules can be disabled if needed.
-
-#### Service contracts
-
-Since Magento framework version 100.1.0 entities must not be responsible for their own loading, service contracts should
-be used to persist entities.
-
-To disable this rule add the following code to your `phpstan.neon` configuration file:
-```
+```neon
 parameters:
-    magento:
-        checkServiceContracts: false
+	bootstrapFiles:
+		- vendor/bitexpert/phpstan-magento/autoload.php
 ```
 
-#### Collections should be used directly via factory
-
-Since Magento framework version 101.0.0 Collections should be used directly via factory instead of calling 
-`\Magento\Framework\Model\AbstractModel::getCollection()` directly.
-
-To disable this rule add the following code to your `phpstan.neon` configuration file:
-```
-parameters:
-    magento:
-        checkCollectionViaFactory: false
-```
+## Feature overview
+
+This PHPStan extension works for both Magento module projects and Magento application projects.
+
+- Class generator for factory & proxy classes
+- Mocked classes autoloader
+- TestFramework autoloader
+- Type hints
+  - TestFramework ObjectManager type hints
+  - ObjectManager type hints
+- Magic method calls
+- Extension attributes
+- PHPStan rules
+  - Service contracts
+  - Collections should be used directly via factory
+
+For a detailed overview, check the feature documentation [here](docs/features.md).
 
 ## Contribute
 

diff --git a/docs/features.md b/docs/features.md
@@ -0,0 +1,61 @@
+# Features
+
+## Class generator for factory & proxy classes
+This PHPStan extension includes a class generator and autoloader for factory & proxy classes similar to what Magento does. When running PHPStan in
+the context of a Magento application this is not needed if you point PHPStan also to the generated files folder. When running
+Magento in the context of a stand-alone module the autoloader helps PHPStan to properly resolve the factory & proxy classes.
+
+## Mocked classes autoloader
+This PHPStan extension provides an autoloader for "mocked" classes. These are classes that replace the Magento-specific implementations
+to fix problems with type hints or missing methods in interfaces and such. The autoloader will check if a class, interface,
+or trait exists locally in the extension's folder of mocks. If so, it will load the local version instead of the one being
+shipped by Magento. Once those problems are fixed in Magento, those mocked files can be removed again.
+
+## TestFramework autoloader
+This PHPStan extension provides an autoloader for `Magento\TestFramework` classes to let you run PHPStan also against your test classes.
+
+## Type hints
+
+### TestFramework ObjectManager type hints
+A type extension is provided for `Magento\Framework\TestFramework\Unit\Helper\ObjectManager` method calls to return the correct return type.
+Additionally, a PHPStan rule checks that only `Magento\Framework\Data\Collection` sub classes can be passed to  
+`Magento\Framework\TestFramework\Unit\Helper\ObjectManager::getCollectionMock()`.
+
+### ObjectManager type hints
+A type extension is provided so that `Magento\Framework\App\ObjectManager` method calls do return the correct return type.
+
+## Magic method calls
+For some classes like `Magento\Framework\DataObject` or `Magento\Framework\Session\SessionManager` PHPStan logic is provided
+to be able to let the magic method calls return proper types.
+
+## Extension attributes
+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.
+
+## PHPStan rules
+
+The following rules are available to run checks against your codebase, e.g. if your implementation adheres to the
+service contracts specification. Each of the rules can be disabled if needed.
+
+### Service contracts
+
+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
+be used to persist entities.
+
+To disable this rule add the following code to your `phpstan.neon` configuration file:
+```
+parameters:
+    magento:
+        checkServiceContracts: false
+```
+
+### Collections should be used directly via factory
+
+Since Magento framework version 101.0.0 Collections should be used directly via factory instead of calling
+`\Magento\Framework\Model\AbstractModel::getCollection()` directly.
+
+To disable this rule add the following code to your `phpstan.neon` configuration file:
+```
+parameters:
+    magento:
+        checkCollectionViaFactory: false
+```