2019-12-24 01:52:07 +01:00
# Psl - PHP Standard Library
2021-02-17 21:27:58 +01:00
[](https://travis-ci.com/azjezz/psl)
[](https://coveralls.io/github/azjezz/psl)
2020-03-01 12:01:57 +01:00
[](https://shepherd.dev/github/azjezz/psl)
2020-09-05 02:58:43 +02:00
[](https://insight.symfony.com/projects/1e053a4a-aaab-4a52-9059-c4883bfd46f7)
2019-12-25 20:17:14 +01:00
[](https://packagist.org/packages/azjezz/psl)
[](https://packagist.org/packages/azjezz/psl)
[](https://packagist.org/packages/azjezz/psl)
2019-12-25 19:39:01 +01:00
2019-12-25 20:18:13 +01:00
Psl is a standard library for PHP, inspired by [hhvm/hsl ](https://github.com/hhvm/hsl ).
The goal of Psl is to provide a consistent, centralized, well-typed set of APIs for PHP programmers.
2019-12-24 01:52:07 +01:00
## Example
```php
< ?php
declare(strict_types=1);
2021-02-16 02:17:35 +01:00
use Psl\{Dict, Str, Vec};
2019-12-24 01:52:07 +01:00
/**
* @psalm -param iterable< ?int> $codes
*/
function foo(iterable $codes): string
{
2021-02-16 02:17:35 +01:00
$codes = Vec\filter_nulls($codes);
$chars = Dict\map($codes, fn(int $code): string => Str\chr($code));
2020-07-06 22:45:13 +02:00
return Str\join($chars, ', ');
2019-12-24 01:52:07 +01:00
}
foo([95, 96, null, 98]);
// 'a, b, d'
```
## Installation
2021-01-17 21:07:12 +01:00
Supported installation method is via [composer ](https://getcomposer.org ):
2019-12-24 01:52:07 +01:00
```console
2020-12-21 19:14:41 +01:00
$ composer require azjezz/psl
2019-12-24 01:52:07 +01:00
```
2021-02-09 21:15:06 +01:00
### Psalm Integration
PSL comes with a [Psalm ](https://psalm.dev/ ) plugin, that improves return type for PSL functions that psalm cannot infer from source code.
2021-02-16 11:02:56 +01:00
To enable the Psalm plugin, add the `Psl\Integration\Psalm\Plugin` class to your psalm configuration file plugins list as follows:
2021-02-09 21:15:06 +01:00
```xml
< psalm >
...
< plugins >
...
2021-02-16 02:17:35 +01:00
< pluginClass class = "Psl \Integration \Psalm \Plugin" />
2021-02-09 21:15:06 +01:00
< / plugins >
< / psalm >
```
2019-12-24 01:52:07 +01:00
## Documentation
Documentation is not available yet.
## Principles
- All functions should be typed as strictly as possible
- The library should be internally consistent
- References may not be used
2020-09-11 02:02:59 +02:00
- Arguments should be as general as possible. For example, for `array` functions, prefer `iterable` inputs where practical, falling back to `array` when needed.
2019-12-24 01:52:07 +01:00
- 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` )
2020-09-04 19:30:12 +02:00
## Sponsors
Thanks to our sponsors and supporters:
| JetBrains |
|---|
| < a href = "https://www.jetbrains.com/?from=PSL ( PHP Standard Library )" title = "JetBrains" target = "_blank" > < img src = "https://res.cloudinary.com/azjezz/image/upload/v1599239910/jetbrains_qnyb0o.png" height = "120" / > < / a > |
2019-12-24 01:52:07 +01:00
## License
The MIT License (MIT). Please see [`LICENSE` ](./LICENSE ) for more information.
