下面我把 PHP 的 str_pad 函数做详尽说明，包含语法、参数、返回值、常见用例、注意事项和性能提示。

函数概述

str_pad 用于将字符串填充到指定长度，支持在左侧、右侧或两侧填充指定的字符串（默认填充空格）。

语法

php
str_pad(string $input, int $pad_length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT): string

参数

• $input：要被填充的原始字符串（会先被转换为字符串）。

• $pad_length：目标长度（以字符数计）。

• 若为正数：表示目标总长度。

• 若目标长度小于或等于原字符串长度，则函数返回原始字符串（不会截断）。

• 若为负数（PHP 8.0+ 支持负数）：表示相对于原字符串的长度偏移（更常见的是不使用负数）。

• $pad_string：用于填充的字符串，默认为空格 " "。

• 如果填充字符串长度大于 1，会按需重复并截断以适配所需填充长度（截断发生在尾端）。

• 若 $pad_string 为空字符串 ""，则 PHP 会抛出一个警告并返回原字符串（从 PHP 8.0 开始会抛出 Warning）。不要传空字符串。

• $pad_type：填充方向，三个可选常量：

• STR_PAD_RIGHT（默认）：在字符串右侧填充。

• STR_PAD_LEFT：在字符串左侧填充。

• STR_PAD_BOTH：两侧填充，奇数个填充字符时左侧比右侧多一个填充字符（PHP 行为：左侧优先添加多余的字符）。

返回值

返回填充后的字符串（长度至少为 $pad_length，除非有错误或 $pad_length <= 原长度）。

示例

1. 右侧填充（默认）

php
echo str_pad("apple", 10);           // "apple     "（5 个空格）
echo str_pad("apple", 10, ".");      // "apple....."

2. 左侧填充

php
echo str_pad("42", 5, "0", STR_PAD_LEFT); // "00042"

3. 两侧填充

php
echo str_pad("cat", 8, "-=", STR_PAD_BOTH); // "-=cat-=-"  解释：目标填充长度为 5，填充串 "-=" 重复并截断

4. 非对称填充示例（奇数需分配）

php
echo str_pad("x", 4, "ab", STR_PAD_BOTH); // "abx a" 实际结果："abxa"?
// 更准确的演示：
echo str_pad("x", 5, "ab", STR_PAD_BOTH); // "abxab"

5. 保持原样（目标长度小于等于原长度）

php
echo str_pad("longstring", 5, "*"); // "longstring"

6. 与数字结合（会先转换为字符串）

php
echo str_pad(123, 6, "0", STR_PAD_LEFT); // "000123"

内部细节与行为

• 填充以字符为单位（对多字节字符如 UTF-8，str_pad 按字节而非字符长度工作，因为它是字节级的字符串函数）。若处理多字节字符，请配合 mb_* 函数或先使用 mb_strlen/mb_substr，或者手动构造填充逻辑。

• 当 $pad_string 的长度不整除所需填充长度时，最后一段会被截断以精确匹配所需数量。

• PHP 7 及更早版本不支持负的 $pad_length（PHP 8 开始允许负数以表示相对行为，但这种用法不常见且需谨慎）。

• 如果传入非字符串类型，PHP 会尝试转换为字符串（例如 null -> ""，int -> 数字字符等）。

常见用途

• 固定宽度输出（日志、表格对齐）。

• 生成固定位数的数字验证码（结合 random_int，并用 STR_PAD_LEFT 和 0 填充）。

• 格式化序列号、订单号（例如 "INV000123"）。

• 在模板中创建占位符或装饰文本。

示例：生成 6 位数字验证码（允许以 0 开头）

php
$code = str_pad((string)random_int(0, 999999), 6, '0', STR_PAD_LEFT);

注意事项与最佳实践

• 若处理 Unicode 可读字符长度，应使用 mb_ 系列函数；否则多字节字符会导致长度/截断错位。

• 对安全敏感的随机值使用 random_int 而非 mt_rand。

• 避免将 $pad_string 设为空字符串。

• 对性能敏感的场景（大量短字符串频繁填充），str_pad 本身开销很小，但应避免不必要的重复调用或在循环中进行复杂转换。

小结

str_pad 是一个简单且常用的函数，用于在左右或两侧填充字符串以达成固定长度。注意多字节字符处理、填充字符串为空的情况以及选择合适的填充方向和填充字符串即可满足多数需求。

如需，我可以给出针对 UTF-8 多字节安全的替代实现或示例代码。