README

这是一个维护分支，基于 danielstjules/Stringy，以便支持 PHP 7.3 兼容性。

一个支持多字节的 PHP 字符串操作库。兼容 PHP 5.4+、PHP 7+（包括 PHP 7.3）和 HHVM。

s('string')->toTitleCase()->ensureRight('y') == 'Stringy'

有关旧版文档，请参阅 1.x 分支或 2.x 分支。

为什么？
安装
面向对象和链式操作
实现接口
PHP 5.6 创建
StaticStringy
类方法
- 创建
实例方法

扩展
测试
许可证

为什么？

部分原因是在 PHP 的许多标准字符串函数中缺乏多字节支持（包括 UTF-8）。但也为了提供一个围绕 mbstring 模块的多字节兼容函数的面向对象的包装。Stringy 处理一些怪异之处，提供额外的功能，并希望使字符串更容易处理！

// Standard library
strtoupper('fòôbàř');       // 'FòôBàř'
strlen('fòôbàř');           // 10

// mbstring
mb_strtoupper('fòôbàř');    // 'FÒÔBÀŘ'
mb_strlen('fòôbàř');        // '6'

// Stringy
s('fòôbàř')->toUpperCase(); // 'FÒÔBÀŘ'
s('fòôbàř')->length();      // '6'

安装

如果您使用 Composer 来管理依赖项，您可以在 composer.json 文件中包含以下内容

"require": {
    "danielstjules/stringy": "~3.1.0"
}

然后，运行 composer update 或 php composer.phar update 后，您可以使用 Composer 的自动加载来加载类

require 'vendor/autoload.php';

否则，您可以简单地直接引入文件

require_once 'path/to/Stringy/src/Stringy.php';

在两种情况下，我都建议使用别名。

use Stringy\Stringy as S;

请注意，Stringy 依赖于 mbstring 模块来提供其底层多字节支持。如果找不到该模块，Stringy 将使用 symfony/polyfill-mbstring。ex-mbstring 是一个非默认但非常常见的模块。例如，在 debian 和 ubuntu 中，它包含在 libapache2-mod-php5、php5-cli 和 php5-fpm 中。对于使用 homebrew 安装任何版本的 PHP 的 OSX 用户，它是一个默认模块。如果您从头编译 PHP，可以使用 --enable-mbstring 标志来包含它。

面向对象和链式操作

该库提供了如下的面向对象方法链式操作

use Stringy\Stringy as S;
echo S::create('fòô     bàř')->collapseWhitespace()->swapCase(); // 'FÒÔ BÀŘ'

Stringy\Stringy 有一个 __toString() 方法，当对象在字符串上下文中使用时返回当前字符串，即：(string) S::create('foo') // 'foo'

实现接口

Stringy\Stringy 实现了 IteratorAggregate 接口，这意味着可以使用 foreach 与类的实例一起使用

$stringy = S::create('fòôbàř');
foreach ($stringy as $char) {
    echo $char;
}
// 'fòôbàř'

它实现了 Countable 接口，允许使用 count() 来检索字符串中的字符数

$stringy = S::create('fòô');
count($stringy);  // 3

此外，还实现了 ArrayAccess 接口。因此，可以使用 isset() 来检查特定索引处的字符是否存在。由于 Stringy\Stringy 是不可变的，因此任何对 offsetSet 或 offsetUnset 的调用都将抛出异常。offsetGet 已实现，并接受正索引和负索引。无效的索引将导致 OutOfBoundsException。

$stringy = S::create('bàř');
echo $stringy[2];     // 'ř'
echo $stringy[-2];    // 'à'
isset($stringy[-4]);  // false

$stringy[3];          // OutOfBoundsException
$stringy[2] = 'a';    // Exception

PHP 5.6 创建

从 PHP 5.6 开始，use function 可用于导入函数。Stringy 暴露了一个命名空间函数，Stringy\create，它与 Stringy\Stringy::create() 具有相同的行为。如果您正在运行 PHP 5.6 或其他支持 use function 语法的环境中，您可以利用更简单的 API，如下所示

