Merge d4ade11 into 9828731

README.md

@@ -34,7 +34,7 @@ This package includes helpful global helpers for your project, separated into di
 * `random_unique`: Returns a unique amount of results from a random generator executed a number of times.
 * `list_from`: Skips the first values of an array, so these can be listed into variables.
 * `none_of`: Checks if none of the options compared or called to a subject returns true.
-* `throttle`: Throttles a given callback by a key.
+* `throttle`: Returns the Rate Limiter or throttles a given callback by a key.
 * `unless`: Returns a value when a condition is falsy.
 * `swap_vars`: Swap two variables values, and returns the second variable original value.
 * `when`: Returns a value when a condition is truthy.
@@ -79,6 +79,7 @@ This package includes helpful global helpers for your project, separated into di
 
 * `artisan`: Returns the Artisan console instance, or calls an Artisan command.
 * `hasher`: Returns the Hasher instance, or hashes a value.
+* `rate_limiter`: Return a new the Rate Limiter instance.
 * `user`: Returns the current user authenticated, or `null` if is a guest.
 
 > This package is focused on the backend. If you want views helpers, I recommend you to use [custom Blade directives](https://laravel.com/docs/blade#extending-blade) instead.

src/helpers.php

@@ -105,17 +105,29 @@ function pipeline($passable, $pipes, $destination = null)
 
 if (! function_exists('throttle')) {
     /**
-     * Throttles a given callback by a key. Returns true is the callable is executed.
+     * Returns the Rate Limiter or throttles a given callback by a key.
+     *
+     * If only a key is given, it will return when it will be available.
+     *
+     * It will return `true` if the callback is executed, and `false` when not.
      *
      * @param  string  $key
      * @param  callable  $callback
      * @param  int  $tries
      * @param  int  $decayMinutes
-     * @return mixed|bool
+     * @return \Illuminate\Cache\RateLimiter|\Illuminate\Support\Carbon|bool
      */
-    function throttle($key, callable $callback, $tries = 60, $decayMinutes = 1)
+    function throttle($key = null, callable $callback = null, $tries = 60, $decayMinutes = 1)
     {
-        $limiter = app(RateLimiter::class);
+        $limiter = rate_limiter();
+
+        if (0 === $args = func_num_args()) {
+            return $limiter;
+        }
+
+        if ($args === 1) {
+            return now()->addSeconds($limiter->availableIn($key));
+        }
 
         if (! $limiter->tooManyAttempts($key, $tries)) {
             $callback();

src/services.php

@@ -1,5 +1,6 @@
 <?php
 
+use Illuminate\Cache\RateLimiter;
 use Illuminate\Contracts\Console\Kernel;
 
 if (! function_exists('artisan')) {
@@ -35,6 +36,18 @@ function hasher($value = null, $options = [])
     }
 }
 
+if (!function_exists('rate_limiter')) {
+    /**
+     * Return a new the Rate Limiter instance.
+     *
+     * @return \Illuminate\Cache\RateLimiter
+     */
+    function rate_limiter()
+    {
+        return app(RateLimiter::class);
+    }
+}
+
 if (! function_exists('user')) {
     /**
      * Returns the current user authenticated, or `null` if is a guest.

tests/HelpersTest.php

@@ -3,10 +3,13 @@
 namespace Tests;
 
 use Closure;
+use DateTimeInterface;
 use Illuminate\Support\Str;
 use Illuminate\Support\Fluent;
 use Orchestra\Testbench\TestCase;
+use Illuminate\Cache\RateLimiter;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Date;
 use Illuminate\Support\LazyCollection;
 
 class HelpersTest extends TestCase
@@ -168,6 +171,8 @@ function ($foo, $next) {
 
     public function test_throttle()
     {
+        $this->assertInstanceOf(RateLimiter::class, throttle());
+
         $randomFunction = function () {
             return Str::random();
         };
@@ -183,6 +188,13 @@ public function test_throttle()
         $this->assertTrue($second);
         $this->assertFalse(throttle('quz', $randomFunction, 1, 60));
         $this->assertTrue(throttle('qux', $randomFunction, 1, 60));
+
+        Date::setTestNow($now = Date::create(2020, 01, 04, 16, 30));
+
+        throttle('quuz', $randomFunction, 1, 1);
+
+        $this->assertInstanceOf(DateTimeInterface::class, $carbon = throttle('quuz'));
+        $this->assertSame(60, throttle('quuz')->diffInSeconds());
     }
 
     public function test_unless()

tests/ServicesTest.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Support\Str;
 use Orchestra\Testbench\TestCase;
+use Illuminate\Cache\RateLimiter;
 use Illuminate\Foundation\Auth\User;
 use Orchestra\Testbench\Console\Kernel;
 use Illuminate\Support\Facades\Artisan;
@@ -22,6 +23,11 @@ public function test_artisan()
         $this->assertSame(0, artisan('foo'));
     }
 
+    public function test_rate_limiter()
+    {
+        $this->assertInstanceOf(RateLimiter::class, rate_limiter());
+    }
+
     public function test_hasher()
     {
         $this->assertInstanceOf(Hasher::class, hasher());