Lottery.php
TLDR
The Lottery.php file in the Illuminate\Support namespace contains the Lottery class. This class is responsible for creating and running a lottery system. It allows you to set the chances of winning, the number of potential opportunities to win, and callbacks for when the lottery "wins" or "loses". It also provides methods for forcing the lottery to always result in a win or lose, as well as setting a sequence of results for testing purposes.
Methods
__construct
The __construct method initializes a new Lottery instance. It takes the number of expected wins ($chances) and the number of potential opportunities to win ($outOf), which is optional.
odds
The odds method is a static method that creates a new Lottery instance. It is an alternative way to create a Lottery instance instead of using the constructor directly.
winner
The winner method sets the winner callback for the lottery. It takes a callable $callback and returns the Lottery instance. The callback is executed when the lottery "wins".
loser
The loser method sets the loser callback for the lottery. It takes a callable $callback and returns the Lottery instance. The callback is executed when the lottery "loses".
__invoke
The __invoke method allows the Lottery instance to be called as a function. It runs the lottery and returns the result of the winner or loser callback.
choose
The choose method runs the lottery a specified number of times (optional). It returns either a single result or an array of results, depending on the value of $times. If $times is null, it runs the lottery once. If $times is an integer, it runs the lottery that many times.
alwaysWin
The alwaysWin method forces the lottery to always result in a win. Optionally, it can take a callback to be executed before and after setting the result factory. If no callback is provided, it only sets the result factory.
alwaysLose
The alwaysLose method forces the lottery to always result in a loss. Optionally, it can take a callback to be executed before and after setting the result factory. If no callback is provided, it only sets the result factory.
fix
The fix method is an alias for forceResultWithSequence. It sets a sequence of results that will be used to determine the lottery results. It takes an array $sequence of values and an optional $whenMissing callback that is executed when the sequence runs out of values.
forceResultWithSequence
The forceResultWithSequence method sets a sequence of results that will be used to determine the lottery results. It takes an array $sequence of values and an optional $whenMissing callback that is executed when the sequence runs out of values.
determineResultNormally
The determineResultNormally method indicates that the lottery results should be determined normally, without any forced results.
setResultFactory
The setResultFactory method sets the factory that should be used to determine the lottery results. It takes a callable $factory and sets it as the static $resultFactory property.
<?php
namespace Illuminate\Support;
use RuntimeException;
class Lottery
{
/**
* The number of expected wins.
*
* @var int|float
*/
protected $chances;
/**
* The number of potential opportunities to win.
*
* @var int|null
*/
protected $outOf;
/**
* The winning callback.
*
* @var null|callable
*/
protected $winner;
/**
* The losing callback.
*
* @var null|callable
*/
protected $loser;
/**
* The factory that should be used to generate results.
*
* @var callable|null
*/
protected static $resultFactory;
/**
* Create a new Lottery instance.
*
* @param int|float $chances
* @param int|null $outOf
* @return void
*/
public function __construct($chances, $outOf = null)
{
if ($outOf === null && is_float($chances) && $chances > 1) {
throw new RuntimeException('Float must not be greater than 1.');
}
$this->chances = $chances;
$this->outOf = $outOf;
}
/**
* Create a new Lottery instance.
*
* @param int|float $chances
* @param int|null $outOf
* @return static
*/
public static function odds($chances, $outOf = null)
{
return new static($chances, $outOf);
}
/**
* Set the winner callback.
*
* @param callable $callback
* @return $this
*/
public function winner($callback)
{
$this->winner = $callback;
return $this;
}
/**
* Set the loser callback.
*
* @param callable $callback
* @return $this
*/
public function loser($callback)
{
$this->loser = $callback;
return $this;
}
/**
* Run the lottery.
*
* @param mixed ...$args
* @return mixed
*/
public function __invoke(...$args)
{
return $this->runCallback(...$args);
}
/**
* Run the lottery.
*
* @param null|int $times
* @return mixed
*/
public function choose($times = null)
{
if ($times === null) {
return $this->runCallback();
}
$results = [];
for ($i = 0; $i < $times; $i++) {
$results[] = $this->runCallback();
}
return $results;
}
/**
* Run the winner or loser callback, randomly.
*
* @param mixed ...$args
* @return callable
*/
protected function runCallback(...$args)
{
return $this->wins()
? ($this->winner ?? fn () => true)(...$args)
: ($this->loser ?? fn () => false)(...$args);
}
/**
* Determine if the lottery "wins" or "loses".
*
* @return bool
*/
protected function wins()
{
return static::resultFactory()($this->chances, $this->outOf);
}
/**
* The factory that determines the lottery result.
*
* @return callable
*/
protected static function resultFactory()
{
return static::$resultFactory ?? fn ($chances, $outOf) => $outOf === null
? random_int(0, PHP_INT_MAX) / PHP_INT_MAX <= $chances
: random_int(1, $outOf) <= $chances;
}
/**
* Force the lottery to always result in a win.
*
* @param callable|null $callback
* @return void
*/
public static function alwaysWin($callback = null)
{
self::setResultFactory(fn () => true);
if ($callback === null) {
return;
}
$callback();
static::determineResultNormally();
}
/**
* Force the lottery to always result in a lose.
*
* @param callable|null $callback
* @return void
*/
public static function alwaysLose($callback = null)
{
self::setResultFactory(fn () => false);
if ($callback === null) {
return;
}
$callback();
static::determineResultNormally();
}
/**
* Set the sequence that will be used to determine lottery results.
*
* @param array $sequence
* @param callable|null $whenMissing
* @return void
*/
public static function fix($sequence, $whenMissing = null)
{
return static::forceResultWithSequence($sequence, $whenMissing);
}
/**
* Set the sequence that will be used to determine lottery results.
*
* @param array $sequence
* @param callable|null $whenMissing
* @return void
*/
public static function forceResultWithSequence($sequence, $whenMissing = null)
{
$next = 0;
$whenMissing ??= function ($chances, $outOf) use (&$next) {
$factoryCache = static::$resultFactory;
static::$resultFactory = null;
$result = static::resultFactory()($chances, $outOf);
static::$resultFactory = $factoryCache;
$next++;
return $result;
};
static::setResultFactory(function ($chances, $outOf) use (&$next, $sequence, $whenMissing) {
if (array_key_exists($next, $sequence)) {
return $sequence[$next++];
}
return $whenMissing($chances, $outOf);
});
}
/**
* Indicate that the lottery results should be determined normally.
*
* @return void
*/
public static function determineResultNormally()
{
static::$resultFactory = null;
}
/**
* Set the factory that should be used to determine the lottery results.
*
* @param callable $factory
* @return void
*/
public static function setResultFactory($factory)
{
self::$resultFactory = $factory;
}
}