CoolCMS API

Used only by line entities with a non-integer quantity (work hours, meters, kilograms): InvoiceItem and InvoiceTemplateItem. Gifts, shipping and payment methods have piece quantities and stay int.

Contract:

• The getter returns a numeric string, like the monetary $price, because DBAL decimal never returns a float. The consumer casts itself ((float) $line->getQuantity()); abs() and intdiv() reject a string and fail with a TypeError under strict_types=1.
• The setter takes int|float|string, so every existing writer keeps working.
• The value is normalized to a fixed two-decimal form ('2.50', '2.00'). The database returns '2.00' after the column change, so a rewrite with the same value is not marked as changed by Doctrine change tracking.
• Rounding is half-up to 2 places, the same as MySQL does when storing into decimal(8,2). Otherwise the calculator would work with a finer number than the database holds and a reloaded invoice would give a different total.
• Non-numeric input gives '0.00'; null, '' or 'abc' must not reach the multiplication by price.
• The range is not clipped: decimal(8,2) holds at most 999999.99, but silent clamping would make the entity claim a different number than the database. The caller validates the range (see InvoiceComposer); the setter must not throw during form hydration instead of a validation message.

IMPORTANT: deploy the code before alter table ... modify quantity decimal(8,2). In that window a decimal quantity must not be entered; the server-side guard DecimalQuantityGuardTrait in beforeSave of both Api managers enforces it (invoice and template): a non-integer quantity over the still int column fails with VALIDATION_FAILED and the write is rolled back. The database does not reliably reject it (depending on sql_mode it may store '2.50' as 3 without any error), and because totals are recomputed from the stored quantity on every save, the invoice would silently grow. Integer quantities pass unchanged and the guard turns itself off after the column change.