Ustring Laravel Package

Technical Evaluation

What it is. hoa/ustring is the Unicode string component of the Hoa project: an object-oriented Ustring class (ArrayAccess, Countable, IteratorAggregate) providing grapheme-cluster-aware charAt, substring, split, toLowerCase, padding, transliteration, and a Search helper. It pulls in hoa/consistency and hoa/exception, and depends on ext-mbstring/ext-iconv for encoding work.

Architecture fit. Poor for anything we would build today. The library predates and is superseded by two things already present in a Laravel codebase: Illuminate\Support\Str / Str::of() (a fluent Stringable API that mirrors the Ustring ergonomics most teams actually adopted it for) and symfony/string (AbstractString, UnicodeString, Slugger), which is a first-party Symfony component with active maintenance and native PHP 8 support. Adopting hoa/ustring would add a parallel, unmaintained string abstraction alongside two supported ones — a net increase in surface area for zero functional gain.

Integration feasibility. Mechanically possible in a legacy context, commercially unattractive in any context:

• Distribution risk: repository is archived (read-only), last tag 2017-01-16, 399 stars, 0 dependents. There is no upstream to receive fixes, no issue tracker, no vendor to escalate to, and no ecosystem pressure that would ever produce a community fork with momentum. The maintenance burden transfers entirely to us on day one.
• Runtime risk: the Composer manifest targets the PHP 5.5/7.x era. On a modern Laravel runtime (PHP 8.0+ required since Laravel 9) installability is at best unverified and typically blocked by platform constraints; forcing it with --ignore-platform-req=php means shipping code that has never been executed against our interpreter. Additionally, Hoa packages historically lean on Hoa\Consistency autoloading and hoa:// stream-wrapper conventions that sit awkwardly beside Composer 2 / PSR-4 expectations.
• Correctness risk: embedded Unicode property and grapheme-break tables are frozen circa 2016–2017. Emoji ZWJ sequences, flag pairs, skin-tone modifiers, and newer script/case-folding data will behave inconsistently with mbstring/intl and with whatever the frontend or database collation does. That is a silent-correctness problem, not a crash — the worst kind.
• State risk: class-level default charset configuration introduces hidden global state that leaks across tests and long-running workers.

Technical risk summary

Key questions for the owning team.

1. Is hoa/ustring actually in composer.lock, and via which direct or transitive path? (composer why hoa/ustring.)
2. Is the usage display formatting (low risk) or input validation/length limiting/identifier generation (security-relevant, because grapheme vs. byte vs. code-point length disagreements are a classic filter-bypass vector)?
3. What is the next mandatory PHP minor/major upgrade date, and does this dependency gate it?
4. Do we need grapheme-level operations at all, or would mb_* plus Str satisfy the original requirement?
5. Does anyone on staff have working knowledge of the Hoa API, or is this already orphaned knowledge?

Integration Approach

Stack fit. Treat this as negative fit and design accordingly. The target state is: symfony/string (or Str/Stringable) for all new code, intl's grapheme_* functions where true grapheme segmentation is required, and hoa/ustring permitted only inside an explicitly quarantined adapter until deleted.

Migration path.

1. Inventory. composer why hoa/ustring, then grep -rn "Hoa\\\\Ustring" across app/, packages/, and any legacy modules. Classify each call site as formatting, comparison, or validation.
2. Freeze. Pin the exact current version in composer.json and add a conflict/CI guard (Deptrac, PHPStan, or a simple PHPCS forbiddenNames rule) that fails the build on any new Hoa\ reference. Add a composer prohibits php 8.0 hoa/ustring check to the upgrade-readiness dashboard.
3. Wrap. Introduce a narrow internal contract — e.g. App\Support\Contracts\UnicodeString with length, substr, lower, upper, contains, slug — implemented first by a Hoa-backed adapter (preserving byte-for-byte current behaviour) so the wrapper is a no-op refactor and ships independently of the migration.
4. Replace behind the wrapper. Implement the same contract with symfony/string and flip the container binding. Legacy code and new code both consume the interface; only the binding changes.
5. Retire. Remove the fork, the adapter, the pinned dependency, and the CI exception.

Compatibility notes.

• Sequence the wrapper before any framework upgrade; it is the cheapest insurance against the upgrade being blocked late.
• If PHP 8 support is genuinely required before replacement is possible, fork to an internal namespace (acme/hoa-ustring) rather than relaxing platform requirements globally — this confines the "unsupported interpreter" risk to one repository we control and can patch.
• Verify mbstring function-overload settings and default_charset are consistent between the legacy Hoa path and the new one; mismatches here produce subtle truncation bugs at boundary lengths.

Effort sizing. For typical Laravel usage (slug generation, limit/words, a few charAt/substr calls) expect 2–5 engineer-days including parity tests. If the library sits inside a bulk text-processing or search-indexing pipeline, budget 10–15 days and plan a dual-run shadow period.

Operational Impact

Maintenance. Total ownership transfer. There are no upstream releases, no security advisories, and no CVE feed we can subscribe to; every future PHP, PCRE, ICU, or mbstring behaviour change is ours to diagnose and patch. Budget a recurring dependency-audit line item and an annual "replace or re-fork" review. Because the repo is archived, issue reporting is not merely slow — it does not exist.

Support. No vendor, no commercial support, no active maintainer, no community channel. Escalation path is internal only. Documentation lives on a project site with no continuity commitment; mirror the relevant API pages into our wiki now while they are still reachable. Zero dependents also means no peer organisations to share fixes or migration notes with.

Scaling. Runtime cost is negligible — pure PHP, no network hop, no service dependency. The real scaling concern is allocation: the design favours an object per string, which is inappropriate inside hot loops over large collections. Also note that Ustring instances are not safe to serialize into queued jobs or cache payloads across deploys; keep the wrapper's public surface returning native strings.

Failure modes to design against.

• Deploy-time hard failure: Composer resolution breaks on the next PHP bump and the pipeline goes red with no remedy other than emergency refactoring under time pressure. This is the dominant risk and the reason to wrap early.
• Silent correctness drift: grapheme counts diverge from the database/client's notion of length, producing truncation, rejected-then-accepted input, or off-by-one limits — potentially a validation bypass.
• Environment divergence: differing mbstring defaults or missing iconv between local, CI, and production yield different results for the same input.
• Global state leakage: default-charset mutation from one request or test contaminating others in long-running workers.
• Knowledge evaporation: no one left who can debug inside Hoa's exception/consistency stack.

Ramp-up. Low-to-negative. New engineers will not have seen this API, will not find current tutorials, and will be steered by every modern reference toward Str/symfony/string. Onboarding cost is therefore mostly rework cost — the wrapper contract is what keeps that bounded, since new hires can be told "use the interface, ignore the implementation" and never need to learn Hoa at all. Hiring signal is mildly negative if the dependency appears prominently in the stack.

Recommendation. Do not adopt for new work. Where it already exists, treat it as a contained legacy liability: wrap, replace with symfony/string/Str, and remove within one planning cycle — with the wrapper prioritised ahead of any PHP or Laravel upgrade.