use function Stringy\create as s;

// Instead of: S::create('fòô     bàř')
s('fòô     bàř')->collapseWhitespace()->swapCase();

StaticStringy

所有在“实例方法”下列出的方法都可以作为静态包装器的一部分使用。对于StaticStringy方法，可选的编码期望是最后一个参数。返回值不会被强制类型转换，因此可能是Stringy、整数、布尔值等类型。

use Stringy\StaticStringy as S;

// Translates to Stringy::create('fòôbàř')->slice(0, 3);
// Returns a Stringy object with the string "fòô"
S::slice('fòôbàř', 0, 3);

类方法

create(mixed $str [, $encoding ])

创建一个Stringy对象，并将提供的值分配给str和encoding属性。$str在分配之前被转换为字符串，如果未指定$encoding，则默认为mb_internal_encoding()。然后返回初始化后的对象。如果第一个参数是一个数组或没有__toString方法的对象，则抛出InvalidArgumentException异常。

$stringy = S::create('fòôbàř'); // 'fòôbàř'

实例方法

Stringy对象是不可变的。以下所有示例都使用了PHP 5.6函数导入和PHP 5.4简短数组语法。它们还假设mb_internal_encoding()返回的编码是UTF-8。有关详细信息，请参阅上面create方法的文档以及PHP 5.6创建的说明。

append(string $string)

返回一个新字符串，其中包含追加的$string。

s('fòô')->append('bàř'); // 'fòôbàř'

at(int $index)

返回索引为$index的字符，索引从0开始。

s('fòôbàř')->at(3); // 'b'

between(string $start, string $end [, int $offset])

如果找到，返回$start和$end之间的子字符串，否则返回空字符串。可以提供一个可选的偏移量，从该偏移量开始搜索start字符串。

s('{foo} and {bar}')->between('{', '}'); // 'foo'

camelize()

返回字符串的camelCase版本。删除周围的空格，将数字、空格、破折号和下划线之后的字母大写，并删除空格、破折号以及下划线。

s('Camel-Case')->camelize(); // 'camelCase'

chars()

返回一个由字符串中的字符组成的数组。

s('fòôbàř')->chars(); // ['f', 'ò', 'ô', 'b', 'à', 'ř']

collapseWhitespace()

修剪字符串，并将连续的空白字符替换为单个空格。这包括制表符和换行符，以及多字节空白字符，如细空格和表意空间。

s('   Ο     συγγραφέας  ')->collapseWhitespace(); // 'Ο συγγραφέας'

contains(string $needle [, boolean $caseSensitive = true ])

如果字符串包含$needle，则返回true，否则返回false。默认情况下，比较是区分大小写的，但可以通过将$caseSensitive设置为false来进行不区分大小写的比较。

s('Ο συγγραφέας είπε')->contains('συγγραφέας'); // true

containsAll(array $needles [, boolean $caseSensitive = true ])

如果字符串包含所有$needles，则返回true，否则返回false。默认情况下，比较是区分大小写的，但可以通过将$caseSensitive设置为false来进行不区分大小写的比较。

s('foo & bar')->containsAll(['foo', 'bar']); // true

containsAny(array $needles [, boolean $caseSensitive = true ])

如果字符串包含任何$needles，则返回true，否则返回false。默认情况下，比较是区分大小写的，但可以通过将$caseSensitive设置为false来进行不区分大小写的比较。

s('str contains foo')->containsAny(['foo', 'bar']); // true

countSubstr(string $substring [, boolean $caseSensitive = true ])

返回给定字符串中$substring出现的次数。默认情况下，比较是区分大小写的，但可以通过将$caseSensitive设置为false来进行不区分大小写的比较。

s('Ο συγγραφέας είπε')->countSubstr('α'); // 2

dasherize()

返回一个由破折号分隔的、小写且修剪过的字符串。破折号插入在字符串的第一个字符（例外）之前的大写字母之前，以及空格和下划线代替的地方。

s('fooBar')->dasherize(); // 'foo-bar'

delimit(int $delimiter)

