Psl - PHP Standard Library

Psl is a standard library for PHP, inspired by hhvm/hsl.

The goal of Psl is to provide a consistent, centralized, well-typed set of APIs for PHP programmers.

Example

<?php

declare(strict_types=1);

use Psl\{Str, Vec};

/**
 * @psalm-param iterable<?int> $codes
 */
function foo(iterable $codes): string
{
    $codes = Vec\filter_nulls($codes);

    $chars = Vec\map($codes, fn(int $code): string => Str\chr($code));

    return Str\join($chars, ', ');
}

foo([95, 96, null, 98]);
// 'a, b, d'

Installation

Supported installation method is via composer:

$ composer require azjezz/psl

Psalm Integration

PSL comes with a Psalm plugin, that improves return type for PSL functions that psalm cannot infer from source code.

To enable the Psalm plugin, add the Psl\Integration\Psalm\Plugin class to your psalm configuration file plugins list as follows:

<psalm>
   ...
   <plugins>
      ...
      <pluginClass class="Psl\Integration\Psalm\Plugin" />
   </plugins>
</psalm>

Documentation

You can read through the API documentation in docs/README.md.

Principles

All functions should be typed as strictly as possible
The library should be internally consistent
References may not be used
Arguments should be as general as possible. For example, for array functions, prefer iterable inputs where practical, falling back to array when needed.
Return types should be as specific as possible
All files should contain declare(strict_types=1);

Consistency Rules

This is not exhaustive list.

Functions argument order should be consistent within the library
- All iterable-related functions take the iterable as the first argument ( e.g. Iter\map and Iter\filter )
- $haystack, $needle, and $pattern are in the same order for all functions that take them
Functions should be consistently named.
If an operation can conceivably operate on either keys or values, the default is to operate on the values - the version that operates on keys should have _key suffix (e.g. Iter\last, Iter\last_key, Iter\contains, Iter\contains_key )
Find-like operations that can fail should return ?T; a second function should be added with an x suffix that uses an invariant to return T (e.g. Arr\last, Arr\lastx)
Iterable functions that do an operation based on a user-supplied keying function for each element should be suffixed with _by (e.g. Arr\sort_by, Iter\group_by, Math\max_by)

License

The MIT License (MIT). Please see LICENSE for more information.

4.0 KiB Raw Blame History