# symfony/polyfill-intl-grapheme for Portable PHP Text Handling

> symfony/polyfill-intl-grapheme supplies ten PHP grapheme functions when the native Intl extension is unavailable. It is aimed at PHP applications that need grapheme-aware UTF-8 string operations without relying on that extension.

**symfony/polyfill-intl-grapheme** — Symfony polyfill for intl's grapheme_* functions

- Repository: https://github.com/symfony/polyfill-intl-grapheme
- Website: https://symfony.com/polyfill-intl-grapheme
- Stars: 1,727 · Forks: 5
- Language: PHP
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/symfony-polyfill-intl-grapheme

## The Missing Intl Operations in symfony/polyfill-intl-grapheme

symfony/polyfill-intl-grapheme addresses a specific portability gap in PHP text handling. PHP's Intl extension provides grapheme functions, but an application cannot assume that this extension exists on every runtime it supports. This package supplies a partial, native PHP implementation of ten functions from PHP's Intl API, allowing application code to call the documented interfaces when the extension is absent.

The intended users are PHP developers building libraries or applications that need grapheme-aware behavior across different deployment environments. A grapheme is a user-perceived character rather than a single byte or Unicode code point. That distinction matters for strings containing emoji sequences, combining characters, and related scripts, where basic string operations can produce counts or boundaries that differ from what a reader perceives.

The project is not a general internationalization package. Its repository is named `intl-grapheme`, and its documented scope is the `grapheme_*` function family. It does not claim to reproduce every capability of the native Intl extension. The README calls the implementation "partial," which defines a significant adoption boundary: installing this package does not make the complete Intl extension available.

## UTF-8 Grapheme Operations in the 1.x Package

The documented API covers counting, searching, slicing, splitting, and extraction in grapheme units. `grapheme_strlen` returns the length of a string in graphemes. `grapheme_substr` returns part of a string, while `grapheme_str_split` splits a string into an array of individual graphemes or chunks of graphemes. These operations give callers a consistent unit when byte length does not match the text structure the application intends to handle.

The search functions cover both directions and both matching modes. `grapheme_strpos` and `grapheme_strrpos` find the first and last case-sensitive occurrences. `grapheme_stripos` and `grapheme_strripos` provide the corresponding case-insensitive searches. `grapheme_strstr` returns the part of the haystack from the first case-sensitive occurrence of the needle through the end, while `grapheme_stristr` returns the case-insensitive equivalent.

For bounded selection, `grapheme_extract` extracts a sequence of grapheme clusters from a text buffer. The README states that this buffer must be encoded in UTF-8. Because the package documents only these ten functions, developers must check the list before changing runtime requirements. Installing it does not guarantee coverage for an unlisted `grapheme_*` operation or for another Intl feature.

## Repository Layout and Native PHP Bootstrap Files

Based on the repository layout, this is a compact PHP library rather than a service or command-line application. Its principal implementation file is `Grapheme.php`. The repository also contains `bootstrap.php`, `bootstrap80.php`, and `bootstrap85.php`, followed by `composer.json`, `README.md`, and `LICENSE`. This file set points to a Composer-distributed package with separate bootstrap variants for PHP compatibility contexts.

There is no documented server process, database, network endpoint, or background worker. Calls enter PHP as ordinary function calls. When PHP can resolve the functions through Intl, the native extension supplies them. Where it cannot, the package provides a PHP implementation intended to expose the supported function names through its Composer integration. The README specifically describes the implementation as native PHP, rather than as a wrapper around another operating-system service.

The repository does not present an application-level configuration file. Its integration surface consists of Composer metadata, bootstrap files, and the functions implemented for callers. This also means the package is not a tool for configuring locale data, collation, currency formatting, time zones, or the wider set of facilities associated with the Intl extension. Its intended role is narrower.

## Installing and Preparing symfony/polyfill-intl-grapheme

The project README does not provide a standalone installation command or a complete dependency declaration that can be reproduced from the repository documentation. Instead, it directs readers to Symfony's main Polyfill README for more information. Installation should therefore begin there and follow the dependency configuration of the host PHP project.

The package is identified as `symfony/polyfill-intl-grapheme`, and its repository includes `composer.json`. The main Symfony Polyfill README is the documented source for broader installation guidance.

For a first use, select one of the ten documented functions and exercise it with a known UTF-8 string. `grapheme_strlen` is the most direct entry point for checking grapheme-count behavior. A useful acceptance test should contain text where byte count, code-point count, and grapheme count could differ. The expected result should come from the PHP API contract, not from an output claim made by this review.

After installation, confirm that the application's normal dependency-loading process exposes the function before relying on it in production. No executable PHP example can be copied because the repository README does not contain one. Adding an unverified code sample would risk claiming unsupported setup behavior or syntax.

