The String Component

The String Component

The String component provides a single object-oriented API to work with three “unit systems” of strings: bytes, code points and grapheme clusters.

New in version 5.0: The String component was introduced in Symfony 5.0.

Installation

  1. $ composer require symfony/string

Note

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

What is a String?

You can skip this section if you already know what a “code point” or a “grapheme cluster” are in the context of handling strings. Otherwise, read this section to learn about the terminology used by this component.

Languages like English require a very limited set of characters and symbols to display any content. Each string is a series of characters (letters or symbols) and they can be encoded even with the most limited standards (e.g. ASCII).

However, other languages require thousands of symbols to display their contents. They need complex encoding standards such as Unicode and concepts like “character” no longer make sense. Instead, you have to deal with these terms:

  • Code points: they are the atomic unit of information. A string is a series of code points. Each code point is a number whose meaning is given by the Unicode standard. For example, the English letter A is the U+0041 code point and the Japanese kana の is the U+306E code point.
  • Grapheme clusters: they are a sequence of one or more code points which are displayed as a single graphical unit. For example, the Spanish letter ñ is a grapheme cluster that contains two code points: U+006E = n (“latin small letter N”) + U+0303 = ◌̃ (“combining tilde”).
  • Bytes: they are the actual information stored for the string contents. Each code point can require one or more bytes of storage depending on the standard being used (UTF-8, UTF-16, etc.).

The following image displays the bytes, code points and grapheme clusters for the same word written in English (hello) and Hindi (नमस्ते):

../_images/bytes-points-graphemes.png

Usage

Create a new object of type Symfony\Component\String\ByteString, Symfony\Component\String\CodePointString or Symfony\Component\String\UnicodeString, pass the string contents as their arguments and then use the object-oriented API to work with those strings:

  1. use Symfony\Component\String\UnicodeString;
  3. $text = (new UnicodeString('This is a déjà-vu situation.'))
  4.     ->trimEnd('.')
  5.     ->replace('déjà-vu', 'jamais-vu')
  6.     ->append('!');
  7. // $text = 'This is a jamais-vu situation!'
  9. $content = new UnicodeString('नमस्ते दुनिया');
  10. if ($content->ignoreCase()->startsWith('नमस्ते')) {
  11.     // ...
  12. }

Method Reference

Methods to Create String Objects

First, you can create objects prepared to store strings as bytes, code points and grapheme clusters with the following classes:

  1. use Symfony\Component\String\ByteString;
  2. use Symfony\Component\String\CodePointString;
  3. use Symfony\Component\String\UnicodeString;
  5. $foo = new ByteString('hello');
  6. $bar = new CodePointString('hello');
  7. // UnicodeString is the most commonly used class
  8. $baz = new UnicodeString('hello');

Use the `wrap() static method to instantiate more than one string object:

  1. $contents = ByteString::wrap(['hello', 'world']);        // $contents = ByteString[]
  2. $contents = UnicodeString::wrap(['I', '❤️', 'Symfony']); // $contents = UnicodeString[]
  4. // use the unwrap method to make the inverse conversion
  5. $contents = UnicodeString::unwrap([
  6.     new UnicodeString('hello'), new UnicodeString('world'),
  7. ]); // $contents = ['hello', 'world']

If you work with lots of String objects, consider using the shortcut functions to make your code more concise:

  1. // the b() function creates byte strings
  2. use function Symfony\Component\String\b;
  4. // both lines are equivalent
  5. $foo = new ByteString('hello');
  6. $foo = b('hello');
  8. // the u() function creates Unicode strings
  9. use function Symfony\Component\String\u;
  11. // both lines are equivalent
  12. $foo = new UnicodeString('hello');
  13. $foo = u('hello');
  15. // the s() function creates a byte string or Unicode string
  16. // depending on the given contents
  17. use function Symfony\Component\String\s;
  19. // creates a ByteString object
  20. $foo = s("\xfe\xff");
  21. // creates a UnicodeString object
  22. $foo = s('अनुच्छेद');

New in version 5.1: The `s() function was introduced in Symfony 5.1.

There are also some specialized constructors:

  1. // ByteString can create a random string of the given length
  2. $foo = ByteString::fromRandom(12);
  3. // by default, random strings use A-Za-z0-9 characters; you can restrict
  4. // the characters to use with the second optional argument
  5. $foo = ByteString::fromRandom(6, 'AEIOU0123456789');
  6. $foo = ByteString::fromRandom(10, 'qwertyuiop');
  8. // CodePointString and UnicodeString can create a string from code points
  9. $foo = UnicodeString::fromCodePoints(0x928, 0x92E, 0x938, 0x94D, 0x924, 0x947);
  10. // equivalent to: $foo = new UnicodeString('नमस्ते');

