Added optional error handler.

Author: Bilge

README.md

@@ -20,19 +20,23 @@ Usage
 The `retry` function has the following signature.
 
 ```
-retry(int $times, callable $operation);
+retry(int $times, callable $operation, callable $onError = null);
 ```
 * `$times` specifies how many times the operation may be called.
 * `$operation` is a callback to be run up to the specified number of times.
+* `$onError` is called immediately before retrying the operation.
 
-Note that in the [original library](https://github.com/igorw/retry), `$times` specified the number of *retries* and therefore the operation could run up to `n + 1` times. In this version, `$times` specifies exactly the number of times the operation may run such that if zero (`0`) is specified it will never run.
+Note that in the [original library](https://github.com/igorw/retry), `$times` specified the number of *retries* and
+therefore the operation could run up to `n + 1` times. In this version, `$times` specifies exactly the number of
+times the operation may run such that if zero (`0`) is specified it will never run.
 
 ### Example
 
+The following code fragment attempts to fetch data from a URL over HTTP up to five times.
+
 ```php
 use function ScriptFUSION\Retry\retry;
 
-// Try an operation up to 5 times.
 $response = retry(5, function () use ($url) {
     return HttpConnector::fetch($url);
 });
@@ -47,4 +51,3 @@ $response = retry(5, function () use ($url) {
   [Coverage image]: https://coveralls.io/repos/ScriptFUSION/Retry/badge.svg "Test coverage"
   [Style]: https://styleci.io/repos/62990558
   [Style image]: https://styleci.io/repos/62990558/shield?style=flat "Code style"
-

src/retry.php

@@ -2,15 +2,18 @@
 namespace ScriptFUSION\Retry;
 
 /**
- * Tries the specified operation up to the specified number of times.
+ * Tries the specified operation up to the specified number of times. If
+ * specified, the error handler will be called immediately before retrying the
+ * operation.
  *
  * @param int $tries Number of times.
  * @param callable $operation Operation.
+ * @param callable $onError Optional. Error handler.
  *
  * @return mixed Result of running the operation if tries is greater than zero,
  *     otherwise null.
  */
-function retry($tries, callable $operation)
+function retry($tries, callable $operation, callable $onError = null)
 {
     $tries |= 0;
 
@@ -21,11 +24,13 @@ function retry($tries, callable $operation)
     try {
         beginning:
         return $operation();
-    } catch (\Exception $e) {
+    } catch (\Exception $exception) {
         if ($tries === ++$attempts) {
-            throw new FailingTooHardException($attempts, $e);
+            throw new FailingTooHardException($attempts, $exception);
         }
 
+        $onError && $onError($exception);
+
         goto beginning;
     }
 }

test/RetryTest.php

@@ -10,7 +10,7 @@ public function testWithoutFailing()
         $invocations = 0;
 
         $value = \ScriptFUSION\Retry\retry($tries = 1, function () use (&$invocations) {
-            $invocations++;
+            ++$invocations;
 
             return 5;
         });
@@ -25,10 +25,11 @@ public function testFailingOnce()
         $failed = false;
 
         $value = \ScriptFUSION\Retry\retry($tries = 2, function () use (&$invocations, &$failed) {
-            $invocations++;
+            ++$invocations;
 
             if (!$failed) {
                 $failed = true;
+
                 throw new \RuntimeException;
             }
 
@@ -45,7 +46,7 @@ public function testZeroTries()
         $invocations = 0;
 
         $value = \ScriptFUSION\Retry\retry($tries = 0, function () use (&$invocations) {
-            $invocations++;
+            ++$invocations;
 
             return 5;
         });
@@ -61,14 +62,38 @@ public function testFailingTooHard()
 
         try {
             \ScriptFUSION\Retry\retry($tries = 2, function () use (&$invocations, &$innerException) {
-                $invocations++;
+                ++$invocations;
+
                 throw $innerException = new \RuntimeException;
             });
-        } catch (\Exception $outerException) {
+        } catch (FailingTooHardException $outerException) {
         }
 
         self::assertInstanceOf(FailingTooHardException::class, $outerException);
         self::assertSame($innerException, $outerException->getPrevious());
         self::assertSame($tries, $invocations);
     }
+
+    public function testErrorCallback()
+    {
+        $invocations = $errors = 0;
+        $outerException = $innerException = null;
+
+        try {
+            \ScriptFUSION\Retry\retry($tries = 2, function () use (&$invocations, &$innerException) {
+                ++$invocations;
+
+                throw $innerException = new \RuntimeException;
+            }, function (\Exception $exception) use (&$innerException, &$errors) {
+                ++$errors;
+
+                self::assertSame($innerException, $exception);
+            });
+        } catch (FailingTooHardException $outerException) {
+        }
+
+        self::assertInstanceOf(FailingTooHardException::class, $outerException);
+        self::assertSame($tries, $invocations);
+        self::assertSame(1, $errors);
+    }
 }