feat: Add incrementMany() and decrementMany() methods to BaseBuilder and other driver specific builders

[patel-vansh]

Description
This PR adds two new functions in BaseBuilder.php — incrementMany() and decrementMany(). These two functions enable devs to increment/decrement multiple rows at once atomically.

Also, the increment() and decrement() methods now internally call incrementMany() and decrementMany() respectively to prevent duplicating the logic.

Checklist:

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

[paulbalandan]

Have you considered adding a separate incrementAll (or other wording) that will take care of the array, so to minimize the BC break?

PS. The random test failure seems legitimate. I'll deal with that later.

[michalsn]

I also think that incrementMany() or incrementAll() would probably work better.

[patel-vansh]

Yeah, that would avoid BC. I guess incrementAll would be the new method.

Maybe the current increment method calls incrementAll internally? So, there's no duplication of any logic.
@paulbalandan and @michalsn

[michalsn]

Maybe the current increment method calls incrementAll internally? So, there's no duplication of any logic.

I see why not.

[patel-vansh]

Not sure why PHPStan analysis have failed.

[paulbalandan]

You apparently fixed (or renamed) the affected code. Just run composer phpstan:baseline to update the baseline.

[michalsn]

Supporting a more convenient API would be nice:

incrementAll(['one', 'two'], 2)
incrementAll(['one' => 2, 'two' => 3])

What do you think?

Something like:

public function incrementAll(array $columns, int $value = 1): bool
{
    $fields = [];

    if (array_is_list($columns)) {
        foreach ($columns as $column) {
            $column          = $this->db->protectIdentifiers($column);
            $fields[$column] = "{$column} + {$value}";
        }
    } else {
        foreach ($columns as $column => $value) {
            if (! is_int($value)) {
                throw new TypeError(...);
            }

            $column          = $this->db->protectIdentifiers($column);
            $fields[$column] = "{$column} + {$value}";
        }
    }
    
    // ...
}

[patel-vansh]

incrementEach() is also an option.

[patel-vansh]

I chose incrementAll() over any other as it kind of refers to an All or nothing DB operation. And since it's a single SQL query, it is an All or Nothing operation.

incrementEach() is an option but I think it's the least bottom in the names, as this might refer to some sort of foreach loop.

incrementMany() is an interesting option too.

[neznaika0]

You have removed the public methods for SQLSRV and Postgre. I think it needs to be displayed in the BC section. I can't write a suggestion well, let them correct me.
The Postgre::increment() method ... has been removed. Added new incrementMany() instead.

[michalsn]

increment() and decrement() are still public through inheritance from BaseBuilder. People overriding those methods in their own subclass can still do so. People calling parent::increment() from a subclass still get working behavior.

[neznaika0]

You forgot to test negative values. The is_int() check will work correctly and the data will be changed incorrectly: field + -1. It is necessary to prohibit these values.

The comment applies to all new methods

[patel-vansh]

Actually, negative values were allowed in earlier behaviour. increment() method allowed negative values which would actually subtract from the field instead of adding. So, I tried to retain that behaviour. If everyone agrees to change that, I would happily change this to disallow negative values in both incrementMany() and decrementMany() method

[michalsn]

I see no problem with allowing negative values. This may be an actively used feature.

[patel-vansh]

I was looking at the PostgreSQL Builder's failing test cases and found that the current implementation (to_number({$col}, '9999999') + {$val}) was only working for string based columns who wanted to increment numeric values. But native numeric columns will throw errors.

So, here's my suggestion. Instead of "to_number({$col}, '9999999') + {$val}", we use "{$col}::numeric + {$val}" or "CAST({$col} AS numeric) + {$val}" and it will work with both types of columns and AFAIK, it won't be a BC.

[michalsn]

"CAST({$col} AS numeric) + {$val}"

sounds reasonable to me. I do not see BC break here.