New in version 5.1: The second argument of `ByteString::fromRandom() was introduced in Symfony 5.1.

Methods to Transform String Objects

Each string object can be transformed into the other two types of objects:

  1. $foo = ByteString::fromRandom(12)->toCodePointString();
  2. $foo = (new CodePointString('hello'))->toUnicodeString();
  3. $foo = UnicodeString::fromCodePoints(0x68, 0x65, 0x6C, 0x6C, 0x6F)->toByteString();
  5. // the optional $toEncoding argument defines the encoding of the target string
  6. $foo = (new CodePointString('hello'))->toByteString('Windows-1252');
  7. // the optional $fromEncoding argument defines the encoding of the original string
  8. $foo = (new ByteString('さよなら'))->toCodePointString('ISO-2022-JP');

If the conversion is not possible for any reason, you’ll get an Symfony\Component\String\Exception\InvalidArgumentException.

There is also a method to get the bytes stored at some position:

  1. // ('नमस्ते' bytes = [224, 164, 168, 224, 164, 174, 224, 164, 184,
  2. //                  224, 165, 141, 224, 164, 164, 224, 165, 135])
  3. b('नमस्ते')->bytesAt(0);   // [224]
  4. u('नमस्ते')->bytesAt(0);   // [224, 164, 168]
  6. b('नमस्ते')->bytesAt(1);   // [164]
  7. u('नमस्ते')->bytesAt(1);   // [224, 164, 174]
  1. // returns the number of graphemes, code points or bytes of the given string
  2. $word = 'नमस्ते';
  3. (new ByteString($word))->length();      // 18 (bytes)
  4. (new CodePointString($word))->length(); // 6 (code points)
  5. (new UnicodeString($word))->length();   // 4 (graphemes)
  7. // some symbols require double the width of others to represent them when using
  8. // a monospaced font (e.g. in a console). This method returns the total width
  9. // needed to represent the entire word
  10. $word = 'नमस्ते';
  11. (new ByteString($word))->width();      // 18
  12. (new CodePointString($word))->width(); // 4
  13. (new UnicodeString($word))->width();   // 4
  14. // if the text contains multiple lines, it returns the max width of all lines
  15. $text = "<<<END
  16. This is a
  17. multiline text
  18. END";
  19. u($text)->width(); // 14
  21. // only returns TRUE if the string is exactly an empty string (not even white spaces)
  22. u('hello world')->isEmpty();  // false
  23. u('     ')->isEmpty();        // false
  24. u('')->isEmpty();             // true
  26. // removes all white spaces from the start and end of the string and replaces two
  27. // or more consecutive white spaces inside contents by a single white space
  28. u("  \n\n   hello        world \n    \n")->collapseWhitespace(); // 'hello world'

Methods to Change Case

  1. // changes all graphemes/code points to lower case
  2. u('FOO Bar')->lower();  // 'foo bar'
  4. // when dealing with different languages, uppercase/lowercase is not enough
  5. // there are three cases (lower, upper, title), some characters have no case,
  6. // case is context-sensitive and locale-sensitive, etc.
  7. // this method returns a string that you can use in case-insensitive comparisons
  8. u('FOO Bar')->folded();             // 'foo bar'
  9. u('Die O\'Brian Straße')->folded(); // "die o'brian strasse"
  11. // changes all graphemes/code points to upper case
  12. u('foo BAR')->upper(); // 'FOO BAR'
  14. // changes all graphemes/code points to "title case"
  15. u('foo bar')->title();     // 'Foo bar'
  16. u('foo bar')->title(true); // 'Foo Bar'
  18. // changes all graphemes/code points to camelCase
  19. u('Foo: Bar-baz.')->camel(); // 'fooBarBaz'
  20. // changes all graphemes/code points to snake_case
  21. u('Foo: Bar-baz.')->snake(); // 'foo_bar_baz'
  22. // other cases can be achieved by chaining methods. E.g. PascalCase:
  23. u('Foo: Bar-baz.')->camel()->title(); // 'FooBarBaz'

The methods of all string classes are case-sensitive by default. You can perform case-insensitive operations with the `ignoreCase() method:

  1. u('abc')->indexOf('B');               // null
  2. u('abc')->ignoreCase()->indexOf('B'); // 1

