Skip to content

Add support for Money based formatters - #103

Closed
mklepaczewski wants to merge 4 commits into
brick:masterfrom
mklepaczewski:feat/money-formatter
Closed

mklepaczewski wants to merge 4 commits into
brick:masterfrom
mklepaczewski:feat/money-formatter

Conversation

@mklepaczewski

Copy link
Copy Markdown
Contributor

Description

This PR extends Money::formatWith() to support custom formatters by broadening its signature:

...
public function formatWith(NumberFormatter|MoneyFormatter $formatter): string
...

This change uses union types introduced in PHP 8.0. The project requires PHP 8.1.

A new MoneyFormatter interface is introduced, but this PR does not include any concrete implementations. A simple anonymous implementation is used in the test suite to demonstrate usage.

interface MoneyFormatter {
    public function format(Money $money): string;
}

Problem this PR solves

  • NumberFormatter only accepts float, which can lead to loss of precision (it's acknowleded here https://github.com/brick/money#formatting). The new MoneyFormatter interface accepts a Money object directly, giving the formatter full control and avoiding conversion issues.
  • At present, developers must extend NumberFormatter to customize formatting, which is cumbersome since that class handles far more than just currency formatting. MoneyFormatter has only a single purpose and one method.

Backward compatibility

This change is backward-compatible:

  • Existing code calling Money::formatWith() with a NumberFormatter instance will continue to work unchanged.
  • Money is declared final, so it cannot be subclassed - meaning no signature conflicts can occur.
  • union types were introduced in PHP 8.0, and the project requires PHP 8.1

@BenMorel

Copy link
Copy Markdown
Member

Hi, I think that adding a MoneyFormatter interface is a sound idea. It uniformizes potential implementations of money formatters in the wild under a common API.

However, I'm a bit hesistant about adding it to the signature of formatWith(): sure, it doesn't hurt, and it's not a BC break. But what value does it bring to call $money->format($formatter) vs $formatter->format($money)?

@mklepaczewski

mklepaczewski commented Nov 13, 2025 •

Copy link
Copy Markdown
Contributor Author

However, I'm a bit hesistant about adding it to the signature of formatWith(): sure, it doesn't hurt, and it's not a BC break. But what value does it bring to call $money->format($formatter) vs $formatter->format($money)?

Good question! Also, thank you for all the work on the project.

We already have Money::formatWith(NumberFormatter $formatter) as the method for formatting Money. Introducing MoneyFormatter without integrating it into Money::formatWith() would lead to two different code patterns ($amount->formatWith() vs $formatter->format($amount)), which could confuse new users about which one to use. If someone asks, "How do I format Money?", it's easier to point them to Money::formatWith().

Moreover, when a developer wants to switch to custom formatting using MoneyFormatter, the number of required code changes should be minimal - especially when using dependency injection. Compare:

/* $formatter is MoneyFormatter or NumberFormatter *
$logger->info("Processing transaction", [ $amount->formatWith( $formatter) ]);

vs

/* $formatter is NumberFormatter */
$logger->info("Processing transaction", [ $amount->formatWith( $formatter) ]);
/* But if we decide to use MoneyFormatter we need to change more than just the argument */
$logger->info("Processing transaction", [ $formatter->format($amount) ]);

@BenMorel

BenMorel commented Nov 13, 2025 •

Copy link
Copy Markdown
Member

I think the main takeaway is that it indeed doesn't hurt.

While I'm not opposed to your PR as it is, I'd like to also explore another idea:

  • introduce the MoneyFormatter interface as you suggested it
  • add a MoneyNumberFormatter implementation that takes (NumberFormatter $numberFormatter) in the constructor, and move the formatWith() code there
  • add a MoneyLocaleFormatter implementation that takes (string $locale, bool $allowWholeNumber) in the constructor, and move the formatTo() code there
  • get rid of formatWith() altogether
  • change formatTo() to delegate to new MoneyLocaleFormatter($locale, allowWholeNumber)->format($this);

This way, we delegate all formatting concerns to other classes, and only keep the utility function formatTo(), as it's a very common operation and nice QoL improvement vs dealing with the formatter manually.

What do you think?

@mklepaczewski

Copy link
Copy Markdown
Contributor Author

Yes to all. I’ll work on it in a day or two.

However, I’d like to avoid breaking changes since we plan to use this feature in our project (and you might decide to bump the PHP version with this change, which would prevent us from using the PR for a while).

So, I propose we do everything you suggested, except for any changes to formatWith(). Removing the methhod would be a breaking change, and extending it to support MoneyFormatter doesn’t make sense if the method is going to be removed in the next major release. We could mark it as deprecated instead.

@BenMorel

Copy link
Copy Markdown
Member

OK for marking formatWith() as deprecated! 👍

@mklepaczewski

Copy link
Copy Markdown
Contributor Author

Replaced by #105

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants