Skip to content

Intl: Add a new IntlListFormatter class #18519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

BogdanUngureanu
Copy link
Contributor

This PR adds support for ICU's ListFormatter implementation by implementing a new IntlListFormatter class in PHP.

The class supports ANDs, ORs and UNIT format types. However, they are only available if ICU version is 67 or above. On older versions of ICU, we only allow TYPE_AND and WIDTH_WIDE - we need this because, from what I've understood, the minimum version ICU supported is 57, which was bumped from 50 last year.

The class API is pretty simple:

$formatter = new IntlListFormatter('EN_US', IntlListFormatter::TYPE_AND, IntlListFormatter::WIDTH_WIDE);
echo $formatter->format([1,2,3]);

will display

1, 2, and 3

I have some questions here:

  • Do I need to create an RFC for this new addition?
  • I haven't used a namespace and used Intl prefix for consistency sake. Should it be behind a Intl namespace? I haven't seen a class that uses it so I thought I should go with the prefix.

@TimWolla
Copy link
Member

TimWolla commented May 8, 2025

Do I need to create an RFC for this new addition?

I wouldn't need an RFC if this is a straight forward addition to the existing Intl API which just maps to ICU in a straight forward fashion. I would like to see some smaller improvements, though:

  • Making the class final and /** @not-serializable */. This allows you to avoid the “not properly constructed” checks.
  • /** @strict-properties */ to further lock down the class against misuse.

I haven't used a namespace and used Intl prefix for consistency sake. Should it be behind a Intl namespace? I haven't seen a class that uses it so I thought I should go with the prefix.

The prefix makes sense to me. Using the Intl namespace should properly happen when designing an Intl API that isn't just a straight forward mapping to ICU, but also provides a nice API (e.g. enums, proper class and exception hierarchy, …).

@BogdanUngureanu
Copy link
Contributor Author

Hi @TimWolla! Thanks for the suggestions - great ideas! I've pushed a commit that makes the class final and enabled those flags.

Copy link
Member

@TimWolla TimWolla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some more Stub nits. Please do not add PHPDoc comments, unless they allow you to express something that the types themselves cannot.

@BogdanUngureanu
Copy link
Contributor Author

Some more Stub nits. Please do not add PHPDoc comments, unless they allow you to express something that the types themselves cannot.

Thanks for the quick response! I'll make the changes tomorrow. :)

@devnexen
Copy link
Member

devnexen commented May 8, 2025

windows CI failure is related otherwise

@BogdanUngureanu BogdanUngureanu requested a review from devnexen May 10, 2025 22:46
intl_convert_utf8_to_utf16(&ustr, &ustr_len, ZSTR_VAL(str_val), ZSTR_LEN(str_val), &status);
if (U_FAILURE(status)) {
for (uint32_t j = 0; j < i; j++) {
efree((void *)items[j]);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: do you get a warning during your build if you remove the (void *) cast ? unsure it s really necessary.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep, I get a warning:

/listformatter_class.c:158:17: warning: passing 'const UChar *' (aka 'const unsigned short *') to parameter of type 'void *' discards qualifiers [-Wincompatible-pointer-types-discards-qualifiers]

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the const qualifier ... can items just be mutable and eventually doing the cast at ulistfmt_format ?

$formatter = new IntlListFormatter('ro', IntlListFormatter::TYPE_AND, IntlListFormatter::WIDTH_WIDE);

try {
echo $formatter->format([new stdClass()]);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice but would like to see more tests, e.g. an array with a NULL somewhere ... what happens if values are references ? etc..

@devnexen
Copy link
Member

As first round of reviews, look good, I ll play a bit with your branch I think tomorrow.

resultLength = ulistfmt_format(LISTFORMATTER_OBJECT(obj), items, itemLengths, count, NULL, 0, &status);

if (U_FAILURE(status) && status != U_BUFFER_OVERFLOW_ERROR) {
intl_error_set(NULL, status, "Failed to format list", 0);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to deal with resources leaks here, might be possible to create a goto label to avoid code repetitions.

@devnexen
Copy link
Member

devnexen commented May 11, 2025

As first round of reviews, look good, I ll play a bit with your branch I think tomorrow.

So I locally tested, changing unit tests ; looking ok so far. Once all remarks had been addressed, I ll let it rest a bit and come back to it later.

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

Successfully merging this pull request may close these issues.

3 participants