## UTF-8 and API Boundaries for Grapheme Processing

The main limitation is explicit: this is a partial implementation, not a full clone of PHP's Intl extension. Applications using locales, collations, iterators, formatters, calendars, number formatting, or other Intl facilities should not assume those services are available through this package. Only the functions listed in the README belong to the documented contract.

The documented extraction operation also establishes an encoding constraint. The text buffer passed to `grapheme_extract` must be encoded in UTF-8. UTF-8 inputs are also central to the other listed grapheme operations because they count, find, split, or return portions of text in grapheme units. Data from legacy storage or an upstream service should not be treated as UTF-8 unless its encoding has already been established.

This package is the wrong choice when grapheme segmentation is unnecessary. Native PHP string operations may be sufficient for ASCII identifiers, fixed protocol fields, or data whose length is deliberately measured in bytes. Adding this dependency introduces behavior and a compatibility contract that the application may not need.

Another boundary concerns expectations around PHP's Intl API. A developer may know the extension by name and assume that a Symfony polyfill with `intl-grapheme` in its name supplies all of Intl. The repository contradicts that assumption. Its implementation and documentation focus on ten grapheme operations, so broader Intl requirements need a different source.

## Native Intl, mbstring, and the Grapheme Polyfill

Native Intl is the direct alternative because the documented functions belong to that extension. Its approach is to provide `grapheme_*` functions through a compiled PHP extension. symfony/polyfill-intl-grapheme instead uses a native PHP implementation distributed as a Symfony polyfill, which addresses PHP environments where the Intl extension is unavailable.

The difference is not simply that both approaches process strings. Native Intl installs the upstream extension, while this package supplies a PHP-level implementation for the subset documented by its README. The resulting function surface is narrower. An application that needs only the listed grapheme operations can retain those calls and gain a portability path. An application that relies on other Intl components still needs those components from elsewhere.

For this specific compatibility need, symfony/polyfill-intl-grapheme is the closer option because its documented purpose is to implement the same selected function names in PHP. Its limitation remains equally clear: availability of these ten functions does not establish parity with all native Intl behavior.

## Maintenance, Releases, and MIT Upgrade Cost

The repository is not archived, and its last push was on 2026-10-15. Recent releases include `v1.43.0` on 2026-09-30, `v1.41.0` on 2026-07-28, and `v1.38.1` on 2026-05-26. These facts show recent activity on the default `1.x` branch, but they do not by themselves establish compatibility with every future PHP version or Intl configuration.

Dependency management and upgrade cost depend on how the host project consumes Composer packages. Because no migration script or configuration conversion is documented, the README does not support claiming that upgrades are always automatic or free of behavioral impact. A team should examine its own UTF-8 test data for changes in grapheme counts, match positions, substrings, split results, and extraction boundaries.

The documented code surface is small, but text-boundary behavior can affect application logic that derives display limits, search offsets, or character-based input limits. Case-insensitive functions add another area to verify because their matching semantics are separate from the case-sensitive counterparts.

The project is released under the MIT license. Its terms permit use, modification, distribution, and sublicensing subject to conditions that include retaining the copyright and permission notice. This is a factual description of the stated license, not legal advice. The repository's `LICENSE` file is the controlling source for the applicable terms.

## Conclusion

Adopt this package when the application uses the listed grapheme_* functions, requires UTF-8 input, and must run in environments that may lack Intl. Do not treat it as a complete replacement for Intl, because the repository documents only ten functions and calls its implementation partial. Before adoption, verify that every required API appears in the README, that dependency loading works on each target runtime, and that tests cover emoji, combining marks, case-insensitive searches, and extraction boundaries.

## FAQ

### What does symfony/polyfill-intl-grapheme provide?

It provides a partial native PHP implementation of ten grapheme functions from PHP's Intl extension, including grapheme counting, searching, slicing, splitting, and extraction.

### Does symfony/polyfill-intl-grapheme replace the entire Intl extension?

No. The README describes it as partial and lists only ten supported functions. Other Intl features are outside the documented scope of this repository.

### What text encoding does symfony/polyfill-intl-grapheme require?

The README specifically states that the text buffer passed to `grapheme_extract` must be encoded in UTF-8. Its grapheme operations are documented in the context of UTF-8 text.

## Sources

- [License: MIT](https://github.com/symfony/polyfill-intl-grapheme/blob/1.x/LICENSE)
- [Project website](https://symfony.com/polyfill-intl-grapheme)
- [README](https://github.com/symfony/polyfill-intl-grapheme/blob/1.x/README.md)
- [Releases](https://github.com/symfony/polyfill-intl-grapheme/releases)
- [symfony/polyfill-intl-grapheme on GitHub](https://github.com/symfony/polyfill-intl-grapheme)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/symfony-polyfill-intl-grapheme