[dereuromark]

The remaining 2.0 behavior, built on one rule: the library never drops a digit unless the caller says how. A result is exact, or a rounding mode is named, or the call throws.

No silent digit loss

Call	1.x	2.0
Decimal::create('10')->divide('3', 4)	3.3333	RoundingNecessaryException
Decimal::create('10')->divide('3', 4, Decimal::ROUND_HALF_UP)	3.3333	3.3333
Decimal::create('10')->divide('4', 2)	2.50	2.50
Decimal::create('18')->sqrt()	4	RoundingNecessaryException
Decimal::create('1.5')->pow(2)	2.2	2.25
Decimal::create('19.99')->multiply('0.19', 2)	3.79	RoundingNecessaryException
Decimal::create('0.129', 2)	0.12	RoundingNecessaryException
Decimal::create('0.120', 2)	0.12	0.12

• New ROUND_UNNECESSARY mode, the default of divide(), sqrt(), average() and of the scale argument on add(), subtract(), multiply(), mod() and pow(). Dropping zeros is never an error.
• ROUND_DOWN reproduces the 1.x cut-off wherever it is wanted.
• sqrt() and pow() round in every mode.
• The $strict argument is removed, its check is always on.

Scale and string agree

Decimal::create('0.1', 4) prints 0.1000. The scale of an object is always the number of decimals in its string.

Floats

The constructor, create() and every method taking a value reject floats with an exception that points to createFromFloat().

The parameter types still list float. Without it, PHP converts a float to an integer for callers that do not declare strict types, so Decimal::create(1.5) would become 1 without any error. Keeping the type and throwing is the only way to reject it for all callers.

Exceptions

Six classes under PhpCollective\DecimalObject\Exception, all implementing DecimalException:

Exception	Extends
InvalidNumberException	\InvalidArgumentException
InvalidArgumentException	\InvalidArgumentException
RoundingNecessaryException	\RuntimeException
DivisionByZeroException	\DivisionByZeroError
NegativeNumberException	\DomainException
OverflowException	\OverflowException

bcmath's ValueError no longer surfaces from sqrt() of a negative value or a fractional pow() exponent. toInt() out of range throws OverflowException where it threw TypeError.

Native RoundingMode

Every mode argument is typed RoundingMode|int and accepts PHP 8.4's enum next to the constants:

Decimal::create('2')->divide('3', 2, \RoundingMode::HalfAwayFromZero);

The enum is matched by case name, so the class loads and works on PHP 8.2 and 8.3, where only the constants exist. Code written with the constants needs no change later. A copy of the enum in tests/stubs is scanned by PHPStan only, so the type can be analysed on those versions.

Other

• toFloat() returns the nearest float for long fractions and throws only beyond the float range. isBigDecimal() is removed.
• __serialize() / __unserialize() store the decimal string. Data serialized by 1.x is still read, including a declared scale.
• pow() exponents are limited to MAX_EXPONENT in either direction.

The class is not final and the properties stay protected.

Documentation is updated throughout, and docs/reference/upgrading.md lists every change with the 1.x and 2.0 result and what to do about it.

One note for dereuromark/cakephp-decimal: it passes database and request values straight to Decimal::create(). Any place that can hand it a float needs to go through createFromFloat() or a string before the plugin allows ^2.0.

[codecov]

Codecov Report

❌ Patch coverage is 86.66667% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.59%. Comparing base (613a622) to head (f4a3e59).
⚠️ Report is 1 commits behind head on next.

Files with missing lines	Patch %	Lines
src/Decimal.php	86.66%	18 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               next      #27      +/-   ##
============================================
- Coverage     98.00%   95.59%   -2.42%     
- Complexity      190      201      +11     
============================================
  Files             1        1              
  Lines           401      454      +53     
============================================
+ Hits            393      434      +41     
- Misses            8       20      +12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.