PHPackages                             moccalotto/stringy - 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. moccalotto/stringy

ActiveLibrary

moccalotto/stringy
==================

Easy, powerful and fluent string handling

0.4.1(9y ago)060MITPHPPHP >=7.0.0

Since Mar 3Pushed 8y ago1 watchersCompare

[ Source](https://github.com/moccalotto/stringy)[ Packagist](https://packagist.org/packages/moccalotto/stringy)[ Docs](https://moccalotto.github.io/docs/stringy)[ RSS](/packages/moccalotto-stringy/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (3)DependenciesVersions (4)Used By (0)

Stringy
=======

[](#stringy)

[![Build Status](https://camo.githubusercontent.com/8731fed55a792a7d52b5d65e11c8272eec5bf041cd9b84cad5cb169541683c4c/68747470733a2f2f7472617669732d63692e6f72672f6d6f6363616c6f74746f2f737472696e67792e737667)](https://travis-ci.org/moccalotto/stringy)

Easy, powerful and fluent string handling

Installation
------------

[](#installation)

To add this package as a local, per-project dependency to your project, simply add a dependency on `moccalotto/stringy` to your project's `composer.json` file.

This can be done via composer:

```
composer require moccalotto/stringy
```

Documentation
-------------

[](#documentation)

The `Stringy` object is immutable. This means that all operations that return a *new* `Stringy` instance This means that you will not have to `clone` the object if you need to do two different, branching operations on a given string.

On the other hand, it is quite likely that you cannot identity-compare two stringy objects because they are often very short-lived. In cases where you need to check if two stringy objects contain the same string, we suggest using the `is()` method. See the example below:

```
$s0 = str('Foo');

$s1 = $s0->lower(),
$s2 = $s0->lower();

if ($s0 === $s1) {
    echo 'this code will not be executed';
}

if ($s1 === $s2) {
    echo 'this code will not be executed';
}

if ($s1->is($s2)) {
    echo 'this will work just fine';
}

if (strval($s1) === strval($s2)) {
    echo 'this will also work';
}
```

### Constructors

[](#constructors)

Normal constructor.

```
/**
 * Constructor.
 *
 * @param string      $string          the string contents of the Stringy object
 * @param string|null $currentEncoding the current encoding of $string
 */
public function __construct(string $string = '', string $currentEncoding = null)
```

Static factory.

```
/**
 * Factory.
 *
 * @param Stringy|string $string   The string to be Stringyfied.
 *                                 If $string is a (descendant of) Stringy, it will
 *                                 be cloned and converted to using $encoding
 * @param string|null    $encoding The encoding of the $string
 *
 * @return Stringy
 */
public static function create($string = '', string $encoding = null)
```

Helper factory function.

```
/**
 * Stringify a string
 *
 * @param Stringy|string $string   The string to be Stringyfied.
 *                                 If $string is a (descendant of) Stringy, it will
 *                                 be cloned and converted to using $encoding.
 * @param string|null    $encoding The encoding of the $string
 *
 * @return Stringy
 */
function str($string = '', string $encoding = null) : Stringy
```

Create a random string.

```
/**
 * Factory for a random string of a given length.
 *
 * @return Stringy
 */
public static function random($length)
```

### Get the content string.

[](#get-the-content-string)

```
/**
 * Get the content string of this object encoded as $encoding.
 *
 * @param string|null $encodedAs The encoding to get the string as. NULL = mb_internal_encoding
 *
 * @return string
 */
public function string($encodedAs = null) : string
```

### String comparison

[](#string-comparison)

```
/**
 * Compare this string to another.
 *
 * @param Stringy|string $string
 *
 * @return bool only true if the two strings are equal using strict (===) comparison.
 */
public function is($string) : bool
```

```
/**
 * Does the string contain $needle.
 *
 * @param Stringy|string $needle
 * @param int            $index
 *
 * @return bool
 */
public function contains($needle, int $index = 0) : bool
```

```
/**
 * Does the string start with $needle ?
 *
 * @param Stringy|string $needle.
 *
 * @return bool
 */
public function startsWith($needle) : bool
```

```
/**
 * Does the string end with $needle ?
 *
 * @param Stringy|string $needle.
 *
 * @return bool
 */
public function endsWith($needle) : bool
```

### Length (characters)

[](#length-characters)

```
/**
 * Get the length (in characters) of the content string.
 *
 * @return int
 */
public function length() : int
```

### Size (bytes)

[](#size-bytes)

```
/**
 * Get the size (in bytes) of the content string.
 *
 * @return int
 */
public function size() : int
```

### Position of substring

[](#position-of-substring)

```
/**
 * Find a the position of the first character of $needle within this string.
 *
 * @param Stringy|string $needle The string to search for
 * @param int            $index  Which occurrance of the string to get the position of.
 *                               0 means the first match, 1 means the second match, etc.
 *                               -1 means the last match, -2 means the penultimate match, etc
 *
 * @return int|null The position of the first character of the $needle found.
 *                  NULL if $needle with the given $index could not be found
 *                  NOTE: that this behavior deviates from strpos in that strpos returns FALSE
 *                  in case $needle was not found.
 */
public function positionOf($needle, int $index = 0)
```

### Getting words and characters from the string.

[](#getting-words-and-characters-from-the-string)

You can get individual characters via the php array accessor language construct like so:

```
// Accessing individual characters:
$str = str('foo bar baz');

$str[0]->string() === 'f'; // true
$str[1]->string() === 'o'; // true
$str[2]->string() === 'o'; // true

$str[-3]->string() === 'b' // true
$str[-2]->string() === 'a' // true
$str[-1]->string() === 'z' // true

$x = $str[30]; // OutOfRangeException
```

```
/**
 * Convert the content string into an array of words.
 *
 * Note that this method will not correctly split kanji, thai, braille, and
 * other scripts where words are not necessarily clearly bounded.
 *
 * @return Stringy[]
 */
public function words() : array
```

```
/**
 * Get an array of characters in the content string.
 *
 * @return Stringy[]
 */
public function characters() : array
```

### Map/transform the string

[](#maptransform-the-string)

```
/**
 * Transform the string.
 *
 * @param callable $callable a function with the signature (Stringy $string) : Stringy|string
 *
 * @return Stringy
 */
public function transform(callable $callable)
```

Example:

```
$str = str('foo bar baz');

$formatted = $str->transform(function (Stringy $stringy) {
    // the output of str_rot13() is a string
    // but it will automatically be converted to a
    // Stringy instance using the default character set.
    // If you return your own Stringy object, it will not be converted in any way.
    return str_rot13($stringy->asciiSafe());
});

print $formatted->string();
```

### Fetch a substring

[](#fetch-a-substring)

```
/**
 * Get a substring.
 *
 * @see http://php.net/manual/function.mb-substr.php
 *      for details about the $start and $length paramteers
 *
 * @param int      $start  The offset of the substring.
 *                         If negative, it counts backwards
 *                         from the end of the content string.
 * @param int|null $length The length of the substring to extract.
 *                         If negative, it counts backwards from
 *                         the end of the content string.
 *                         If NULL, the entire string after $start
 *                         is extracted.
 *
 * @return Stringy
 */
public function substring(int $start, int $length = null)

```

### Fetch segments of a string based on searches.

[](#fetch-segments-of-a-string-based-on-searches)

Fetch the part of the string that comes after a given search term.

```
/**
 * Get the part of the string that comes after $needle.
 *
 * @example: str('foo bar baz')->after('foo ') == 'bar baz'
 *
 * @param Stringy|string $needle
 * @param int            $index  Which occurrance of the string to search for:
 *                               0 means the first match, 1 means the second match, etc.
 *                               -1 means the last match, -2 means the penultimate match, etc
 *
 * @return Stringy a clone of $this with a content string containing the
 *                 part that comes after $needle. If $needle is not
 *                 found, an empty Stringy is returned
 */
public function after($needle, int $index = 0)
```

Fetch the part of the string that comes before a given search term.

```
/**
 * Get the part of the string before the first character of $needle.
 *
 * @example: str('foo bar baz')->before('foo ') == 'bar baz'
 *
 * @param Stringy|string $needle
 * @param int            $index  Which occurrance of the string to search for:
 *                               0 means the first match, 1 means the second match, etc.
 *                               -1 means the last match, -2 means the penultimate match, etc
 *
 * @return Stringy a clone of $this with a content string containing the
 *                 part that comes after $needle. If $needle is not
 *                 found, an empty Stringy is returned
 */
public function before($needle, int $index = 0)
```

Fetch the part of the string that resides between two search terms.

```
/**
 * Return the text that comes after $start and before $stop.
 *
 * @param Stringy|string $start
 * @param Stringy|string $stop
 * @param int            $pairIndex search for the nth pair and
 *                                  find what lies between those strings
 *
 * @return Stringy the string between $start and $stop
 */
public function between($start, $stop, int $pairIndex = 0)
```

### Remove parts of the string based on search terms.

[](#remove-parts-of-the-string-based-on-search-terms)

Remove the part of the string that comes after the given search term.

```
/**
 * Remove the substring that comes after the nth $needle.
 *
 * @param Stringy|string $needle
 * @param int            $index
 *
 * @return Stringy
 */
public function removeAfter($needle, int $index = 0)
```

Remove the part of the string that comes before the given search term.

```
/**
 * Remove the substring that comes before the nth $needle.
 *
 * @param Stringy|string $needle
 * @param int            $index
 *
 * @return Stringy
 */
public function removeBefore($needle, int $index = 0)
```

### Repetition

[](#repetition)

Repeating a string

```
/**
 * Repeat this string a number of times.
 *
 * @param int $times
 *
 * @return Stringy a string repeated $times times
 */
public function repeat(int $times)
```

```
/**
 * Remove repititions of substrings.
 *
 * If a substring is repeated 2 or more times in a row within the
 * content string,reduce it to being there only once.
 *
 * str('hello    world')->unrepeat(' ') would be turned into 'hello world'
 * str('foo    bar    baz')->unrepeat(' ') would be turned into 'foo bar baz'
 *
 * @param Stringy|string $substring
 *
 * @return Stringy
 */
public function unrepeat($substring)
```

### Add padding

[](#add-padding)

```
/**
 * Append padding to the right hand side of the string.
 *
 * @param int            $totalLengthOfResult the total length of the result string
 * @param Stringy|string $padding             the padding character to use
 *
 * @return Stringy
 */
public function rightPadded(int $totalLengthOfResult, $padding = ' ')
```

```
/**
 * Prepend padding to the left hand side of the string.
 *
 * @param int            $totalLengthOfResult the total length of the result string
 * @param Stringy|string $padding             the padding character to use
 *
 * @return Stringy
 */
public function leftPadded(int $totalLengthOfResult, $padding = ' ')
```

```
/**
 * Add padding to both sides of the content string such that it becomes centered.
 *
 * @param int            $totalLengthOfResult the total length of the result string
 * @param Stringy|string $padding             the padding character to use
 * @param string         $tieBreak            Can either be "left" or "right".
 *                                            In case the content string cannot be
 *                                            centered, should the content string
 *                                            be to the left of center or the right of
 *                                            center.
 *
 * @return Stringy
 */
public function centered(int $totalLengthOfResult, $padding = ' ', $tieBreak = 'left')
```

### Remove Padding

[](#remove-padding)

```
/**
 * Remove all instances of $needle from the beginning of the content string.
 *
 * @param Stringy|string $needle the substring to remove from the
 *                               beginning of the content string
 *
 * @return Stringy
 */
public function leftTrim($needle)
```

```
/**
 * Remove all instances of $needle from the end of the content string.
 *
 * @param Stringy|string $needle the substring to remove from the
 *                               end of the content string
 *
 * @return Stringy
 */
public function rightTrim($needle)
```

```
/**
 * Remove all occurances of $strings from the beginning of the content string.
 *
 * @param array $strings An array of strings or Stringy objects.
 *
 * @return Stringy
 */
public function leftTrimAll(array $strings)
```

```
/**
 * Remove all occurances of $strings from the end of the content string.
 *
 * @param array $strings An array of strings or Stringy objects.
 *
 * @return Stringy
 */
public function rightTrimAll(array $strings)
```

### Appending and prepending

[](#appending-and-prepending)

```
/**
 * Append a string to $this.
 *
 * @param Stringy|string $other
 *
 * @return Stringy a clone of $this where contents of $other is prepended
 */
public function append($other)
```

```
/**
 * Prepend a string to $this.
 *
 * @param Stringy|string $other
 *
 * @return Stringy a clone of $this where contents of $other is prepended
 */
public function prepend($other)
```

```
/**
 * Surround the content string with two other strings.
 *
 * Essentially the same as calling prepend and append in one single operation.
 *
 * @param Stringy|string      $left  the string to be prepended to the content string
 * @param Stringy|string|null $right The string to be appended to the content string.
 *                                   if NULL, the $left string will be used.
 *
 * @return Stringy
 */
public function surroundWith($left, $right = null)
```

### Adjust Casing

[](#adjust-casing)

```
/**
 * Convert the content string to uppercase.
 *
 * @return Stringy
 */
public function upper()
```

```
/**
 * Convert the content string to lowercase.
 *
 * @return Stringy
 */
public function lower()
```

```
/**
 * Turn the first letter of every word uppercase.
 *
 * Does not interfere with the casing of the rest of the letters.
 * Words are defined as strings separated by a word-boundary (such as white space, dashes, dots, etc.)
 *
 * @return Stringy
 */
public function ucwords()
```

```
/**
 * Turn the first letter of every word lowercase.
 *
 * Does not interfere with the casing of the rest of the letters.
 * Words are defined as strings separated by a word-boundary (such as white space, dashes, dots, etc.)
 *
 * @return Stringy
 */
public function lcwords()
```

```
/**
 * Turn first letter uppercased.
 *
 * Do not change the casing of the rest of the letters.
 */
public function ucfirst()
```

```
/**
 * Turn first letter lowercased.
 *
 * Do not change the casing of the rest of the letters.
 */
public function lcfirst()
```

### Exploding and imploding

[](#exploding-and-imploding)

```
/**
 * Split the string into segments.
 *
 * @see http://php.net/manual/function.explode.php
 *
 * @param Stringy|string $pattern
 * @param int            $limit
 *
 * @return Stringy[] array of strings as Stringy instances
 */
public function explode($pattern, int $limit = PHP_INT_MAX) : array
```

```
/**
 * Use the content string as glue to implode an array of strings.
 *
 * For instance: str(' + ')->glue(['this', 'that']) would yield the result "this + that".
 *
 * @see http://php.net/manual/function.implode.php
 *
 * @param array $strings An array of strings or Stringy objects that will be glued together.
 *
 * @return Stringy
 */
public function glue(array $strings)
```

### Replace and remove

[](#replace-and-remove)

```
/**
 * Replace all occurrences of the $search string with the $replacement string.
 *
 * @see http://php.net/manual/function.str-replace.php
 *
 * @param Stringy|string $search
 * @param Stringy|string $replace
 *
 * @return Stringy
 */
public function replace($search, $replace)
```

```
/**
 * Perform to => from translation.
 *
 * @see http://php.net/manual/function.strtr.php
 *
 * @param array $replacePairs an array in the form array('from' => 'to', ...).
 *
 * @return Stringy a Stringy where all the occurrences
 *                 of the array keys have been replaced by the corresponding values.
 *                 The longest keys will be tried first.
 *                 Once a substring has been replaced,
 *                 its new value will not be searched again.
 */
public function replaceMany(array $replacePairs)
```

```
/**
 * Remove a substring. (I.e. replace $search with an empty string).
 *
 * @param Stringy|string $search the substring to be removed
 *
 * @return Stringy
 */
public function remove($search)
```

```
**
 * Remove a number of substrings.
 *
 * @param array $searches an array of strings (or Stringy objects)
 *                        to be removed
 *
 * @return Stringy
 */
public function removeMany(array $searches)
```

### Escaping

[](#escaping)

```
/**
 * Ensure that all characters are ASCII.
 *
 * Convert non-ascii characters to ASCII if possible (i.e. 'ü' is converted to 'u' and 'æ' to 'ae').
 * Remove any characters that cannot be converted (i.e. most characters that are not based on the latin script).
 *
 * @return Stringy
 */
public function asciiSafe()
```

```
/**
 * Convert all non-ASCII  characters into html entities.
 *
 * @see http://php.net/manual/function.htmlentities.php
 *
 * @param int $flags See php documentation for htmlentities
 *
 * @return Stringy
 */
public function entityEncoded(int $flags = ENT_QUOTES | ENT_HTML5)
```

```
/**
 * Escape this string for use as html text.
 *
 * @see http://php.net/manual/function.htmlspecialchars.php
 *
 * @param int $flags See php documentation for htmlspecialchars
 *
 * @return Stringy
 */
public function escapeForHtml(int $flags = ENT_QUOTES | ENT_HTML5)
```

```
/**
 * Escape a string so it can be used in a regular expression.
 *
 * @param Stringy|string $delimiter the delimiter used to start and
 *                                  terminate the regular expression.
 *                                  Usually the forward slash will be
 *                                  used to encluse regular expression.
 *
 * @return Stringy|string
 */
public function escapeForRegex($delimiter)
```

### Formatting

[](#formatting)

```
/**
 * Include the content string in another, using sprintf syntax.
 *
 * @see http://php.net/manual/function.sprintf.php
 *
 * @param Stringy|string $string      The sprintf-template string to use.
 *                                    Must include at least one "%s"
 * @param array          $extraParams extra params to use in the sprintf operation
 *
 * @return Stringy
 */
public function includeIn($string, array $extraParams = [])

// example:

str('bar')->includeIn('foo %s baz')->is('foo bar baz'); // true

str('bar')->includeIn('foo %s %s', ['baz'])->is('foo bar baz'); // true
```

```
/**
 * Use the content string as a sprintf-template string.
 *
 * @see http://php.net/manual/function.vsprintf.php
 *
 * @param array $args an array of args to use á la vsprintf
 *
 * @return Stringy
 */
public function format(array $args)
```

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity8

Limited adoption so far

Community5

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~0 days

Total

3

Last Release

3359d ago

### Community

---

Top Contributors

[![moccalotto](https://avatars.githubusercontent.com/u/3907867?v=4)](https://github.com/moccalotto "moccalotto (11 commits)")

---

Tags

declarativefluentstringstexttext-formattingutf-8

### Embed Badge

![Health badge](/badges/moccalotto-stringy/health.svg)

```
[![Health](https://phpackages.com/badges/moccalotto-stringy/health.svg)](https://phpackages.com/packages/moccalotto-stringy)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)