Methods to Append and Prepend

  1. // adds the given content (one or more strings) at the beginning/end of the string
  2. u('world')->prepend('hello');      // 'helloworld'
  3. u('world')->prepend('hello', ' '); // 'hello world'
  5. u('hello')->append('world');      // 'helloworld'
  6. u('hello')->append(' ', 'world'); // 'hello world'
  8. // adds the given content at the beginning of the string (or removes it) to
  9. // make sure that the content starts exactly with that content
  10. u('Name')->ensureStart('get');       // 'getName'
  11. u('getName')->ensureStart('get');    // 'getName'
  12. u('getgetName')->ensureStart('get'); // 'getName'
  13. // this method is similar, but works on the end of the content instead of on the beginning
  14. u('User')->ensureEnd('Controller');           // 'UserController'
  15. u('UserController')->ensureEnd('Controller'); // 'UserController'
  16. u('UserControllerController')->ensureEnd('Controller'); // 'UserController'
  18. // returns the contents found before/after the first occurrence of the given string
  19. u('hello world')->before('world');   // 'hello '
  20. u('hello world')->before('o');       // 'hell'
  21. u('hello world')->before('o', true); // 'hello'
  23. u('hello world')->after('hello');   // ' world'
  24. u('hello world')->after('o');       // ' world'
  25. u('hello world')->after('o', true); // 'o world'
  27. // returns the contents found before/after the last occurrence of the given string
  28. u('hello world')->beforeLast('o');       // 'hello w'
  29. u('hello world')->beforeLast('o', true); // 'hello wo'
  31. u('hello world')->afterLast('o');       // 'rld'
  32. u('hello world')->afterLast('o', true); // 'orld'

Methods to Pad and Trim

  1. // makes a string as long as the first argument by adding the given
  2. // string at the beginning, end or both sides of the string
  3. u(' Lorem Ipsum ')->padBoth(20, '-'); // '--- Lorem Ipsum ----'
  4. u(' Lorem Ipsum')->padStart(20, '-'); // '-------- Lorem Ipsum'
  5. u('Lorem Ipsum ')->padEnd(20, '-');   // 'Lorem Ipsum --------'
  7. // repeats the given string the number of times passed as argument
  8. u('_.')->repeat(10); // '_._._._._._._._._._.'
  10. // removes the given characters (by default, white spaces) from the string
  11. u('   Lorem Ipsum   ')->trim(); // 'Lorem Ipsum'
  12. u('Lorem Ipsum   ')->trim('m'); // 'Lorem Ipsum   '
  13. u('Lorem Ipsum')->trim('m');    // 'Lorem Ipsu'
  15. u('   Lorem Ipsum   ')->trimStart(); // 'Lorem Ipsum   '
  16. u('   Lorem Ipsum   ')->trimEnd();   // '   Lorem Ipsum'

Methods to Search and Replace

  1. // checks if the string starts/ends with the given string
  2. u('https://symfony.com')->startsWith('https'); // true
  3. u('report-1234.pdf')->endsWith('.pdf');        // true
  5. // checks if the string contents are exactly the same as the given contents
  6. u('foo')->equalsTo('foo'); // true
  8. // checks if the string content match the given regular expression
  9. u('avatar-73647.png')->match('/avatar-(\d+)\.png/');
  10. // result = ['avatar-73647.png', '73647']
  12. // checks if the string contains any of the other given strings
  13. u('aeiou')->containsAny('a');                 // true
  14. u('aeiou')->containsAny(['ab', 'efg']);       // false
  15. u('aeiou')->containsAny(['eio', 'foo', 'z']); // true
  17. // finds the position of the first occurrence of the given string
  18. // (the second argument is the position where the search starts and negative
  19. // values have the same meaning as in PHP functions)
  20. u('abcdeabcde')->indexOf('c');     // 2
  21. u('abcdeabcde')->indexOf('c', 2);  // 2
  22. u('abcdeabcde')->indexOf('c', -4); // 7
  23. u('abcdeabcde')->indexOf('eab');   // 4
  24. u('abcdeabcde')->indexOf('k');     // null
  26. // finds the position of the last occurrence of the given string
  27. // (the second argument is the position where the search starts and negative
  28. // values have the same meaning as in PHP functions)
  29. u('abcdeabcde')->indexOfLast('c');     // 7
  30. u('abcdeabcde')->indexOfLast('c', 2);  // 7
  31. u('abcdeabcde')->indexOfLast('c', -4); // 2
  32. u('abcdeabcde')->indexOfLast('eab');   // 4
  33. u('abcdeabcde')->indexOfLast('k');     // null
  35. // replaces all occurrences of the given string
  36. u('http://symfony.com')->replace('http://', 'https://'); // 'https://symfony.com'
  37. // replaces all occurrences of the given regular expression
  38. u('(+1) 206-555-0100')->replaceMatches('/[^A-Za-z0-9]++/', ''); // '12065550100'
  39. // you can pass a callable as the second argument to perform advanced replacements
  40. u('123')->replaceMatches('/\d/', function ($match) {
  41.     return '['.$match[0].']';
  42. }); // result = '[1][2][3]'

