Skip to content

API.md

Latest commit

 

History

History
529 lines (290 loc) · 8.43 KB

API.md

File metadata and controls

529 lines (290 loc) · 8.43 KB
Raw

API Reference

dogeow/php-helpers 的 API 文档按模块分组整理在这里。

目录

Arr

Arr::combinationOfTwoNumbers(array $array): array

返回数组中不重复的两两组合。

参数:

  • $array: 输入数组。

返回:

  • array: 形如 [['a', 'b'], ['a', 'c'], ['b', 'c']] 的组合结果。

说明:

  • 不会生成 ['a', 'b'] 和 ['b', 'a'] 两份。
  • 不会把同一个元素和自己组合。

示例:

Arr::combinationOfTwoNumbers(['a', 'b', 'c']);
// [['a', 'b'], ['a', 'c'], ['b', 'c']]

Arr::isInTwoDimensionalArray(array $array, array $item): bool

判断二维数组中是否存在与目标数组严格相等的一项。

参数:

  • $array: 二维数组。
  • $item: 要匹配的数组项。

返回:

  • bool

说明:

  • 使用严格相等比较，顺序不同视为不同数组。

Str

Str::bytesForHuman(string $size, int $base = 1024, string $delimiter = ''): string

把字节数字符串格式化为可读大小。

参数:

  • $size: 非负整数字符串，例如 '1024'。
  • $base: 进位基数，常用 1024 或 1000。
  • $delimiter: 数字和单位之间的分隔符。

返回:

  • string

异常:

  • InvalidArgumentException: 当 $size 不是非负整数字符串，或 $base <= 1。

示例:

Str::bytesForHuman('5200'); // 5.08KB
Str::bytesForHuman('1536', 1024, ' '); // 1.5 KB

Str::baseConvert(string $number, string $targetBit): string

把十进制非负整数字符串转换为目标进制字符串。

参数:

  • $number: 非负整数字符串。
  • $targetBit: 目标进制字符串，范围 2 到 36。

返回:

  • string

异常:

  • InvalidArgumentException: 输入格式非法，或目标进制不在 2..36。

示例:

Str::baseConvert('10', '36'); // A

Str::rgb2Hex(int $r, int $g = -1, int $b = -1): string

把 RGB 值转换为十六进制颜色。

参数:

  • $r, $g, $b: 颜色通道值，超出范围会被截断到 0..255。

返回:

  • string: 例如 #ff0000

Str::getMainColor(string $imgUrl, bool $isHex): string

获取图片平均主色。

参数:

  • $imgUrl: 本地路径或可读取的图片路径。
  • $isHex: true 返回十六进制颜色，false 返回 rgb(r, g, b)。

返回:

  • string

说明:

  • 实际委托给 Image::getMainColor()。
  • 读取失败时返回黑色默认值。

Str::getTitle(string $url): string|false

读取 URL 或文件内容并提取 <title>。

参数:

  • $url: 可被 file_get_contents() 读取的地址或路径。

返回:

  • string|false: 成功返回标题，失败或无标题时返回 false。

Str::getStringBetween(string $string, string $start, string $end): string

截取两个边界之间的内容。

参数:

  • $string: 原字符串。
  • $start: 开始边界。
  • $end: 结束边界。

返回:

  • string

说明:

  • 任一边界不存在时返回空字符串。
  • 返回结果不包含开始和结束边界本身。

Str::filterEmoji(string $str): string

移除常见 emoji 和符号字符。

参数:

  • $str: 输入字符串。

返回:

  • string

Str::birthdayToConstellation(string $birthday): string

根据生日字符串返回星座。

参数:

  • $birthday: 可被 strtotime() 解析的日期字符串。

返回:

  • string

说明:

  • 解析失败时返回空字符串。

Html

Html::br2nl(string $input): string

把 HTML 中的 <br> 标签转换成换行符。

参数:

  • $input: HTML 字符串。

返回:

  • string

说明:

  • 会先做 htmlspecialchars_decode()。
  • 会移除原始 \r 和 \n 后再替换 <br>。

Html::extractTitle(string $html): string

从 HTML 字符串中提取 <title> 内容。

参数:

  • $html: HTML 字符串。

返回:

  • string

说明:

  • 未匹配到标题时返回空字符串。

Html::extractFavicon(string $html, string $url): string

从 HTML 中提取 favicon 地址，并归一化为完整 URL。

参数:

  • $html: HTML 字符串。
  • $url: 当前页面 URL，用于补全相对地址。

