Added capability to halt retries by returning false from exception ha…

…ndler.

README.md

@@ -19,15 +19,17 @@ Requirements
 Usage
 -----
 
-The `retry` function retries an operation up to the specified number of times with an optional error handler and has
-the following signature.
+The `retry` function retries an operation up to the specified number of times with an optional exception handler.
+
+If an exception handler is specified, it is called immediately before retrying the operation. If the handler returns
+`false`, the operation is not retried.
 
 ```
 retry(int $times, callable $operation, callable $onError = null);
 ```
 * `$times`—Maximum number of times the operation may run.
 * `$operation`—Operation to run up to the specified number of times.
-* `$onError`—Optional. Error handler called immediately before retrying the operation.
+* `$onError`—Optional. Exception handler that receives the thrown exception as its first argument.
 
 Note in the original library, `$times` specifies the number of *retries* and therefore the operation could run up to
 `$times + 1` times. In this version, `$times` specifies exactly the number of times the operation may run such that if

src/retry.php

@@ -29,7 +29,9 @@ function retry($tries, callable $operation, callable $onError = null)
             throw new FailingTooHardException($attempts, $exception);
         }
 
-        $onError && $onError($exception);
+        if ($onError && $onError($exception) === false) {
+            return;
+        }
 
         goto beginning;
     }

test/RetryTest.php

@@ -94,6 +94,23 @@ public function testErrorCallback()
 
         self::assertInstanceOf(FailingTooHardException::class, $outerException);
         self::assertSame($tries, $invocations);
-        self::assertSame(1, $errors);
+        self::assertSame($tries - 1, $errors);
+    }
+
+    public function testErrorCallbackHalt()
+    {
+        $invocations = 0;
+        try {
+            \ScriptFUSION\Retry\retry($tries = 2, function () use (&$invocations) {
+                ++$invocations;
+
+                throw new \RuntimeException;
+            }, function () {
+                return false;
+            });
+        } catch (FailingTooHardException $exception) {
+        }
+
+        self::assertSame(1, $invocations);
     }
 }