[12.x] Add whenJson/whenNotJson methods

[tomirons]

I find the when/not when methods very readable and needed something similar for JSON strings. Hence a PR to support it!

Before:

$stringable = str();

if ($stringable->isJson()) {
    // do something...
} else {
    // do something else
}

After

str()->whenJson(function () {
    // do something...
}, function () {
    // do something else
})

[AndrewMast]

To allow for the higher order functions that the when method is capable of, I suggest changing this to:

return $this->when($this->isJson(), ...func_get_args());

This allows the func_num_args() call in when to properly pick up $callback or $default being used.

[tomirons]

Sorry, I'm not quite following what you're trying to say. The method parameters and parameters passed to the when function are the same as whenEmpty and whenNotEmpty.

[AndrewMast]

Nevermind. I didn't realize the rest of Stringable is doing the same as you suggested...

[AndrewMast]

@tomirons Considering the rest of the Stringable class, you should discard what I was saying. But to clarify what I meant:

When only one method is provided to the when (the condition, in this case, $this->isJson()), a HigherOrderWhenProxy instance is returned. This allows for method calls such as $conditionableObject->when(true)->prepend('key.')->unless(false)->append('.key'); or something like that. It also allows for $object->when()->methodThatReturnsTrue()->doThis(); (also with properties).

When doing $this->when($this->isJson(), $callback, $default);, it forces 3 arguments no matter what, even if nothing is provided for $default in whenJson. So this would mean that when would never be able to be a higher order method in this case. But also considering the $callback method is required, it's best to keep it as-is.

[rodrigopedra]

You can already do this:

$stringable->when(fn ($s) => $s->isJson(), function () {
    // do something...
}, function () {
    // do something else
});

Otherwise, why not propose the addition of also:

• whenAscii() from Stringable@isAscii()
• whenUrl() from Stringable@isUrl()
• whenUuid() from Stringable@isUuid()
• whenUlid() from Stringable@isUlid()
• whenEmpty() from Stringable@isEmpty()
• whenNotEmpty() from Stringable@isNotEmpty()
• whenMatch() from Stringable@isMatch()

I actually have a Str::whenUuid() macro in a project using event sourcing in models with auto-increment IDs, but that are UUID routable.

[AndrewMast]

@rodrigopedra We already have many of those for the Stringable class:

• whenContains
• whenContainsAll
• whenEmpty
• whenNotEmpty
• whenEndsWith
• whenExactly
• whenNotExactly
• whenIs
• whenIsAscii
• whenIsUuid
• whenIsUlid
• whenStartsWith
• whenTest

[rodrigopedra]

@AndrewMast didn't know about those.

Thanks for the heads up.

So probably the macro I got isn't even being called 😅

Might be a left over from before it was added.

[rodrigopedra]

Actually just checked and it is called, as my macro is named whenUuid.

As I added to my last comment must be a left over from before whenIsUuid was added, or even an oversight.

Refactoring already, thanks again @AndrewMast for the heads-up!

[taylorotwell]

Thanks for your pull request to Laravel!

Unfortunately, I'm going to delay merging this code for now. To preserve our ability to adequately maintain the framework, we need to be very careful regarding the amount of code we include.

If applicable, please consider releasing your code as a package so that the community can still take advantage of your contributions!