返回一个由给定分隔符分隔的、小写且修剪过的字符串。分隔符插入在字符串的第一个字符（例外）之前的大写字母之前，以及空格、破折号和下划线代替的地方。alpha分隔符不会被转换为小写。

s('fooBar')->delimit('::'); // 'foo::bar'

endsWith(string $substring [, boolean $caseSensitive = true ])

如果字符串以$substring结束，则返回true，否则返回false。默认情况下，比较是区分大小写的，但可以通过将$caseSensitive设置为false来进行不区分大小写的比较。

s('fòôbàř')->endsWith('bàř'); // true

endsWithAny(string[] $substrings [, boolean $caseSensitive = true ])

如果字符串以任何$substrings结束，则返回true，否则返回false。默认情况下，比较是区分大小写的，但可以通过将$caseSensitive设置为false来进行不区分大小写的比较。

s('fòôbàř')->endsWithAny(['bàř', 'baz']); // true

确保左端包含(string $substring)

确保字符串以$substring开始。如果没有，则在其前添加。

s('foobar')->ensureLeft('http://'); // 'http://foobar'

确保右端包含(string $substring)

确保字符串以$substring结束。如果没有，则在其后添加。

s('foobar')->ensureRight('.com'); // 'foobar.com'

first(int $n)

返回字符串的前$n个字符。

s('fòôbàř')->first(3); // 'fòô'

getEncoding()

返回Stringy对象使用的编码。

s('fòôbàř')->getEncoding(); // 'UTF-8'

hasLowerCase()

如果字符串包含小写字符，则返回true，否则返回false。

s('fòôbàř')->hasLowerCase(); // true

hasUpperCase()

如果字符串包含大写字符，则返回true，否则返回false。

s('fòôbàř')->hasUpperCase(); // false

htmlDecode()

将所有HTML实体转换为相应的字符。是html_entity_decode的别名。有关标志列表，请参阅https://php.ac.cn/manual/en/function.html-entity-decode.php

s('&amp;')->htmlDecode(); // '&'

htmlEncode()

将所有相关字符转换为HTML实体。是htmlentities的别名。有关标志列表，请参阅https://php.ac.cn/manual/en/function.htmlentities.php

s('&')->htmlEncode(); // '&amp;'

humanize()

将字符串的第一个单词首字母大写，将下划线替换为空格，并删除'_id'。

s('author_id')->humanize(); // 'Author'

indexOf(string $needle [, $offset = 0 ]);

返回$needle在字符串中第一次出现的索引，如果未找到则返回false。接受一个可选的偏移量，从该偏移量开始搜索。负索引从字符串末尾开始搜索

s('string')->indexOf('ing'); // 3

indexOfLast(string $needle [, $offset = 0 ]);

返回$needle在字符串中最后一次出现的索引，如果未找到则返回false。接受一个可选的偏移量，从该偏移量开始搜索。偏移量可以是负数，从字符串的最后一个字符开始计数。

s('foobarfoo')->indexOfLast('foo'); // 10

insert(int $index, string $substring)

将$substring插入到字符串中提供的索引处。

s('fòôbř')->insert('à', 4); // 'fòôbàř'

isAlpha()

如果字符串只包含字母字符，则返回true，否则返回false。

s('丹尼爾')->isAlpha(); // true

isAlphanumeric()

如果字符串只包含字母和数字字符，则返回true，否则返回false。

s('دانيال1')->isAlphanumeric(); // true

isBase64()

如果字符串是base64编码的，则返回true，否则返回false。

s('Zm9vYmFy')->isBase64(); // true

isBlank()

如果字符串只包含空白字符，则返回true，否则返回false。

s("\n\t  \v\f")->isBlank(); // true

isHexadecimal()

如果字符串只包含十六进制字符，则返回true，否则返回false。

s('A102F')->isHexadecimal(); // true

isJson()

如果字符串是JSON，则返回true，否则返回false。与PHP 5.x中的json_decode不同，此方法与PHP 7和其他JSON解析器一致，空字符串不被视为有效的JSON。

s('{"foo":"bar"}')->isJson(); // true

