Fix: README.md

Jan0707 · Mar 1, 2020 · 934b96c · 934b96c
1 parent d9ad771
commit 934b96c
Showing 1 changed file with 158 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -1,82 +1,207 @@
+# phpstan-prophecy
+
 [![Continuous Integration](https://github.com/Jan0707/phpstan-prophecy/workflows/Continuous%20Integration/badge.svg)](https://github.com/Jan0707/phpstan-prophecy/actions)
+
 [![Latest Stable Version](https://poser.pugx.org/jangregor/phpstan-prophecy/v/stable)](https://packagist.org/packages/jangregor/phpstan-prophecy)
 [![Total Downloads](https://poser.pugx.org/jangregor/phpstan-prophecy/downloads)](https://packagist.org/packages/jangregor/phpstan-prophecy)
+
 [![Violinist Enabled](https://img.shields.io/badge/violinist-enabled-brightgreen.svg)](https://violinist.io)
 
-# PHPStan-Prophecy
+Provides a [`prophecy/prophecy`](https://github.com/phpspec/prophecy) extension for [`phpstan/phpstan`](https://github.com/phpstan/phpstan)
+
+## Installation
+
+Run
+
+```shell
+$ composer require --dev jangregor/phpstan-prophecy
+```
+
+## Configuration
 
-## Introduction
+### Automatic
 
-PHPStan is a static code analysis tool for php, you can [find out more about it here](https://github.com/phpstan/phpstan).
+When using [`phpstan/extension-installer`](https://github.com/phpstan/extension-installer), no further setup is required.
 
-This repository provides an extension so that it also understands code that uses the Prophecy library to fake objects in unit tests. So far it covers two use cases:
+### Manual
 
-### Prophesizing and Revealing
+When not using [`phpstan/extension-installer`](https://github.com/phpstan/extension-installer), [`extension.neon`](src/extension.neon) needs to be included in `phpstan.neon`:
+
+```diff
+ includes:
++	- vendor/jangregor/phpstan-prophecy/extension.neon
+```
+
+## Usage
+
+### `prophesize()` and `reveal()`
 
 ```php
-$prophecy = $prophet->prophesize(SomeModel::class);
-$instance = $prophecy->reveal();
+<?php
+
+use PHPUnit\Framework;
+
+final class ExampleTest extends Framework\TestCase
+{
+    private $prophecy;
+
+    protected function setUp()
+    {
+        $this->prophecy = $this->prophesize(SomeModel::class);
+    }
+
+    public function testSomething(): void
+    {
+        $prophecy = $this->prophesize(SomeModel::class);
+
+        $testDouble = $prophecy->reveal();
+
+        // ...
+    }
+
+    public function testSomethingElse(): void
+    {
+        $testDouble = $this->prophecy->reveal();
+
+        // ...
+    }
+}
 ```
 
-It will help PHPStan to understand that the `$instance` variable is indeed an instance of `SomeModel`.
+:bulb: With this extension enabled, `phpstan/phpstan` will understand that `$testDouble` is an instance of `SomeModel`:
 
-### Method Predictions
+### `prophesize()`, `willExtend()`, and `reveal()`
 
 ```php
-$prophecy = $prophet->prophesize(Calculator::class);
-$prophecy->doubleTheNumber(Argument::is(2))->willReturn(5);
+<?php
+
+use PHPUnit\Framework;
+
+final class ExampleTest extends Framework\TestCase
+{
+    private $prophecy;
+
+    protected function setUp()
+    {
+        $this->prophecy = $this->prophesize()->willExtend(SomeModel::class)
+    }
+
+    public function testSomething(): void
+    {
+        $prophecy = $this->prophesize()->willExtend(SomeModel::class);
+
+        $testDouble = $prophecy->reveal();
 
-$instance = $prophecy->reveal();
-$instance->doubleTheNumber(2); // Will return 5
+        // ...
+    }
+
+    public function testSomethingElse(): void
+    {
+        $testDouble = $this->prophecy->reveal();
+
+        // ...
+    }
+}
 ```
 
-It will also help PHPStan to understand that `$prophecy` accepts method calls to all methods that are implemented by its prophesized class.
+:bulb: With this extension enabled, `phpstan/phpstan` will understand that `$testDouble` is an instance of `SomeModel`:
 
-**HINT:** Currently there are no checks in place to validate the arguments of methods that are being called on prophecies.
+### `prophesize()`, `willImplement()`, and `reveal()`
 
-## Installation and usage
+```php
+<?php
 
-Install via composer:
+use PHPUnit\Framework;
 
-```shell
-composer require --dev jangregor/phpstan-prophecy
+final class ExampleTest extends Framework\TestCase
+{
+    private $prophecy;
+
+    protected function setUp()
+    {
+        $this->prophecy = $this->prophesize(SomeModel::class)->willImplement(SomeInterface::class);
+    }
+
+    public function testSomething(): void
+    {
+        $prophecy = $this->prophesize(SomeModel::class)->willImplement(SomeInterface::class);
+
+        $testDouble = $prophecy->reveal();
+
+        // ...
+    }
+
+    public function testSomethingElse(): void
+    {
+        $testDouble = $this->prophecy->reveal();
+
+        // ...
+    }
+}
 ```
 
-### Automatic Extension Setup
+:bulb: With this extension enabled, `phpstan/phpstan` will understand that `$testDouble` is an instance of `SomModel` that also implements `SomeInterface`:
+
+### Method Predictions
+
+```php
+<?php
 
-If you have the [PHPStan Extension Installer](https://github.com/phpstan/extension-installer) installed as well, there is no next step required.
-Otherwise, please proceed with the manual setup step.
+use PHPUnit\Framework;
 
-### Manual Setup
+final class ExampleTest extends Framework\TestCase
+{
+    public function testSomething(): void
+    {
+        $prophecy = $this->prophesize(SomeModel::class);
 
-And then make sure to add the extension to your `phpstan.neon` file:
+        $prophecy
+            ->doubleTheNumber(Argument::is(2))
+            ->willReturn(4);
 
-```neon
-includes:
-	- vendor/jangregor/phpstan-prophecy/extension.neon
+        $testDouble = $prophecy->reveal();
+
+        // ...
+    }
+}
 ```
 
-And you should be good to go. Happy testing!
+:bulb: With this extension enabled, `phpstan/phpstan` will understand that `$prophecy`  accepts method calls to all methods that are implemented by its prophesized class (or additionally implemented interfaces, when using `willImplement()`).
+
+### Method Arguments
+
+:exclamation: Currently here are no checks in place to validate the arguments of methods that are invoked on prophecies.
 
 ## Development
 
-If you need a suitable dev environment you can always use docker.
-Simply build the respective container and tag it via:
+A development environment is provided via [`.docker/Dockerfile`](.docker/Dockerfile).
 
-```
+Run
+
+```shell
 $ docker build -t phpstan-prophecy:7.1 .docker/
 ```
 
-You can then use this tagged container image to run php during development:
+to build and tag the Docker image.
 
-```
+Run
+
+```shell
 $ docker run -it --rm --name phpstan-prophecy-dev -v "$PWD":/var/www/html -w /var/www/html phpstan-prophecy:7.1 bash
 ```
 
+to open a shell in the Docker container.
+
 ## Changelog
 
 Please have a look at [`CHANGELOG.md`](CHANGELOG.md).
 
 ## Contributing
 
 Please have a look at [`CONTRIBUTING.md`](.github/CONTRIBUTING.md).
+
+## License
+
+This package is licensed using the MIT License.
+
+Please have a look at [LICENSE](LICENSE).