PHPackages soloterm/grapheme - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. soloterm/grapheme ActiveLibrary[Utility & Helpers](/categories/utility) soloterm/grapheme ================= A PHP package to measure the width of unicode strings rendered to a terminal. v1.1.1(3mo ago)79293.0kโ†“32.8%15MITPHPPHP ^8.1CI passing Since Feb 25Pushed 3mo ago2 watchersCompare [ Source](https://github.com/soloterm/grapheme)[ Packagist](https://packagist.org/packages/soloterm/grapheme)[ RSS](/packages/soloterm-grapheme/feed)WikiDiscussions main Synced 2d ago READMEChangelog (5)Dependencies (6)Versions (6)Used By (5) Grapheme ======== [](#grapheme) [![Latest Version on Packagist](https://camo.githubusercontent.com/0821618e789a12342740e55c2baee6345a542df4644669a536e15ff51982498b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736f6c6f7465726d2f6772617068656d65)](https://packagist.org/packages/soloterm/grapheme)[![Total Downloads](https://camo.githubusercontent.com/57dea55ec8f4abc70c4a6696be2df68aa6e5f8d6b74fbfa143f072b7d16b0bfe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736f6c6f7465726d2f6772617068656d65)](https://packagist.org/packages/soloterm/grapheme)[![License](https://camo.githubusercontent.com/68a2535cf6e4ceca569b3190b83bf240f22180d968cbb46f551d1ed080992a50/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f736f6c6f7465726d2f6772617068656d65)](https://packagist.org/packages/soloterm/grapheme) A highly optimized PHP library for calculating the display width of Unicode graphemes in terminal environments. Accurately determine how many columns a character will occupy in the terminal, including complex emoji, combining marks, and more. It also provides full-string and chunked grapheme segmentation so downstream renderers can share the same Unicode boundary logic. This library was built to support [Solo](https://github.com/soloterm/solo), your all-in-one Laravel command to tame local development. Why Use This Library? --------------------- [](#why-use-this-library) Building CLI applications can be challenging when it comes to handling modern Unicode text: - Emoji and CJK characters take up 2 cells in most terminals - Zero-width characters (joiners, marks, etc.) don't affect layout but can cause width calculation errors - Complex text like emoji with skin tones or flags require special handling - PHP's built-in functions don't fully address these edge cases This library solves these problems by providing an accurate, performant, and thoroughly tested way to determine the display width of any character or grapheme cluster. Installation ------------ [](#installation) ``` composer require soloterm/grapheme ``` Usage ----- [](#usage) ``` use SoloTerm\Grapheme\Grapheme; // Basic characters (width: 1) Grapheme::wcwidth('a'); // Returns: 1 Grapheme::wcwidth('ะฏ'); // Returns: 1 // East Asian characters (width: 2) Grapheme::wcwidth('ๆ–‡'); // Returns: 2 Grapheme::wcwidth('ใ‚'); // Returns: 2 // Emoji (width: 2) Grapheme::wcwidth('๐Ÿ˜€'); // Returns: 2 Grapheme::wcwidth('๐Ÿš€'); // Returns: 2 // Complex emoji with modifiers (width: 2) Grapheme::wcwidth('๐Ÿ‘๐Ÿป'); // Returns: 2 Grapheme::wcwidth('๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ'); // Returns: 2 // Zero-width characters (width: 0) Grapheme::wcwidth("\u{200B}"); // Returns: 0 (Zero-width space) // Characters with combining marks (width: 1) Grapheme::wcwidth('รฉ'); // Returns: 1 Grapheme::wcwidth("e\u{0301}"); // Returns: 1 (e + combining acute) // Special cases Grapheme::wcwidth("โš \u{FE0E}"); // Returns: 1 (Warning sign in text presentation) Grapheme::wcwidth("โš \u{FE0F}"); // Returns: 2 (Warning sign in emoji presentation) // Empty string (width: 0) Grapheme::wcwidth(''); // Returns: 0 ``` ### Segmentation [](#segmentation) ``` // Split a full string into grapheme clusters Grapheme::split("e\u{0301}"); // Returns: ["eฬ"] Grapheme::split("\u{2764}\u{FE0F}"); // Returns: ["โค๏ธ"] Grapheme::split('๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ'); // Returns: ["๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ"] Grapheme::split('ๆ–‡A'); // Returns: ['ๆ–‡', 'A'] ``` ### Streaming / Chunked Segmentation [](#streaming--chunked-segmentation) `splitChunk()` preserves the trailing grapheme in `carry` so boundaries remain correct when text arrives in arbitrary byte chunks. Pass an empty chunk to flush the final completed grapheme at end-of-input. Invalid UTF-8 bytes are preserved as single-byte segments instead of throwing. ``` $carry = ''; $graphemes = []; foreach (["e", "\u{0301}"] as $chunk) { $result = Grapheme::splitChunk($carry, $chunk); $graphemes = [...$graphemes, ...$result['graphemes']]; $carry = $result['carry']; } $result = Grapheme::splitChunk($carry, ''); $graphemes = [...$graphemes, ...$result['graphemes']]; // ["eฬ"] ``` ### Cache Management [](#cache-management) Results are cached automatically for performance. For long-running processes, you can manage the cache: ``` // Clear the cache to free memory Grapheme::clearCache(); // Set maximum cache size (default: 10,000) // Cache auto-clears when this limit is exceeded Grapheme::setMaxCacheSize(5000); ``` Features -------- [](#features) - **Highly optimized** for performance with byte-level fast paths and smart caching - **Memory safe** for long-running processes with configurable cache limits - **Full-string and streaming segmentation** with a single source of truth for grapheme boundaries - **Comprehensive Unicode support** including: - CJK (Chinese, Japanese, Korean) characters - Emoji (including skin tone modifiers, gender modifiers, flags) - Zero-width characters and control codes - Combining marks and accents - Regional indicators and flags - Variation selectors - **Carefully tested** against a wide range of Unicode characters and streaming boundary cases (200+ assertions) - **Minimal dependencies** - only requires PHP 8.1+ and an optional intl extension - **Compatible** with most terminal environments Terminal Compatibility ---------------------- [](#terminal-compatibility) This library aims to match the behavior of `wcwidth()` in modern terminal emulators. Requirements ------------ [](#requirements) - PHP 8.1 or higher - The `symfony/polyfill-intl-grapheme`, `symfony/polyfill-mbstring`, and `symfony/polyfill-intl-normalizer` packages are included as dependencies - The `ext-intl` extension is recommended for best performance Under the Hood -------------- [](#under-the-hood) The library uses a series of optimized patterns and checks to accurately determine character width: 1. **Byte-level fast paths** - Single-byte ASCII, CJK (UTF-8 0xE4-0xE9), and emoji (UTF-8 0xF0 0x9F) are detected by examining raw bytes, avoiding expensive regex operations 2. **Smart caching** - Results are cached with automatic size limiting to prevent memory growth in long-running processes 3. **Best-available Unicode segmentation** - Valid UTF-8 text is segmented with native grapheme functions first, with regex fallback only if that backend is unavailable 4. **Chunk-safe UTF-8 handling** - Streaming segmentation preserves incomplete UTF-8 suffixes and the trailing grapheme in `carry` 5. **Special handling** for complex scripts like Devanagari, emoji variation selectors, and invisible joiners Performance benchmarks show ~1.6M uncached calls/sec and ~12M cached calls/sec on modern hardware. Testing ------- [](#testing) ``` composer test composer benchmark ``` The test suite includes 200+ assertions covering extensive Unicode scenarios including ASCII, CJK, emoji, zero-width characters, variation selectors, complex ZWJ sequences, and chunked segmentation boundaries. Please feel free to add more. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a pull request. License ------- [](#license) The MIT License (MIT). Support ------- [](#support) This is free! If you want to support me: - Check out my courses: - [Database School](https://databaseschool.com) - [Screencasting](https://screencasting.com) - Help spread the word about things I make Related Projects ---------------- [](#related-projects) - [Solo](https://github.com/soloterm/solo) - All-in-one Laravel command for local development - [Screen](https://github.com/soloterm/screen) - Pure PHP terminal renderer - [Dumps](https://github.com/soloterm/dumps) - Laravel command to intercept dumps - [Notify](https://github.com/soloterm/notify) - PHP package for desktop notifications via OSC escape sequences - [Notify Laravel](https://github.com/soloterm/notify-laravel) - Laravel integration for soloterm/notify - [TNotify](https://github.com/soloterm/tnotify) - Standalone, cross-platform CLI for desktop notifications - [VTail](https://github.com/soloterm/vtail) - Vendor-aware tail for Laravel logs Credits ------- [](#credits) Solo was developed by Aaron Francis. If you like it, please let me know! - Twitter: - Website: - YouTube: - GitHub: ### Health Score 52 โ€” FairBetter than 96% of packages Maintenance79 Regular maintenance activity Popularity48 Moderate usage in the ecosystem Community18 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 94.1% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~96 days Total 5 Last Release 110d ago PHP version history (2 changes)v1.0.0PHP ^8.2 v1.0.1PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/033238953a59b9223a1bde703b5e4254e63c7412195da1cb9de5af44bf53fc0a?d=identicon)[aarondfrancis](/maintainers/aarondfrancis) --- Top Contributors [![aarondfrancis](https://avatars.githubusercontent.com/u/881931?v=4)](https://github.com/aarondfrancis "aarondfrancis (32 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/soloterm-grapheme/health.svg) ``` [![Health](https://phpackages.com/badges/soloterm-grapheme/health.svg)](https://phpackages.com/packages/soloterm-grapheme) ``` ### Alternatives [symfony/symfony The Symfony PHP framework 31.4k87.2M2.2k](/packages/symfony-symfony)[symfony/string Provides an object-oriented API to strings and deals with bytes, UTF-8 code points and grapheme clusters in a unified way 1.8k777.3M1.3k](/packages/symfony-string)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6942.5M421](/packages/drupal-core-recommended)[symfony/dom-crawler Eases DOM navigation for HTML and XML documents 4.1k399.9M2.6k](/packages/symfony-dom-crawler)[friendsofphp/php-cs-fixer A tool to automatically fix PHP code style 13.5k251.2M25.2k](/packages/friendsofphp-php-cs-fixer)[symfony/filesystem Provides basic utilities for the filesystem 4.6k710.3M4.0k](/packages/symfony-filesystem) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)