isLowerCase()

如果字符串只包含小写字符，则返回true，否则返回false。

s('fòôbàř')->isLowerCase(); // true

isSerialized()

如果字符串是序列化的，则返回true，否则返回false。

s('a:1:{s:3:"foo";s:3:"bar";}')->isSerialized(); // true

isUpperCase()

如果字符串只包含大写字符，则返回true，否则返回false。

s('FÒÔBÀŘ')->isUpperCase(); // true

last(int $n)

返回字符串的最后$n个字符。

s('fòôbàř')->last(3); // 'bàř'

length()

返回字符串的长度。是PHP的mb_strlen()函数的别名。

s('fòôbàř')->length(); // 6

lines()

按换行符和回车符分割，返回一个Stringy对象数组，对应字符串中的行。

s("fòô\r\nbàř\n")->lines(); // ['fòô', 'bàř', '']

longestCommonPrefix(string $otherStr)

返回字符串和$otherStr之间的最长公共前缀。

s('foobar')->longestCommonPrefix('foobaz'); // 'fooba'

longestCommonSuffix(string $otherStr)

返回字符串和$otherStr之间的最长公共后缀。

s('fòôbàř')->longestCommonSuffix('fòrbàř'); // 'bàř'

longestCommonSubstring(string $otherStr)

返回字符串和$otherStr之间的最长公共子串。在出现平局时，返回第一个出现的那个。

s('foobar')->longestCommonSubstring('boofar'); // 'oo'

lowerCaseFirst()

将提供的字符串的第一个字符转换为小写。

s('Σ foo')->lowerCaseFirst(); // 'σ foo'

pad(int $length [, string $padStr = ' ' [, string $padType = 'right' ]])

使用 $padStr 将字符串填充到指定的长度。如果长度小于或等于字符串长度，则不进行填充。默认的填充字符串是空格，默认类型（'left'、'right'、'both' 中的一个）是 'right'。如果 $padType 不是这 3 个值之一，则抛出 InvalidArgumentException。

s('fòôbàř')->pad(9, '-/', 'left'); // '-/-fòôbàř'

padBoth(int $length [, string $padStr = ' ' ])

返回一个具有给定长度的字符串，字符串的两端都被填充。这是 pad() 函数，$padType 为 'both' 的别名。

s('foo bar')->padBoth(9, ' '); // ' foo bar '

padLeft(int $length [, string $padStr = ' ' ])

返回一个具有给定长度的字符串，字符串的开头被填充。这是 pad() 函数，$padType 为 'left' 的别名。

s('foo bar')->padLeft(9, ' '); // '  foo bar'

padRight(int $length [, string $padStr = ' ' ])

返回一个具有给定长度的字符串，字符串的末尾被填充。这是 pad() 函数，$padType 为 'right' 的别名。

s('foo bar')->padRight(10, '_*'); // 'foo bar_*_'

prepend(string $string)

返回一个以 $string 开始的新字符串。

s('bàř')->prepend('fòô'); // 'fòôbàř'

regexReplace(string $pattern, string $replacement [, string $options = 'msr'])

用 $replacement 替换 $str 中所有出现的 $pattern。这是 mb_ereg_replace() 的别名。注意，mb_ereg_replace() 中多字节模式的 'i' 选项在 PHP 5.6+ 中才能正确工作，这是由于 PHP < 5.6 中捆绑的 Oniguruma 版本不支持，以及 HHVM（3.8 及以下版本）当前版本不支持。

s('fòô ')->regexReplace('f[òô]+\s', 'bàř'); // 'bàř'
s('fò')->regexReplace('(ò)', '\\1ô'); // 'fòô'

removeLeft(string $substring)

返回一个新字符串，如果存在，则移除前缀 $substring。

s('fòôbàř')->removeLeft('fòô'); // 'bàř'

removeRight(string $substring)

返回一个新字符串，如果存在，则移除后缀 $substring。

s('fòôbàř')->removeRight('bàř'); // 'fòô'

repeat(int $multiplier)

返回一个给定倍数的重复字符串。这是 str_repeat 的别名。