New in version 5.1: The `containsAny() method was introduced in Symfony 5.1.

Methods to Join, Split, Truncate and Reverse

  1. // uses the string as the "glue" to merge all the given strings
  2. u(', ')->join(['foo', 'bar']); // 'foo, bar'
  4. // breaks the string into pieces using the given delimiter
  5. u('template_name.html.twig')->split('.');    // ['template_name', 'html', 'twig']
  6. // you can set the maximum number of pieces as the second argument
  7. u('template_name.html.twig')->split('.', 2); // ['template_name', 'html.twig']
  9. // returns a substring which starts at the first argument and has the length of the
  10. // second optional argument (negative values have the same meaning as in PHP functions)
  11. u('Symfony is great')->slice(0, 7);  // 'Symfony'
  12. u('Symfony is great')->slice(0, -6); // 'Symfony is'
  13. u('Symfony is great')->slice(11);    // 'great'
  14. u('Symfony is great')->slice(-5);    // 'great'
  16. // reduces the string to the length given as argument (if it's longer)
  17. u('Lorem Ipsum')->truncate(3);             // 'Lor'
  18. u('Lorem Ipsum')->truncate(80);            // 'Lorem Ipsum'
  19. // the second argument is the character(s) added when a string is cut
  20. // (the total length includes the length of this character(s))
  21. u('Lorem Ipsum')->truncate(8, '…');        // 'Lorem I…'
  22. // if the third argument is false, the last word before the cut is kept
  23. // even if that generates a string longer than the desired length
  24. u('Lorem Ipsum')->truncate(8, '…', false); // 'Lorem Ipsum'

New in version 5.1: The third argument of `truncate() was introduced in Symfony 5.1.

  1. // breaks the string into lines of the given length
  2. u('Lorem Ipsum')->wordwrap(4);             // 'Lorem\nIpsum'
  3. // by default it breaks by white space; pass TRUE to break unconditionally
  4. u('Lorem Ipsum')->wordwrap(4, "\n", true); // 'Lore\nm\nIpsu\nm'
  6. // replaces a portion of the string with the given contents:
  7. // the second argument is the position where the replacement starts;
  8. // the third argument is the number of graphemes/code points removed from the string
  9. u('0123456789')->splice('xxx');       // 'xxx'
  10. u('0123456789')->splice('xxx', 0, 2); // 'xxx23456789'
  11. u('0123456789')->splice('xxx', 0, 6); // 'xxx6789'
  12. u('0123456789')->splice('xxx', 6);    // '012345xxx'
  14. // breaks the string into pieces of the length given as argument
  15. u('0123456789')->chunk(3);  // ['012', '345', '678', '9']
  17. // reverses the order of the string contents
  18. u('foo bar')->reverse(); // 'rab oof'
  19. u('さよなら')->reverse(); // 'らなよさ'

New in version 5.1: The `reverse() method was introduced in Symfony 5.1.

Methods Added by ByteString

These methods are only available for ByteString objects:

  1. // returns TRUE if the string contents are valid UTF-8 contents
  2. b('Lorem Ipsum')->isUtf8(); // true
  3. b("\xc3\x28")->isUtf8();    // false

Methods Added by CodePointString and UnicodeString

These methods are only available for CodePointString and UnicodeString objects:

  1. // transliterates any string into the latin alphabet defined by the ASCII encoding
  2. // (don't use this method to build a slugger because this component already provides
  3. // a slugger, as explained later in this article)
  4. u('नमस्ते')->ascii();    // 'namaste'
  5. u('さよなら')->ascii(); // 'sayonara'
  6. u('спасибо')->ascii(); // 'spasibo'
  8. // returns an array with the code point or points stored at the given position
  9. // (code points of 'नमस्ते' graphemes = [2344, 2350, 2360, 2340]
  10. u('नमस्ते')->codePointsAt(0); // [2344]
  11. u('नमस्ते')->codePointsAt(2); // [2360]

Unicode equivalence is the specification by the Unicode standard that different sequences of code points represent the same character. For example, the Swedish letter å can be a single code point (U+00E5 = “latin small letter A with ring above”) or a sequence of two code points (U+0061 = “latin small letter A” + U+030A = “combining ring above”). The `normalize() method allows to pick the normalization mode:

  1. // these encode the letter as a single code point: U+00E5
  2. u('å')->normalize(UnicodeString::NFC);
  3. u('å')->normalize(UnicodeString::NFKC);
  4. // these encode the letter as two code points: U+0061 + U+030A
  5. u('å')->normalize(UnicodeString::NFD);
  6. u('å')->normalize(UnicodeString::NFKD);

