When/WhenNot methods for db in a trait

[lonnieezell]

This replaces #6329. It adds a new ConditionalTrait to CodeIgniter that can be used to add when() and whenNot() methods in various places in the framework. This PR adds it to the database layer for inline conditions to queries.

Instead of:

$query = $this->where('foo', $foo);

if ($bar) {
    $query = $query->where('bar', $bar);
}

return $query->findAll();

you can now do:

return $query->where('foo', $foo)
    ->when($bar, static function($query) {
        return $query->where('bar', $bar);
    })
    ->findAll();

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[iRedds]

What do you think of this kind of code?

function when ($when, callable $true, ?callable $false = null)
{
	($when ? $true : $false ?? function(){})($this, $when);
}

function whenNot ($when, callable $true, ?callable $false = null)
{
	when($when, $false ?? function(){}, $true);
}

[MGatner]

I like this change! Good suggestion from @iRedds. A agree with @kenjis' tweaks but otherwise approve.

[MGatner]

What do you think of this kind of code?

@iRedds I like the efficiency but I had to read it like five times to figure it out; I think @lonnieezell's version is much easier to understand without galaxy brain 😉

I do like whenNot() simply being an inversion of when() instead of a repeat of the code - less to break in future changes. That would be a good change to apply here.

[kenjis]

@iRedds To be honest, the code is difficult to understand.

Code should be written to minimize the time it would take for someone else to understand it.

[MGatner]

I follow @iRedds suggestion to make this one method with its inversion.

[paulbalandan]

whenNot as the inverse of when seems quite not natural for me. It's a bit off. How about other antonyms of when:

• except
• unless
• if not
• lest

[lonnieezell]

The method expects the condition to evaluate to false, which makes except and unless not make semantic sense. ifNot as an opposite of when feels wrong also. lest feels like the condition should evaluate to true to me, also.

whenNot does at least match the pattern of other methods like where/whereNot. I'm open to suggestions but I'm not sure any of these fit, unless we change the whole method to suit the name.

[paulbalandan]

except/unless makes sense to me if the statement is read in a specific way. In the context of the DB builder, since I know the usage of when then when I read its inverse (except/unless):

$builder = $this->db->table('users');
$user = model('Users')->find(1);

return $builder->except($user, fn ($query) { /* some code */ })->get();

In this example, I would read the code as "Except when $user is truthy (or a found user record), let the $builder execute the callable then get the DB result."

[kenjis]

whenNot is easy to understand for non native English speakers.
It is logical. The when whenNot pair is easy to remember, because we already have where/whereNot.

except is difficult to imagine as the opposite of when.

There is a conflict.

[lonnieezell]

@MGatner are we ok to merge this one?

[MGatner]

@lonnieezell It needs to be switched to 4.3. You can try this:

git rebase --onto develop 4.3 when-trait

Just be ready to git rebase --abort if things go poorly 😅 and cherry-pick into a new branch.

I think the content is all good, though I do think @paulbalandan 's suggestion is good. Maybe he would add it as an actual GitHub suggested change?

[lonnieezell]

@MGatner It's already on 4.3 so we're good there. Just committed @paulbalandan suggestion.

[MGatner]

Looks good to me! Last comment is the negative name; I don't have a strong feeling either way.

[kenjis]

Can you remove the merge commit 49f1e70 ?
We don't need merge commits in PR branches.

[kenjis]

There is a coding style error.
https://github.com/codeigniter4/CodeIgniter4/actions/runs/3144200239/jobs/5109891442

[lonnieezell]

Can you remove the merge commit 49f1e70 ?

I think the likelihood of me messing something up trying to do that is pretty high, honestly. Seems we just squash and merge and the history is nice and clean that way, won't it be?

[kenjis]

Okay, I rebased and force-pushed.

[MGatner]

Hurrah!

[datamweb]

Finally, good result, thank you all.😍

[MGatner]

🥳