Add fluent Numberable class (Number equivalent of Stringable)

[Tresor-Kasenda]

Summary

I'd like to propose adding a Numberable class as a fluent wrapper for Number, similar to how Stringable wraps Str.

Motivation

Currently, Str has a fluent counterpart Stringable that enables method chaining:

// Static
Str::upper(Str::trim(' hello '));

// Fluent (much cleaner)
str(' hello ')->trim()->upper();

However, Number has no equivalent. Complex number formatting requires nested calls or temporary variables:

// Current approach - nested calls (hard to read)
Number::currency(Number::clamp($price, 0, 1000), 'EUR');

// Current approach - temporary variables
$clamped = Number::clamp($price, 0, 1000);
$formatted = Number::currency($clamped, 'EUR');

Proposed API

// New fluent approach with num() helper
num(1234.567)->clamp(0, 1000)->currency('EUR');

// Mathematical operations
num(100)
    ->multiply(1.2)
    ->add(50)
    ->clamp(0, 150)
    ->currency('USD');

// With Conditionable trait
num($bytes)
    ->when($bytes > 1024, fn($n) => $n->divide(1024))
    ->fileSize();

Proposed Implementation

A Numberable class with:

Chainable methods (return static)

• clamp(), trim()
• add(), subtract(), multiply(), divide()

Terminal methods (return string)

• format(), currency(), percentage()
• spell(), ordinal(), spellOrdinal()
• fileSize(), abbreviate(), forHumans()

Traits

• Conditionable, Dumpable, Macroable, Tappable

Helper function

function num(int|float $value): Numberable

Questions for the community

1. Is this something that would be useful in your projects?
2. Should mathematical operations (add, multiply, etc.) be included, or keep it simple as a formatting wrapper only?
3. Any concerns about the num() helper name conflicting with existing code?

Alternatives considered

• Do nothing: Users can create their own wrapper if needed
• Add fluent methods directly to Number: Would break the static nature of the class
• Use a pipeline: $result = Pipeline::of($number)->through([...])->then(...) — more verbose

---

I'm happy to submit a PR if there's interest in this feature. Looking forward to hearing your thoughts!

[shaedrich]

That would be awesome! In fact, I also already thought about that 👍🏻

You forgot a group of methods: Static constructors

• parse()
• parseInt()
• parseFloat()

There are more terminal methods:

• pairs()

Furthermore, we could have fluent setters for formatters (probably rather __toString()) and such

• formatAs() ('currency'|'percentage'|'spell'|'ordinal'|'spellOrdinal'|'abbreviated'|'summarized'|'fileSize'|'humanReadable')
• withers (withLocale(), withCurrency())
• other arguments (precision, maxPrecision, others)

[Tresor-Kasenda]

Thank you for the feedback!

I'll add the missing static constructors (parse(), parseInt(), parseFloat()) as well as terminal methods like pairs().
Great suggestion for fluent setters/formatters too (formatAs(), withLocale(), withCurrency(), etc.) and for supporting additional arguments (precision, maxPrecision, etc.) — I’ll integrate these or propose a more complete API.

Let me know if you have any specific expectations for method signatures or further suggestions!

[shaedrich]

Thanks a lot! I will.

We could also probably add a round() chainable method.

The Str helper has several when() shortcuts:

• whenContains()
• whenContainsAll()
• whenDoesntEndWith()
• whenDoesntStartWith()
• whenEmpty()
• whenNotEmpty()
• whenStartsWith()
• whenEndsWith()
• whenExactly()
• whenNotExactly()
• whenIs()
• whenIsAscii()
• whenIsUlid()
• whenIsUuid()
• whenTest()

Maybe, Numberable could also have some:

• whenGreaterThan()
• whenEquals()
• whenLowerThan()
• whenGreaterThanOrEqual()
• whenLowerThanOrEqual()
• whenPositive()
• whenNegative()
• whenInteger()
• whenFloat()
• whenMultipleOf()
• whenPrime()
• etc.

[Tresor-Kasenda]

Thanks a lot for the suggestions — really appreciated.

round() is already chainable on Numberable (all math methods return a new Numberable), and now supports explicit rounding modes too.

I also like the when... shortcut idea. Since Numberable already uses Conditionable, we already have flexible when() / unless() support with predicates, for example:

$number->when(fn ($n) => $n->isPositive(), fn ($n) => $n->multiply(2));

To keep the API focused, I’d prefer starting with predicate methods (isPositive, isNegative, isInt, isFloat, isMultipleOf, maybe isPrime) and only adding dedicated whenX() helpers where there is clear ergonomic value.

[Tresor-Kasenda]

@shaedrich i release the package there is the link https://github.com/Tresor-Kasenda/laravel-numberable