Slugger

In some contexts, such as URLs and file/directory names, it’s not safe to use any Unicode character. A slugger transforms a given string into another string that only includes safe ASCII characters:

  1. use Symfony\Component\String\Slugger\AsciiSlugger;
  3. $slugger = new AsciiSlugger();
  4. $slug = $slugger->slug('Wôrķšƥáçè ~~sèťtïñğš~~');
  5. // $slug = 'Workspace-settings'
  7. // you can also pass an array with additional character substitutions
  8. $slugger = new AsciiSlugger('en', ['en' => ['%' => 'percent', '€' => 'euro']]);
  9. $slug = $slugger->slug('10% or 5€');
  10. // $slug = '10-percent-or-5-euro'
  12. // if there is no symbols map for your locale (e.g. 'en_GB') then the parent locale's symbols map
  13. // will be used instead (i.e. 'en')
  14. $slugger = new AsciiSlugger('en_GB', ['en' => ['%' => 'percent', '€' => 'euro']]);
  15. $slug = $slugger->slug('10% or 5€');
  16. // $slug = '10-percent-or-5-euro'
  18. // for more dynamic substitutions, pass a PHP closure instead of an array
  19. $slugger = new AsciiSlugger('en', function ($string, $locale) {
  20.     return str_replace('❤️', 'love', $string);
  21. });

New in version 5.1: The feature to define additional substitutions was introduced in Symfony 5.1.

New in version 5.2: The feature to use a PHP closure to define substitutions was introduced in Symfony 5.2.

New in version 5.3: The feature to fallback to the parent locale’s symbols map was introduced in Symfony 5.3.

The separator between words is a dash (-) by default, but you can define another separator as the second argument:

  1. $slug = $slugger->slug('Wôrķšƥáçè ~~sèťtïñğš~~', '/');
  2. // $slug = 'Workspace/settings'

The slugger transliterates the original string into the Latin script before applying the other transformations. The locale of the original string is detected automatically, but you can define it explicitly:

  1. // this tells the slugger to transliterate from Korean language
  2. $slugger = new AsciiSlugger('ko');
  4. // you can override the locale as the third optional parameter of slug()
  5. $slug = $slugger->slug('...', '-', 'fa');

In a Symfony application, you don’t need to create the slugger yourself. Thanks to service autowiring, you can inject a slugger by type-hinting a service constructor argument with the Symfony\Component\String\Slugger\SluggerInterface. The locale of the injected slugger is the same as the request locale:

  1. use Symfony\Component\String\Slugger\SluggerInterface;
  3. class MyService
  4. {
  5.     private $slugger;
  7.     public function __construct(SluggerInterface $slugger)
  8.     {
  9.         $this->slugger = $slugger;
  10.     }
  12.     public function someMethod()
  13.     {
  14.         $slug = $this->slugger->slug('...');
  15.     }
  16. }

Inflector

New in version 5.1: The inflector feature was introduced in Symfony 5.1.

In some scenarios such as code generation and code introspection, you need to convert words from/to singular/plural. For example, to know the property associated with an adder method, you must convert from plural (addStories() method) to singular ($story` property).

Most human languages have simple pluralization rules, but at the same time they define lots of exceptions. For example, the general rule in English is to add an s at the end of the word (book -> books) but there are lots of exceptions even for common words (woman -> women, life -> lives, news -> news, radius -> radii, etc.)

This component provides an Symfony\Component\String\Inflector\EnglishInflector class to convert English words from/to singular/plural with confidence:

  1. use Symfony\Component\String\Inflector\EnglishInflector;
  3. $inflector = new EnglishInflector();
  5. $result = $inflector->singularize('teeth');   // ['tooth']
  6. $result = $inflector->singularize('radii');   // ['radius']
  7. $result = $inflector->singularize('leaves');  // ['leaf', 'leave', 'leaff']
  9. $result = $inflector->pluralize('bacterium'); // ['bacteria']
  10. $result = $inflector->pluralize('news');      // ['news']
  11. $result = $inflector->pluralize('person');    // ['persons', 'people']

The value returned by both methods is always an array because sometimes it’s not possible to determine a unique singular/plural form for the given word.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.