diff --git a/helpers.md b/helpers.md index 66691c59da..d7c6ad6538 100644 --- a/helpers.md +++ b/helpers.md @@ -9,6 +9,7 @@ - [Lottery](#lottery) - [Pipeline](#pipeline) - [Sleep](#sleep) + - [Timebox](#timebox) ## Introduction @@ -2769,3 +2770,20 @@ $start->diffForHumans(); // 1 second ago ``` Laravel uses the `Sleep` class internally whenever it is pausing execution. For example, the [`retry`](#method-retry) helper uses the `Sleep` class when sleeping, allowing for improved testability when using that helper. + + +### Timebox + +Laravel's `Timebox` class ensures that the given callback always takes a fixed amount of time to execute, even if its actual execution completes sooner. This is particularly useful for cryptographic operations and user authentication checks, where attackers might exploit variations in execution time to infer sensitive information. + +If the execution exceeds the fixed duration, `Timebox` has no effect. It is up to the developer to choose a sufficiently long time as the fixed duration to account for worst-case scenarios. + +The call method accepts a closure and a time limit in microseconds, and then executes the closure and waits until the time limit is reached: + + use Illuminate\Support\Timebox; + + (new Timebox)->call(function ($timebox) { + // ... + }, microseconds: 10000); + +If an exception is thrown within the closure, this class will respect the defined delay and re-throw the exception after the delay.