# 文本辅助函数

文本辅助函数文件包含了一系列辅助处理文本的函数。

## 加载辅助函数

使用以下代码加载此辅助函数：

    <?php

    helper('text');

## 可用函数

提供以下函数：

random_string([$type = 'alnum'[, $len = 8]])
  参数:

    - $type (`string`) -- 随机化类型

    - $len (`int`) -- 输出字符串长度

  返回:

    随机字符串

  返回类型:

    `string`

  根据指定的类型和长度生成随机字符串。适用于创建密码或生成随机哈希值。

  第一个参数指定字符串类型，第二个参数指定长度。可选类型如下：

  - alpha: 仅包含大小写字母的字符串。

  - alnum: 包含大小写字母和数字的字母数字字符串。

  - numeric: 数字字符串。

  - nozero: 不含 0 的数字字符串。

  - crypto: 基于 `random_bytes()` 的随机字符串。

  备注

  使用 crypto 时，第二个参数必须设为偶数。自 v4.2.2 起，若设为奇数，将抛出 `InvalidArgumentException` 异常。

  备注

  自 v4.3.3 起，alpha、alnum 和 nozero 使用 `random_byte()`，numeric 使用 `random_int()`。在之前的版本中，这些类型使用的是并非加密安全的 `str_shuffle()`。

  用法示例：

      <?php

      echo random_string('alnum', 16);

increment_string($str[, $separator = '_'[, $first = 1]])
  参数:

    - $str (`string`) -- 输入字符串

    - $separator (`string`) -- 用于追加重复数字的分隔符

    - $first (`int`) -- 起始数字

  返回:

    递增后的字符串

  返回类型:

    `string`

  通过在字符串后追加数字或增加原有数字来递增字符串。适用于创建文件“副本”，或复制具有唯一标题或别名的数据库内容。

  用法示例：

      <?php

      echo increment_string('file', '_'); // "file_1"
      echo increment_string('file', '-', 2); // "file-2"
      echo increment_string('file_4'); // "file_5"

alternator($args)
  参数:

    - $args (`mixed`) -- 可变数量的参数

  返回:

    交替后的字符串

  返回类型:

    `mixed`

  用于在循环中交替使用两个或多个项目。示例：

      <?php

      for ($i = 0; $i < 10; $i++) {
          echo alternator('string one', 'string two');
      }

  可根据需要添加任意数量的参数，每次循环迭代时将返回下一个项目。

      <?php

      for ($i = 0; $i < 10; $i++) {
          echo alternator('one', 'two', 'three', 'four', 'five');
      }

  备注

  若要多次独立调用此函数，只需在调用时不带任何参数即可重新初始化。

reduce_double_slashes($str)
  参数:

    - $str (`string`) -- 输入字符串

  返回:

    格式化斜杠后的字符串

  返回类型:

    `string`

  将字符串中的双斜杠转换为单斜杠，但会忽略 URL 协议前缀（如 http&#58;//）中的双斜杠。

  示例：

      <?php

      $string = 'http://example.com//index.php';
      echo reduce_double_slashes($string); // results in "http://example.com/index.php"

strip_slashes($data)
  参数:

    - $data (`mixed`) -- 输入字符串或字符串数组

  返回:

    移除斜杠后的字符串或数组

  返回类型:

    `mixed`

  移除字符串数组中的所有斜杠。

  示例：

      <?php

      $str = [
          'question' => "Is your name O\\'reilly?",
          'answer'   => "No, my name is O\\'connor.",
      ];

      $str = strip_slashes($str);

  以上代码将返回以下数组：

      <?php

      [
          'question' => "Is your name O'reilly?",
          'answer'   => "No, my name is O'connor.",
      ];

  备注

  出于历史原因，此函数也支持并处理字符串输入。此时，它仅作为 `stripslashes()` 的别名。

reduce_multiples($str[, $character = ', '[, $trim = false]])
  参数:

    - $str (`string`) -- 待搜索文本

    - $character (`string`) -- 待压缩字符

    - $trim (`bool`) -- 是否同时 trim 指定的字符

  返回:

    压缩后的字符串

  返回类型:

    `string`

  压缩连续出现的多个特定字符。示例：

      <?php

      $string = 'Fred, Bill,, Joe, Jimmy';
      $string = reduce_multiples($string); // results in "Fred, Bill, Joe, Jimmy"

  若第三个参数设为 `true`，则会同时移除字符串首尾出现的该字符。示例：

      <?php

      $string = ',Fred, Bill,, Joe, Jimmy,';
      $string = reduce_multiples($string, ',', true); // results in "Fred, Bill, Joe, Jimmy"

