Add new rule to simplify a last useless variable assignment. (#2963)

* Add new rule to simplify a last useless variable assignment.

The rule `SimplifyUselessLastVariableAssignRector` try to remove the
latest variable assignment before the variable will return. Variable
assignment and return, must be in the same scope.
This rule is inspired by `SimplifyUselessVariableRector` but will not
replace it.

* Remove exception handling.

build/target-repository/docs/rector_rules_overview.md

@@ -1,12 +1,12 @@
-# 398 Rules Overview
+# 399 Rules Overview
 
 <br>
 
 ## Categories
 
 - [Arguments](#arguments) (5)
 
-- [CodeQuality](#codequality) (75)
+- [CodeQuality](#codequality) (76)
 
 - [CodingStyle](#codingstyle) (36)
 
@@ -1478,6 +1478,25 @@ Simplify tautology ternary to value
 
 <br>
 
+### SimplifyUselessLastVariableAssignRector
+
+Removes the latest useless variable assigns before a variable will return.
+
+- class: [`Rector\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector`](../rules/CodeQuality/Rector/FunctionLike/SimplifyUselessLastVariableAssignRector.php)
+
+```diff
+ function ($b) {
+-    $a = true;
+     if ($b === 1) {
+         return $b;
+     }
+-    return $a;
++    return true;
+ };
+```
+
+<br>
+
 ### SimplifyUselessVariableRector
 
 Removes useless variable assigns

rules-tests/CodeQuality/Rector/FunctionLike/SimplifyUselessLastVariableAssignRector/Fixture/assign_ops.php.inc

@@ -0,0 +1,47 @@
+<?php
+
+namespace Rector\Tests\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector\Fixture;
+
+function () {
+    $b += 1;
+    return $b;
+};
+
+function () {
+    $e /= 1;
+    return $e;
+};
+
+function () {
+    $f **= 1;
+    return $f;
+};
+
+function () {
+    $m .= 1;
+    return $m;
+};
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector\Fixture;
+
+function () {
+    return $b + 1;
+};
+
+function () {
+    return $e / 1;
+};
+
+function () {
+    return $f ** 1;
+};
+
+function () {
+    return $m . 1;
+};
+
+?>

rules-tests/CodeQuality/Rector/FunctionLike/SimplifyUselessLastVariableAssignRector/Fixture/empty_array.php.inc

@@ -0,0 +1,36 @@
+<?php
+
+namespace Rector\Tests\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector\Fixture;
+
+class EmptyArray
+{
+    public function run()
+    {
+        $content = [];
+        if (\rand(0, 1)) {
+            echo '';
+        }
+
+        return $content;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector\Fixture;
+
+class EmptyArray
+{
+    public function run()
+    {
+        if (\rand(0, 1)) {
+            echo '';
+        }
+
+        return [];
+    }
+}
+
+?>

rules-tests/CodeQuality/Rector/FunctionLike/SimplifyUselessLastVariableAssignRector/Fixture/fixture.php.inc

@@ -0,0 +1,91 @@
+<?php
+
+namespace Rector\Tests\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector\Fixture;
+
+function () {
+    $a = true;
+    return $a;
+};
+
+function sameVariableInDifferentScope()
+{
+    $n = array_map(function () {
+        return $n + 1;
+    }, []);
+
+    return $n;
+}
+
+function moreVariableOneWithoutAssigment() {
+    $o++;
+    $o = 10;
+
+    return $o;
+}
+
+function assigmentAsFunctionParametr() {
+    doSomething($p = 0);
+    return $p;
+}
+
+function assigmentAfterAssignment() {
+    doSomething($qq = $q = 0);
+    return $q;
+}
+
+function () {
+    $a = 1;
+    $b = 1;
+    $c = [
+        $b-- => $a++,
+        --$b => ++$a,
+    ];
+    return $c;
+};
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\CodeQuality\Rector\FunctionLike\SimplifyUselessLastVariableAssignRector\Fixture;
+
+function () {
+    return true;
+};
+
+function sameVariableInDifferentScope()
+{
+    $n = array_map(function () {
+        return $n + 1;
+    }, []);
+
+    return $n;
+}
+
+function moreVariableOneWithoutAssigment() {
+    $o++;
+
+    return 10;
+}
+
+function assigmentAsFunctionParametr() {
+    doSomething($p = 0);
+    return $p;
+}
+
+function assigmentAfterAssignment() {
+    doSomething($qq = $q = 0);
+    return $q;
+}
+
+function () {
+    $a = 1;
+    $b = 1;
+    $c = [
+        $b-- => $a++,
+        --$b => ++$a,
+    ];
+    return $c;
+};
+
+?>