README

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.5.*.

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 8.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