quotes_to_entities($str)
  参数:

    - $str (`string`) -- 输入字符串

  返回:

    引号转换为 HTML 实体后的字符串

  返回类型:

    `string`

  将字符串中的单引号和双引号转换为对应的 HTML 实体。示例：

      <?php

      $string = "Joe's \"dinner\"";
      $string = quotes_to_entities($string); // results in "Joe&#39;s &quot;dinner&quot;"

strip_quotes($str)
  参数:

    - $str (`string`) -- 输入字符串

  返回:

    移除引号后的字符串

  返回类型:

    `string`

  移除字符串中的单引号和双引号。示例：

      <?php

      $string = "Joe's \"dinner\"";
      $string = strip_quotes($string); // results in "Joes dinner"

word_limiter($str[, $limit = 100[, $endChar = '&#8230;']])
  参数:

    - $str (`string`) -- 输入字符串

    - $limit (`int`) -- 限制数量

    - $endChar (`string`) -- 结束字符（通常为省略号）

  返回:

    截断后的字符串

  返回类型:

    `string`

  将字符串截断为指定的 单词 数。示例：

      <?php

      $string = 'Here is a nice text string consisting of eleven words.';
      $string = word_limiter($string, 4);
      // Returns:  Here is a nice

  第三个参数是添加到字符串末尾的可选后缀，默认使用省略号。

character_limiter($string[, $limit = 500[, $endChar = '&#8230;']])
  参数:

    - $string (`string`) -- 输入字符串

    - $limit (`int`) -- 字符数

    - $endChar (`string`) -- 结束字符（通常为省略号）

  返回:

    截断后的字符串

  返回类型:

    `string`

  将字符串截断为指定的 字符 数。该函数会保持单词的完整性，因此字符数可能会略多或略少于设定值。

  示例：

      <?php

      $string = 'Here is a nice text string consisting of eleven words.';
      $string = character_limiter($string, 20);
      // Returns:  Here is a nice text string

  第三个参数是添加到字符串末尾的可选后缀。若未声明，则使用省略号。

  备注

  如需截断为精确数量的字符，请参阅下文的 `ellipsize()` 函数。

ascii_to_entities($str)
  参数:

    - $str (`string`) -- 输入字符串

  返回:

    ASCII 值转换为实体后的字符串

  返回类型:

    `string`

  将 ASCII 值转换为字符实体（包括在网页中使用时可能引起问题的扩展 ASCII 和 MS Word 字符）。由此，无论浏览器如何设置都能一致显示，或可靠地存储到数据库中。此函数在一定程度上取决于服务器支持的字符集，因此在某些情况下可能并非 100% 可靠，但在大多数情况下，它能正确识别常规范围之外的字符（如重音字符）。

  示例：

      <?php

      $string = ascii_to_entities($string);

entities_to_ascii($str[, $all = true])
  参数:

    - $str (`string`) -- 输入字符串

    - $all (`bool`) -- 是否也转换不安全实体

  返回:

    HTML 实体转换为 ASCII 字符后的字符串

  返回类型:

    `string`

  此函数功能与 `ascii_to_entities()` 相反，负责将字符实体转回 ASCII。

convert_accented_characters($str)
  参数:

    - $str (`string`) -- 输入字符串

  返回:

    重音字符转换后的字符串

  返回类型:

    `string`

  将高位 ASCII 字符音译为对应的低位 ASCII 字符。适用于必须使用标准 ASCII 字符的场景（如 URL）中处理非英语字符。

  示例：

      <?php

      $string = convert_accented_characters($string);

  备注

  此函数使用配套配置文件 app/Config/ForeignCharacters.php 来定义音译所需的转换数组。

word_censor($str, $censored[, $replacement = ''])
  参数:

    - $str (`string`) -- 输入字符串

    - $censored (`array`) -- 待过滤的敏感词列表

    - $replacement (`string`) -- 用于替换敏感词的内容

  返回:

    过滤后的字符串

  返回类型:

    `string`

  用于过滤文本字符串中的词汇。第一个参数为原始字符串，第二个参数为禁用的词汇数组。第三个参数（可选）为替换值。若未指定，敏感词将被替换为井号：####。

  示例：

      <?php

      $disallowed = ['darn', 'shucks', 'golly', 'phooey'];
      $string     = word_censor($string, $disallowed, 'Beep!');

highlight_code($str)
  参数:

    - $str (`string`) -- 输入字符串

  返回:

    经 HTML 高亮处理后的代码字符串

  返回类型:

    `string`

  为代码字符串（PHP、HTML 等）着色。示例：

      <?php

      $string = highlight_code($string);

  此函数使用 PHP 的 `highlight_string()` 函数，因此所用颜色为 php.ini 文件中指定的颜色。

