This trait gives you a declarative way to support multiple signatures for the same method.
Say we have a Ticket class with a holdUntil method that lets us put that ticket on hold until a certain date and time by passing in a DateTime object:
class Ticket extends Model
{
// ...
public function holdUntil(DateTime $dateTime)
{
$this->update(['hold_until' => $dateTime]);
}
// ...
}...but now you decide it would be convenient if it could also accept a well-formatted date string.
Normally you'd do something like this:
class Ticket extends Model
{
// ...
public function holdUntil($dateTime)
{
if (is_string($dateTime)) {
$dateTime = Carbon::parse($dateTime);
}
$this->update(['hold_until' => $dateTime]);
}
// ...
}The overloadable trait allows you to essentially pattern match in a declarative way instead of conditionally checking arguments:
class Ticket extends Model
{
use Overloadable;
// ...
public function holdUntil(...$args)
{
return $this->overload($args, [
function (string $dateTime) {
$this->update(['hold_until' => Carbon::parse($dateTime)]);
},
function (DateTime $dateTime) {
$this->update(['hold_until' => $dateTime]);
},
]);
}
// ...
}If you wanted to avoid that duplication, you could even do this wild recursive madness:
class Ticket extends Model
{
use Overloadable;
// ...
public function holdUntil(...$args)
{
return $this->overload($args, [
function (string $dateTime) {
$this->holdUntil(Carbon::parse($dateTime));
},
function (DateTime $dateTime) {
$this->update(['hold_until' => $dateTime]);
},
]);
}
// ...
}You might be thinking:
"Uhhh bro, that looks like even more code."
Yeah, because that example is boring. This one is a bit more fun.
I've always wanted Laravel's validate controller helper to accept a closure as it's last parameter that let me return whatever HTTP response I wanted if validation failed.
But the method signature for validate takes like a million things and I don't want to pass a ton of empty arrays, for example:
public function store()
{
// Super grim! 😭
// ⬇️ ⬇️
$this->validate($request, $rules, [], [], function ($errors) {
return response()->json([
'someOtherInfo' => 'toInclude',
'errors' => $errors
], 422);
});
}I'd love if I could just do:
public function store()
{
$this->validate($request, $rules, function ($errors) {
return response()->json([
'someOtherInfo' => 'toInclude',
'errors' => $errors
], 422);
});
}...and have it magically work, knowing I clearly don't care about the $messages or $customAttributes arguments, but can you imagine how gross it would be to add those checks inside the validate method to do all this argument counting and type checking?!
Check out how it would work with this badass trait from the gods:
trait ValidatesRequests
{
// ...
public function validate(...$args)
{
return $this->overload($args, [
function ($request, $rules, Closure $callback) {
return $this->validateRequest($request, $rules, [], [], $callback);
},
function ($request, $rules, $messages, Closure $callback) {
return $this->validateRequest($request, $rules, $messages, [], $callback);
},
'validateRequest',
]);
}
// Move the real logic into a new private function...
protected function validateRequest(Request $request, array $rules, array $messages = [], array $customAttributes = [], Closure $onErrorCallback = null)
{
$validator = $this->getValidationFactory()->make($request->all(), $rules, $messages, $customAttributes);
if ($validator->fails()) {
$this->throwValidationException($request, $validator, $onErrorCallback);
}
}
// ...
}Overloadable doesn't just work with closures, you can do all sorts of crazy shit!
Check out this example from the test:
class SomeOverloadable
{
use Overloadable;
public function someMethod(...$args)
{
return $this->overload($args, [
// Call this closure if two args are passed and the first is an int
function (int $a, $b) {
return 'From the Closure';
},
// Call this method if the args match the args of `methodA` (uses reflection)
'methodA',
// Call this method if the args match the args of `methodB` (uses reflection)
'methodB',
// Call methodC if exactly 2 arguments of any type are passed
'methodC' => ['*', '*'],
// Call methodD if 3 args are passed and the first is an array
'methodD' => ['array', '*', '*'],
// Call methodE if 3 args are passed and the last is a closure
'methodE' => ['*', '*', Closure::class],
]);
}
private function methodA($arg1)
{
return 'Method A';
}
private function methodB(\DateTime $arg1, array $arg2, int $arg3)
{
return 'Method B';
}
private function methodC($arg1, $arg2)
{
return 'Method C';
}
private function methodD($arg1, $arg2, $arg3)
{
return 'Method D';
}
private function methodE($arg1, $arg2, $arg3)
{
return 'Method E';
}
}Methods are matched in the order they are specified when you call overload.
I'm still just hacking around with this and there's probably a bunch of things I'm missing.
For example, it just occurred to me that I haven't really considered how the reflection-based detection stuff should handle optional arguments, and off the top of my head I don't even know what it should do ¯\(ツ)/¯
Either way, I think it's some pretty fun code and I thought it was pretty cool that we could even come up with an API for it at all.
Are you making Elixir in PHP now? ⚔️