brick / Std
Brick\Std
An attempt at a standard library for PHP.
Introduction
The PHP internal functions are notorious for their inconsistency: inconsistent naming, inconsistent parameter order, inconsistent error handling: sometimes returning false
, sometimes triggering an error, sometimes throwing an exception, and sometimes a mix of these.
The aim of this library is mainly to provide a consistent, object-oriented wrapper around PHP native functions, that deals with inconsistencies internally to expose a cleaner API externally.
Hopefully PHP will do this job one day; in the meantime, this project is a humble attempt to fill the gap.
The library will start small. Functionality will be added as needs arise. Contributions are welcome.
Project status & release process
The current releases are numbered 0.x.y
. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), y
is incremented.
When a breaking change is introduced, a new 0.x
version cycle is always started.
It is therefore safe to lock your project to a given release cycle, such as 0.3.*
.
If you need to upgrade to a newer release cycle, check the release history
for a list of changes introduced by each further 0.x.0
version.
Installation
This library is installable via Composer:
composer require brick/std
Requirements
This library requires PHP 7.2 or later.
Overview
IO
File I/O functionality is provided via static methods in the FileSystem class. All methods throw an IoException on failure.
The ultimate aim of this class would be to throw fine-grained exceptions for specific cases (file already exists, destination is a directory, etc.) but this would require to analyze PHP error messages, making the library fragile to changes, and/or call several internal filesystem functions in a row, making most of the operations non-atomic. Both approaches have potentially serious drawbacks. Ideas and comments welcome.
Method list:
-
copy()
Copies a file. -
move()
Moves a file or a directory. -
delete()
Deletes a file. -
createDirectory()
Creates a directory. -
createDirectories()
Creates a directory by creating all nonexistent parent directories first. -
exists()
Checks whether a file or directory exists. -
isFile()
Checks whether the path points to a regular file. -
isDirectory()
Checks whether the path points to a directory. -
isSymbolicLink()
Checks whether the path points to a symbolic link. -
createSymbolicLink()
Creates a symbolic link to a target. -
createLink()
Creates a hard link to an existing file. -
readSymbolicLink()
Returns the target of a symbolic link. -
getRealPath()
Returns the canonicalized absolute pathname. -
write()
Writes data to a file. -
read()
Reads data from a file.
Iterator
The library ships with two handy iterator for CSV files:
CsvFileIterator
This iterator iterates over a CSV file, and returns an indexed array by default:
use Brick\Std\Iterator\CsvFileIterator;
// 1,Bob,New York
// 2,John,Los Angeles
$users = new CsvFileIterator('users.csv');
foreach ($users as [$id, $name, $city]) {
// ...
}
It can also read the first line of the file that contains column names, and use them to return an associative array:
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']
}
Delimiter, enclosure and escape characters can be provided to the constructor.
CsvJsonFileIterator
This iterator iterates over a CSV file whose fields are JSON-encoded:
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
}
The JSON-encoded fields must not contain newline characters.
JSON
JSON functionality is provided by JsonEncoder and JsonDecoder. Options are set on the encoder/decoder instance, via explicit methods. If an error occurs, a JsonException is thrown.
Encoding:
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
Decoding:
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