highlight_phrase($str, $phrase[, $tag_open = '<mark>'[, $tag_close = '</mark>']])
  参数:

    - $str (`string`) -- 输入字符串

    - $phrase (`string`) -- 待高亮的短语

    - $tag_open (`string`) -- 用于高亮的起始标签

    - $tag_close (`string`) -- 用于高亮的结束标签

  返回:

    经 HTML 高亮处理后的短语字符串

  返回类型:

    `string`

  高亮文本字符串中的特定短语。第一个参数为原始字符串，第二个参数为待高亮的短语。第三个和第四个参数为包裹短语的 HTML 起始/结束标签。

  示例：

      <?php

      $string = 'Here is a nice text string about nothing in particular.';
      echo highlight_phrase($string, 'nice text', '<span style="color:#990000;">', '</span>');

  以上代码输出:

      Here is a <span style="color:#990000;">nice text</span> string about nothing in particular.

  备注

  此函数以前默认使用 `<strong>` 标签。旧版浏览器可能不支持 HTML5 的 mark 标签。如需支持此类浏览器，建议在样式表中插入以下 CSS 代码

      mark {
          background: #ff0;
          color: #000;
      };

word_wrap($str[, $charlim = 76])
  参数:

    - $str (`string`) -- 输入字符串

    - $charlim (`int`) -- 字符限制

  返回:

    换行处理后的字符串

  返回类型:

    `string`

  在保持单词完整的前提下，按指定的 字符 数对文本进行换行处理。

  示例：

      <?php

      $string = 'Here is a simple string of text that will help us demonstrate this function.';
      echo word_wrap($string, 25);
      /*
       * Would produce:
       * Here is a simple string
       * of text that will help us
       * demonstrate this
       * function.
       *
       * Excessively long words will be split, but URLs will not be.
       */

ellipsize($str, $max_length[, $position = 1[, $ellipsis = '&hellip;']])
  参数:

    - $str (`string`) -- 输入字符串

    - $max_length (`int`) -- 字符串长度限制

    - $position (`mixed`) -- 分割位置（整数或浮点数）

    - $ellipsis (`string`) -- 用作省略号的字符

  返回:

    省略处理后的字符串

  返回类型:

    `string`

  此函数会从字符串中移除标签，按设定的最大长度截断并插入省略号。

  第一个参数是待处理字符串，第二个参数是最终字符串的字符数。第三个参数决定省略号出现的位置（0 - 1，从左至右）。例如：1 表示省略号在字符串右侧，0.5 表示在中间，0 表示在左侧。

  可选的第四个参数是省略号的类型。默认插入 &hellip;。

  示例：

      <?php

      $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg';
      echo ellipsize($str, 32, .5);

  输出：:

  > this_string_is_e&hellip;ak_my_design.jpg

excerpt($text, $phrase = false, $radius = 100, $ellipsis = '...')
  参数:

    - $text (`string`) -- 待提取摘要的文本

    - $phrase (`string`) -- 用于提取周边文本的核心短语或单词

    - $radius (`int`) -- $phrase 前后的字符数

    - $ellipsis (`string`) -- 用作省略号的字符

  返回:

    文本摘要。

  返回类型:

    `string`

  此函数会提取中心短语 `$phrase` 前后各 `$radius` 个字符，并在首尾添加省略号。

  第一个参数是待提取摘要的文本，第二个参数是用于计算前后长度的核心词或短语。第三个参数是核心短语前后需保留的字符数。若未传递短语，摘要将包含前 `$radius` 个字符并在末尾添加省略号。

  示例：

      <?php

      $text = 'Ut vel faucibus odio. Quisque quis congue libero. Etiam gravida
      eros lorem, eget porttitor augue dignissim tincidunt. In eget risus eget
      mauris faucibus molestie vitae ultricies odio. Vestibulum id ultricies diam.
      Curabitur non mauris lectus. Phasellus eu sodales sem. Integer dictum purus
      ac enim hendrerit gravida. Donec ac magna vel nunc tincidunt molestie sed
      vitae nisl. Cras sed auctor mauris, non dictum tortor. Nulla vel scelerisque
      arcu. Cras ac ipsum sit amet augue laoreet laoreet. Aenean a risus lacus.
      Sed ut tortor diam.';

      echo excerpt($text, 'Donec');

  输出:

      ... non mauris lectus. Phasellus eu sodales sem. Integer dictum purus ac
      enim hendrerit gravida. Donec ac magna vel nunc tincidunt molestie sed
      vitae nisl. Cras sed auctor mauris, non dictum tortor. ...