s('α')->repeat(3); // 'ααα'

replace(string $search, string $replacement)

替换 $str 中所有出现的 $search。

s('fòô bàř fòô bàř')->replace('fòô ', ''); // 'bàř bàř'

reverse()

返回一个反转的字符串。这是 multibyte 版本的 strrev()。

s('fòôbàř')->reverse(); // 'řàbôòf'

safeTruncate(int $length [, string $substring = '' ])

截断字符串到指定的长度，同时确保它不会分割单词。如果提供了 $substring，并且在截断发生时，字符串将进一步截断，以便子字符串可以被附加，而不超过所需的长度。

s('What are your plans today?')->safeTruncate(22, '...');
// 'What are your plans...'

shuffle()

一个多字节 str_shuffle() 函数。它返回一个字符顺序随机的字符串。

s('fòôbàř')->shuffle(); // 'àôřbòf'

slugify([, string $replacement = '-' [, string $language = 'en']])

将字符串转换为 URL 别名。这包括将非 ASCII 字符替换为其最接近的 ASCII 等效字符，删除剩余的非 ASCII 和非字母数字字符，并用 $replacement 替换空格。默认替换为一个短划线，并且字符串也将转换为小写。也可以提供源字符串的语言，以进行特定语言的重写。

s('Using strings like fòô bàř')->slugify(); // 'using-strings-like-foo-bar'

slice(int $start [, int $end ])

返回从 $start 开始的子字符串，直到但不包括由 $end 指定的索引。如果省略 $end，则提取剩余的字符串。如果 $end 为负，则从字符串的末尾计算。

s('fòôbàř')->slice(3, -1); // 'bà'

split(string $pattern [, int $limit ])

使用提供的正则表达式分割字符串，返回一个包含 Stringy 对象的数组。可选整数 $limit 将截断结果。

s('foo,bar,baz')->split(',', 2); // ['foo', 'bar']

startsWith(string $substring [, boolean $caseSensitive = true ])

如果字符串以 $substring 开头返回 true，否则返回 false。默认情况下，比较是区分大小写的，但可以通过将 $caseSensitive 设置为 false 来使比较不区分大小写。

s('FÒÔbàřbaz')->startsWith('fòôbàř', false); // true

startsWithAny(string[] $substrings [, boolean $caseSensitive = true ])

如果字符串以 $substrings 中的任何一个开头返回 true，否则返回 false。默认情况下，比较是区分大小写的，但可以通过将 $caseSensitive 设置为 false 来使比较不区分大小写。

s('FÒÔbàřbaz')->startsWithAny(['fòô', 'bàř'], false); // true

stripWhitespace()

删除所有空白字符。这包括制表符和换行符，以及多字节空白字符，如细空格和表意文字空格。

s('   Ο     συγγραφέας  ')->stripWhitespace(); // 'Οσυγγραφέας'

substr(int $start [, int $length ])

从起始位置 $start 开始，返回指定长度的子字符串。与 mb_substr() 函数不同，如果提供 $length 为 null，则返回字符串的其余部分，而不是空字符串。

s('fòôbàř')->substr(2, 3); // 'ôbà'

surround(string $substring)

用给定的子字符串包围一个字符串。

s(' ͜ ')->surround('ʘ'); // 'ʘ ͜ ʘ'

swapCase()

返回字符串的大小写互换版本。

s('Ντανιλ')->swapCase(); // 'νΤΑΝΙΛ'

tidy()

返回一个字符串，其中将 Windows-1252（常用于 Word 文档）中的智能引号、省略号字符和破折号替换为其 ASCII 等价物。

s('“I see…”')->tidy(); // '"I see..."'

titleize([, array $ignore])

返回一个修剪后的字符串，每个单词的首字母都大写。也可以接受一个数组，$ignore，允许您列出不进行大写的单词。

$ignore = ['at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the'];
s('i like to watch television')->titleize($ignore);
// 'I Like to Watch Television'

toAscii([, string $language = 'en' [, bool $removeUnsupported = true ]])

