Portable ASCII

If you prefer an Object-Oriented approach to string manipulation, you can use voku/Stringy. While Portable ASCII uses static methods, Stringy provides a fluent interface for string operations including transliteration.

// Portable ASCII (Static approach)
use voku\helper\ASCII;
ASCII::to_transliterate('déjà σσς iıii');

// voku/Stringy (Object-Oriented approach)
use Stringy\Stringy as S;
$stringy = S::create('déjà σσς iıii');
$stringy->toTransliterate(); // 'deja sss iiii'

The benchmark output contains a section labeled portable-ascii performance profile (median µs/op).

When analyzing this output:

1. Focus only on the profile lines: Look for lines starting with portable-ascii performance profile.
2. Ignore noise: Do not include PHPUnit progress dots or the final summary in your analysis.
3. Interpret values: Each value represents the median microseconds per operation (µs/op) for that specific scenario.
4. Comparison logic: When comparing a branch to master, calculate the delta using: delta = (branch / master - 1) * 100
   • A negative value indicates the branch is faster.
   • A positive value indicates the branch is slower.

You can run performance regression tests using the PHPUnit test suite. To enable the benchmark mode, you must set the environment variable PORTABLE_ASCII_RUN_PERFORMANCE_TESTS=1.

To run the benchmark for your current branch, use the following command:

PORTABLE_ASCII_RUN_PERFORMANCE_TESTS=1 ./vendor/bin/phpunit --filter PerformanceRegressionTest

To perform a comparison against the master branch, you should run the benchmark on a clean checkout of master and compare the resulting portable-ascii performance profile (median µs/op) blocks.

Install the library using Composer to add it to your PHP project.

composer require voku/portable-ascii

The voku\helper\ASCII class provides static methods to convert non-ASCII characters into their ASCII equivalents. This is useful for creating URL-friendly strings or normalizing text.

Example usage of ASCII::to_transliterate():

use voku\helper\ASCII;
ASCII::to_transliterate('déjà σσς iıii'); // 'deja sss iiii'

The ASCII::to_ascii() method converts characters to ASCII based on a specified locale (e.g., 'de' for German or 'en' for English). This allows for language-specific transliteration rules, such as converting 'ü' to 'ue' in German.

echo ASCII::to_ascii('�Düsseldorf�', 'de');
// outputs: Duesseldorf

echo ASCII::to_ascii('�Düsseldorf�', 'en');
// outputs: Dusseldorf

Use ASCII::normalize_msword() to replace smart quotes, ellipsis, and dashes from Windows-1252 (common in MS Word documents) with their ASCII equivalents.

```php
ASCII::normalize_msword('„Abcdef…”'); // '"Abcdef...

Use ASCII::to_filename() to convert a string into a safe filename while preserving the original case. By default, it uses ASCII::to_transliterate() for unsafe characters; otherwise, unsafe characters are replaced with a hyphen. You can provide a $fallback_char for characters that cannot be transliterated.

ASCII::to_filename('שדגשדג.png', true); // 'shdgshdg.png'

Use ASCII::to_transliterate() to return an ASCII version of a string by replacing non-ASCII characters with their closest counterparts. You can specify a character to use for unknown characters (default is '?') or use NULL to keep them. You can also enable strict mode to use transliterator_transliterate() from PHP-Intl.

ASCII::to_transliterate('déjà σσς iıii'); // 'deja sss iiii'

Use ASCII::is_ascii() to check if a string consists entirely of 7-bit ASCII characters.

ASCII::is_ascii('白'); // false

Use ASCII::to_ascii() to return an ASCII version of a string. Non-ASCII characters are replaced with their closest ASCII counterparts, and the rest are removed by default. You can provide a language/locale (e.g., 'en', 'de', 'en_GB') to enable language-specific transliteration (e.g., mapping 'ä' to 'ae' in German instead of just 'a').

ASCII::to_ascii('�Düsseldorf�', 'en'); // Dusseldorf