返回:

  • string

说明:

  • 支持 rel="icon" 和 rel="shortcut icon"。
  • 找不到时返回当前站点默认 /favicon.ico。

Url

Url::normalizeHttpUrl(string $url): string

为缺少协议的地址补上 https://。

参数:

  • $url: URL 字符串。

返回:

  • string

示例:

Url::normalizeHttpUrl('example.com'); // https://example.com

Url::normalizeFaviconUrl(string $favicon, string $baseUrl): string

把 favicon 地址归一化为完整 URL。

参数:

  • $favicon: favicon 地址，支持绝对 URL、协议相对 URL、绝对路径、相对路径。
  • $baseUrl: 页面 URL。

返回:

  • string

Url::defaultFaviconUrl(string $url): string

返回站点默认 favicon 地址。

参数:

  • $url: 页面 URL。

返回:

  • string

示例:

Url::defaultFaviconUrl('https://example.com/page');
// https://example.com/favicon.ico

File

File::formatBytes(int|float $bytes): string

把字节数格式化为带单位的字符串。

参数:

  • $bytes: 字节数，负数按 0 处理。

返回:

  • string

示例:

File::formatBytes(1536); // 1.5 KB

File::getSize(string $filePath): int|false

获取文件大小。

参数:

  • $filePath: 文件路径。

返回:

  • int|false: 文件存在时返回字节数，否则返回 false。

File::getFormattedSize(string $filePath): string

获取文件可读大小。

参数:

  • $filePath: 文件路径。

返回:

  • string

说明:

  • 文件不存在时返回 '0 B'。

File::isValid(string $filePath): bool

判断路径是否存在、可读、且大小大于 0。

参数:

  • $filePath: 文件或目录路径。

返回:

  • bool

说明:

  • 对目录同样会基于 filesize() 结果进行判断。

File::ensureDirectoryExists(string $directoryPath, int $permissions = 0755): bool

确保目录存在，不存在时递归创建。

参数:

  • $directoryPath: 目录路径。
  • $permissions: 创建权限。

返回:

  • bool

Image

Image::getMainColor(string $imgPath, bool $asHex = true): string

获取图片平均主色。

参数:

  • $imgPath: 图片路径。
  • $asHex: true 返回十六进制，false 返回 rgb(...)。

返回:

  • string

说明:

  • 读取失败、格式不支持或 GD 无法创建图片资源时，返回黑色默认值。

Image::rgbToHex(int $r, int $g, int $b): string

把 RGB 转为十六进制颜色。

参数:

  • $r, $g, $b: 颜色通道值，超出范围会截断到 0..255。

返回:

  • string

CharLength

CharLength::calculate(string $text): int

按自定义规则计算字符长度。

参数:

  • $text: 输入文本。

返回:

  • int

规则:

  • 中文字符记 2
  • emoji 记 2
  • 数字、字母、普通符号、空格记 1
  • 国旗 emoji 这种双 code point 组合按 2 计

CharLength::exceedsMax(string $text, int $maxLength): bool

参数:

  • $text: 输入文本。
  • $maxLength: 最大允许长度。

返回:

  • bool

CharLength::belowMin(string $text, int $minLength): bool

参数:

  • $text: 输入文本。
  • $minLength: 最小允许长度。

返回:

  • bool

Live

Live::getPhoneOperator(int|string $number): string

判断中国大陆手机号运营商。

参数:

  • $number: 11 位纯数字手机号。

返回:

  • string: 中国移动、中国联通、中国电信 或 未知

说明:

  • 输入不合法时返回 未知。

Live::isVirtualPhone(int|string $number): bool

判断是否虚拟运营商号码。

参数:

  • $number: 11 位纯数字手机号。

返回:

  • bool

说明:

  • 输入不合法时返回 false。

Preg

Preg::isIp(string $ip): bool

判断字符串是否是合法 IP 地址。

参数:

  • $ip: 输入 IP。

返回:

  • bool

Aliyun

Aliyun::textWatermark(string $text, string $url, array $options = []): string

生成阿里云 OSS 文字水印 URL。

参数:

  • $text: 水印文本。
  • $url: 原图 URL。
  • $options: 可选配置。

支持的 $options:

  • size: 字号，默认 45
  • color: 颜色，默认 FFFFFF
  • opacity: 透明度，默认 50

返回:

  • string

说明:

  • 会先移除文本中的 emoji。
  • 返回结果是带 x-oss-process=image/watermark,... 参数的 URL。