返回字符串的 ASCII 版本。一组非 ASCII 字符被替换为其最近的 ASCII 对应字符，其余字符默认情况下将被删除。可以提供源字符串的语言或区域设置，用于以下格式的语言特定转写：en、en_GB 或 en-GB。例如，传递 "de" 结果是 "äöü" 映射到 "aeoeue"，而不是其他语言中的 "aou"。

s('fòôbàř')->toAscii(); // 'foobar'
s('äöü')->toAscii(); // 'aou'
s('äöü')->toAscii('de'); // 'aeoeue'

toBoolean()

返回给定逻辑字符串值的布尔表示。例如，'true'、'1'、'on' 和 'yes' 将返回 true。'false'、'0'、'off' 和 'no' 将返回 false。在所有情况下，忽略大小写。对于其他数字字符串，它们的符号将确定返回值。此外，仅由空白组成的空白字符串将返回 false。对于所有其他字符串，返回值是布尔转换的结果。

s('OFF')->toBoolean(); // false

toLowerCase()

将字符串中的所有字符转换为小写。是 PHP 的 mb_strtolower() 的别名。

s('FÒÔBÀŘ')->toLowerCase(); // 'fòôbàř'

toSpaces([, tabLength = 4 ])

将字符串中的每个制表符转换为定义的 $tabLength 个空格。默认情况下，每个制表符转换为 4 个连续空格。

s(' String speech = "Hi"')->toSpaces(); // '    String speech = "Hi"'

toTabs([, tabLength = 4 ])

将定义的 $tabLength 个连续空格转换为制表符。默认情况下，每个 4 个连续空格转换为制表符。

s('    fòô    bàř')->toTabs();
// '   fòô bàř'

toTitleCase()

将字符串中每个单词的首字母转换为大写。

s('fòô bàř')->toTitleCase(); // 'Fòô Bàř'

toUpperCase()

将字符串中的所有字符转换为大写。是 PHP 的 mb_strtoupper() 的别名。

s('fòôbàř')->toUpperCase(); // 'FÒÔBÀŘ'

trim([, string $chars])

返回一个字符串，从字符串的开始和结束处移除了空白。支持移除 unicode 空白。接受一个可选的字符字符串，用于替换默认值。

s('  fòôbàř  ')->trim(); // 'fòôbàř'

trimLeft([, string $chars])

返回一个字符串，从字符串的开始处移除了空白。支持移除 unicode 空白。接受一个可选的字符字符串，用于替换默认值。

s('  fòôbàř  ')->trimLeft(); // 'fòôbàř  '

trimRight([, string $chars])

返回一个字符串，从字符串的结束处移除了空白。支持移除 unicode 空白。接受一个可选的字符字符串，用于替换默认值。

s('  fòôbàř  ')->trimRight(); // '  fòôbàř'

truncate(int $length [, string $substring = '' ])

截断字符串到指定长度。如果提供了 $substring，并且在截断发生时，字符串将进一步截断，以便子字符串可以附加而不会超过所需的长度。

s('What are your plans today?')->truncate(19, '...'); // 'What are your pl...'

underscored()

返回一个由下划线分隔的、小写和修剪过的字符串。在字符串的开头插入下划线，在空格和破折号之前插入下划线。

s('TestUCase')->underscored(); // 'test_u_case'

upperCamelize()

返回一个 UpperCamelCase 版本的字符串。修剪周围的空格，在数字、空格、破折号和下划线后的字母大写，并移除空格、破折号和下划线。

s('Upper Camel-Case')->upperCamelize(); // 'UpperCamelCase'

upperCaseFirst()

将提供的字符串的第一个字符转换为大写。

s('σ foo')->upperCaseFirst(); // 'Σ foo'

扩展

以下是一个扩展 Stringy 的库列表

SliceableStringy：PHP中的类似Python的字符串切片
SubStringy：高级子字符串方法

测试

从项目目录下，可以使用 phpunit 运行测试

许可证

采用MIT许可证发布 - 详细信息请参阅 LICENSE.txt

statamic / stringy

维护者

详细信息