Are the utf8_* functions part of joomla-framework/string's API?

[nibra]

In PR #38, @mbabker stated:

like it or not the third party API has become a de facto part of this package's API and must be treated as first-party code regarding backward (and forward) compatibility; I'm sure few will remember this, but inclusions of the phputf8 files for extensions were broken in the CMS 3.4 release because the old files were removed, hence those file paths being restored as proxies for backward compatibility

If that is true, replacing the phputf8 library does not really make sense, we'd rather absorb it, since it has been abandoned a long time ago.

Please add your 2 cents, the pros and cons from your perspective, so we can come to an educated decision.

[mbabker]

It can be replaced, I would encourage replacing it. But, flat out removing it in a minor version would be a hard B/C break.

You can rewrite the StringHelper class to not use any of the phputf8 source, but you need to keep distributing it until the next major version comes.

A little back story. Not all of the phputf8 library is actually covered through methods on the StringHelper class, and in those cases, consumers of this package (primarily CMS extension developers) may be directly including and using those functions. Which is why when the CMS was upgraded to a version of this package which added the "core" phputf8 library files to the autoload list, joomla/joomla-cms#9731 was submitted to not break include or require statements for the library in either the core CMS or for extension developers.

Removing the phputf8 library is definitely not be a B/C break in the sense that the public API of anything in the Joomla\String namespace has had a behavior change, but it is a practical B/C break in the sense that code which this package provides (which is essentially unavailable any other way through either the Composer ecosystem or in the CMS installation) has been removed.

Note, this situation is different than other scenarios where a dependency is removed from the require section of the Composer manifest and a downstream consumer upgrades their application and hits an error because of a missing class. In that case, the consumer has incorrect dependencies declared and is relying on transient dependencies for their application to function correctly and the "bug" can be fixed with an appropriate composer require command. Since this package is the provider of the library, the only fix for a downstream consumer is to pin to a version that provided the library or to find the pre-Composer downloads (if they're still available) then re-apply any patches which have been applied to the library over the years (none of those were behavioral changes, they just dealt with deprecations in PHP).

[nibra]

You can rewrite the StringHelper class to not use any of the phputf8 source, but you need to keep distributing it until the next major version comes.

Makes sense to me. Thank you for your thoughts!