README

PHP标准库的尝试。

简介

PHP 内置函数因其不一致性而闻名：命名不一致、参数顺序不一致、错误处理不一致：有时返回 false，有时触发错误，有时抛出异常，有时是这些的组合。该库的主要目的是提供一个一致的、面向对象的包装，围绕 PHP 本地函数，内部处理不一致性，以对外暴露更清晰的 API。希望 PHP 有朝一日能完成这项工作；同时，这个项目是填补这一空白的谦卑尝试。

该库将从小处着手。根据需求增加功能。欢迎贡献。

项目状态 & 发布流程

当前版本号为 0.x.y。当引入非破坏性变更（添加新方法、优化现有代码等）时，y 将递增。

当引入破坏性变更时，总是开始一个新的 0.x 版本周期。

因此，将项目锁定到特定的发布周期，如 0.3.* 是安全的。

如果您需要升级到新的发布周期，请查看发布历史以了解每个后续 0.x.0 版本引入的变更列表。

安装

此库可通过 Composer 安装。

composer require brick/std

要求

此库需要 PHP 7.2 或更高版本。

概述

IO

通过 FileSystem 类的静态方法提供文件 I/O 功能。所有方法在失败时都会抛出 IoException。

该类的最终目标将是为特定情况抛出细粒度的异常（文件已存在、目标是一个目录等），但这需要分析 PHP 错误消息，使库容易受到更改的影响，并且/或者连续调用多个内部文件系统函数，使大多数操作非原子化。这两种方法都存在潜在的严重缺点。欢迎提出想法和评论。

方法列表

• copy() 复制文件。
• move() 移动文件或目录。
• delete() 删除文件。
• createDirectory() 创建目录。
• createDirectories() 通过首先创建所有不存在的父目录来创建目录。
• exists() 检查文件或目录是否存在。
• isFile() 检查路径是否指向常规文件。
• isDirectory() 检查路径是否指向目录。
• isSymbolicLink() 检查路径是否指向符号链接。
• createSymbolicLink() 创建指向目标的符号链接。
• createLink() 创建指向现有文件的硬链接。
• readSymbolicLink() 返回符号链接的目标。
• getRealPath() 返回规范化的绝对路径名。
• write() 将数据写入文件。
• read() 从文件中读取数据。

迭代器

该库附带两个方便的用于 CSV 文件的迭代器

CsvFileIterator

此迭代器遍历 CSV 文件，默认返回索引数组

use Brick\Std\Iterator\CsvFileIterator;

// 1,Bob,New York
// 2,John,Los Angeles
$users = new CsvFileIterator('users.csv');

foreach ($users as [$id, $name, $city]) {
    // ...
}

它还可以读取包含列名的文件的第一行，并使用这些列名返回一个关联数组。

use Brick\Std\Iterator\CsvFileIterator;

// id,name,city
// 1,Bob,New York
// 2,John,Los Angeles
$users = new CsvFileIterator('users.csv', true);

foreach ($users as $user) {
    // $user['id'], $user['name'], $user['city']
}

构造函数可以提供分隔符、定界符和转义字符。

CsvJsonFileIterator

该迭代器遍历一个字段被JSON编码的CSV文件。

use Brick\Std\Iterator\CsvJsonFileIterator;

// 1,"Bob",["John","Mike"]
// 2,"John",["Bob","Brad"]
$users = new CsvJsonFileIterator('users.csv');

foreach ($users as [$id, $name, $friends]) {
    // $id is an int
    // $name is a string
    // $friends is an array
}

JSON编码的字段不得包含换行符。

JSON

JSON功能由JsonEncoder和JsonDecoder提供。选项通过编码器/解码器的显式方法设置。如果发生错误，将抛出JsonException异常。

编码

use Brick\Std\Json\JsonEncoder;

$encoder = new JsonEncoder();
$encoder->forceObject(true);

$encoder->encode(['Hello World']); // '{"0":"Hello World"}'
$encoder->encode(tmpfile()); // Brick\Std\Json\JsonException: Type is not supported

解码

use Brick\Std\Json\JsonDecoder;

$decoder = new JsonDecoder();
$decoder->decodeObjectAsArray(true);

$decoder->decode('{"hello":"world"}'); // ['hello' => 'world']
$decoder->decode('{hello}'); // Brick\Std\Json\JsonException: Syntax error