add docs

Author: corsicanec82

Diff for: README.md

@@ -2,7 +2,55 @@
 
 [![github action status](https://github.com/Hexlet/phpstan-functional-programming/workflows/PHP%20CI/badge.svg)](https://github.com/Hexlet/phpstan-functional-programming/actions)
 
-PHPStan for functional programming
+[PHPStan](https://phpstan.org) rules for functional programming
+
+## Install
+
+To use this extension, require it in [Composer](https://getcomposer.org):
+
+```sh
+$ composer require --dev hexlet/phpstan-fp
+```
+
+## Usage
+
+All of the rules provided (and used) by this library are included in [`extension.neon`](extension.neon).
+
+When you are using [phpstan/extension-installer](https://github.com/phpstan/extension-installer), `extension.neon` will be automatically included.
+
+Otherwise you need to include `extension.neon` in your `phpstan.neon`:
+
+```neon
+includes:
+  - vendor/hexlet/phpstan-fp/extension.neon
+```
+
+## Rules
+
+This package provides the following rules for use with *PHPStan*:
+
+* [`DisallowClassesRule`](docs/rules/DisallowClassesRule.md)
+* [`DisallowThrowRule`](docs/rules/DisallowThrowRule.md)
+* [`DisallowUnusedExpressionRule`](docs/rules/DisallowUnusedExpressionRule.md)
+* [`DisallowMutatingFunctionsRule`](docs/rules/DisallowMutatingFunctionsRule.md)
+* [`DisallowLoopsRule`](docs/rules/DisallowLoopsRule.md)
+* [`DisallowMutationRule`](docs/rules/DisallowMutationRule.md)
+
+## Disabling rules
+
+If you don't want to start using some of the available rules at once, you can.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowClasses: false
+    disallowLoops: false
+    disallowThrow: false
+    disallowUnusedExpression: false
+    disallowVariablesMutation: false
+    disallowMutatingFunctions: false
+```
 
 [![Hexlet Ltd. logo](https://raw.githubusercontent.com/Hexlet/hexletguides.github.io/master/images/hexlet_logo128.png)](https://ru.hexlet.io/pages/about?utm_source=github&utm_medium=link&utm_campaign=phpstan-functional-programming)
 

Diff for: docs/rules/DisallowClassesRule.md

@@ -0,0 +1,48 @@
+# DisallowClassesRule
+
+*Forbid the use of `class`*
+
+Classes are nice tools to use when programming with the object-oriented paradigm, as they hold internal state and give access to methods on the instances. In functional programming, having stateful objects is more harmful than helpful, and should be replaced by the use of pure functions.
+
+### Fail
+
+```php
+<?php
+
+class Point
+{
+    private int $x;
+    private int $y;
+
+    public function __construct(int $x, int $y)
+    {
+        $this->x = $x;
+        $this->y = $y;
+    }
+}
+```
+
+### Pass
+
+```php
+<?php
+
+function point(int $x, int $y): array
+{
+    return [
+        'x' => $x,
+        'y' => $y,
+    ];
+}
+```
+
+## Rule configuration
+
+The rule is enabled by default. To turn it off, edit your *phpstan.neon* file.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowClasses: false
+```

Diff for: docs/rules/DisallowLoopsRule.md

@@ -0,0 +1,70 @@
+# DisallowLoopsRule
+
+*Forbid the use of loops*
+
+Loops, such as `for`, `foreach`, `do` or `while` loops, work well when using a procedural paradigm. In functional programming, recursion or implementation agnostic operations like `array_map`, `array_filter` and `array_reduce` are preferred.
+
+### Fail
+
+```php
+<?php
+
+$result = [];
+$elements = [1, 2, 3];
+
+for ($i = 0; $i < count($elements); $i++) {
+    if ($elements[$i] > 2) {
+        $result[] = $elements[$i];
+    }
+}
+
+foreach ($elements as $element) {
+    $result[] = $element * 10;
+}
+
+$a = 1;
+while ($a < 100) {
+    $result[] = $a;
+    $a *= 2;
+}
+
+$b = 1;
+do {
+    $result[] = $b;
+    $b *= 2;
+} while ($b < 100);
+```
+
+### Pass
+
+```php
+<?php
+
+$elements = [1, 2, 3];
+
+$result1 = array_filter($elements, fn($element) => $element > 2);
+
+$result2 = array_map(fn($element) => $element * 10, $elements);
+
+function doubleThemAll(int $n): array
+{
+	if ($n >= 100) {
+		return [];
+	}
+	
+	return [$n, ...doubleThemAll($n * 2)];
+}
+
+$result3 = doubleThemAll(1);
+```
+
+## Rule configuration
+
+The rule is enabled by default. To turn it off, edit your *phpstan.neon* file.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowLoops: false
+```

Diff for: docs/rules/DisallowMutatingFunctionsRule.md

@@ -0,0 +1,44 @@
+# DisallowMutatingFunctionsRule
+
+*Forbid the use of mutating functions*
+
+If you want to program as if your variables are immutable, you should not use mutating functions of arrays, such as `array_push`. This rule reports the use of functions with the following names: `array_multisort`, `array_pop`, `array_push`, `array_shift`, `array_splice`, `array_unshift`, `arsort`, `asort`, `krsort`, `ksort`, `natcasesort`, `natsort`, `rsort`, `shuffle`, `sort`, `uasort`, `uksort`, `usort`.
+
+### Fail
+
+```php
+<?php
+
+$arr1 = [10, 100, 100, 0];
+$arr2 = [1, 3, 2, 4];
+
+array_multisort($arr1, $arr2);
+$last = array_pop($arr2);
+array_push($arr2, 6, 7);
+$first = array_shift($arr2);
+array_splice($arr1, 2);
+array_unshift($arr1, -1, 0);
+arsort($arr2);
+asort($arr2);
+krsort($arr2);
+ksort($arr2);
+natcasesort($arr2);
+natsort($arr2);
+rsort($arr2);
+shuffle($arr2);
+sort($arr2);
+uasort($arr2);
+uksort($arr2);
+usort($arr2);
+```
+
+## Rule configuration
+
+The rule is enabled by default. To turn it off, edit your *phpstan.neon* file.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowMutatingFunctions: false
+```

Diff for: docs/rules/DisallowMutationRule.md

@@ -0,0 +1,60 @@
+# DisallowMutationRule
+
+*Forbid the use of mutating operators*
+
+If you want to program as if your variables are immutable, part of the answer is to not mutation by re-assigning to a variable, and not use update operators like `++`, `+=` or `--` and others.
+
+### Fail
+
+```php
+<?php
+
+$a = 6;
+$b =& $a;
+$text = 'hello';
+$arr = [1, 2, 3];
+
+$b = 18;
+$a = 15;
+
+$a += 1;
+$a -= 1;
+$a *= 1;
+$a /= 1;
+$a %= 1;
+$a ??= 7;
+$text .= ' world';
+...
+
+$a++;
+$a--;
+++$a;
+--$a;
+
+function (int $num1, &$num2)
+{
+    $num1 = 2;
+    $num2 = 5;
+}
+
+$fn = function () use ($a, &$b) {
+    $a = 5;
+    $b = 10;
+};
+
+$arr[1] = 5;
+$arr[] = 125;
+$arr = [5, 6, 7];
+[$a, $b] = $arr;
+```
+
+## Rule configuration
+
+The rule is enabled by default. To turn it off, edit your *phpstan.neon* file.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowVariablesMutation: false
+```

Diff for: docs/rules/DisallowThrowRule.md

@@ -0,0 +1,27 @@
+# DisallowThrowRule
+
+*Forbid the use of `throw`*
+
+When you throw an exception in PHP, you effectively perform a `GOTO`: your position in the program's execution jumps to the appropriate exception handler, and execution continues. This is fine, but it obviously means that your original function has a side-effect: calling it will fundamentally alter the program flow.
+
+### Fail
+
+```php
+<?php
+
+function throwAnError(): void
+{
+    throw new Exception('some error message');
+}
+```
+
+## Rule configuration
+
+The rule is enabled by default. To turn it off, edit your *phpstan.neon* file.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowThrow: false
+```

Diff for: docs/rules/DisallowUnusedExpressionRule.md

@@ -0,0 +1,51 @@
+# DisallowUnusedExpressionRule
+
+*Enforce that an expression gets used*
+
+In functional programming, functions do not mutate any values or cause side-effects, and it is therefore useless to call a function without using its result. The result should be assigned to a variable, passed as a parameter of another function, etc. Unused literals are reported too as they represent dead code.
+
+### Fail
+
+```php
+<?php
+
+2 + 5;
+
+foo();
+
+function sum(int $a, int $b)
+{
+   2 + 5;
+}
+
+sum(2, 5);
+```
+
+### Pass
+
+```php
+<?php
+
+$result1 = 2 + 5;
+
+$result2 = foo();
+
+function sum(int $a, int $b): int
+{
+   return 2 + 5;
+}
+
+$result3 = sum(2, 5);
+
+```
+
+## Rule configuration
+
+The rule is enabled by default. To turn it off, edit your *phpstan.neon* file.
+
+```neon
+parameters:
+
+  phpstanFunctionalProgramming:
+    disallowUnusedExpression: false
+```