Util
in package
Miscellaneous utilities.
Tags
Table of Contents
Methods
- identity() : mixed
- Just returns the input value. Useful in functional programming style.
- map() : U|T|null
- Checks $v on (selectable) common falsy values and returns $fn($v) or $v (when $fn === null) when not falsy. Returns $v or null otherwise.
- map_nots() : U|T|null
- Maps a value through a function, iff both the value and the function are 'set'. For the function this means it is not null, for the value it means, it is not one of the $nots (compared strictly).
- new() : callable(mixed ...$args): T
- Returns a function (Closure) for a constructor call.
- tree_path() : Generator<string|int, T>
- For any node in a tree structure, get all parents (possibly up to a specific one) and return them from top to bottom as an iterable (Generator): `foreach (tree_path($node) as $parent_node) {...}`
- when() : mixed
- When `$test` is a falsy value (as selected by `$null`, `$false`, `$empty` and `$zero`), returns `null`.
- when_nots() : mixed
- Like {@link when()}, but the the falsy values are given as arguments (`$nots`).
Methods
identity()
Just returns the input value. Useful in functional programming style.
public
static identity(mixed $v) : mixed
Parameters
- $v : mixed
-
the input value
Tags
Return values
mixed —the input value
map()
Checks $v on (selectable) common falsy values and returns $fn($v) or $v (when $fn === null) when not falsy. Returns $v or null otherwise.
public
static map(T|null $v[, callable(Array): Array|null $fn = null ][, bool $null_on_not = false ][, bool $func = false ][, bool $null = true ][, bool $false = false ][, bool $empty = false ][, bool $zero = false ]) : U|T|null
By default only null is selected as a falsy value.
Parameters
- $v : T|null
- $fn : callable(Array): Array|null = null
-
- $null_on_not : bool = false
-
return null on falsy (as selected by $func, $null, $false, $empty and $zero)
- $func : bool = false
-
whether $fn === null means falsy too
- $null : bool = true
-
whether null is a falsy value
- $false : bool = false
-
whether false is a falsy value
- $empty : bool = false
-
whether an empty string and an empty array are falsy values
- $zero : bool = false
-
whether 0 and 0.0 are falsy values
Tags
Return values
U|T|null —the possibly mapped value
map_nots()
Maps a value through a function, iff both the value and the function are 'set'. For the function this means it is not null, for the value it means, it is not one of the $nots (compared strictly).
public
static map_nots(T|null $v[, callable(Array): U|null $fn = null ][, bool $null_on_not = false ][, bool $func = false ], mixed ...$nots) : U|T|null
Parameters
- $v : T|null
-
the input value to be mapped
- $fn : callable(Array): U|null = null
-
- $null_on_not : bool = false
-
whether to return null iff the input value matches one of the $nots
- $func : bool = false
-
whether to test $fn on null as a 'not' value, too. if true, $fn === null means return $v unmapped (only useful with $null_on_not === true, which returns null then); if false, $fn === null means $v is returned unchanged (like ).
- $nots : mixed
-
the values which count as a 'not' value (mostly useful: null, false, '', 0). see
Tags
Return values
U|T|null —the possibly mapped value
new()
Returns a function (Closure) for a constructor call.
public
static new(T> $class) : callable(mixed ...$args): T
PHP does not support new MyClass(...), so this is a workaround: Util::new(MyClass::class)`
Parameters
- $class : T>
-
the class name
Tags
Return values
callable(mixed ...$args): T —the function (Closure) to create the class
tree_path()
For any node in a tree structure, get all parents (possibly up to a specific one) and return them from top to bottom as an iterable (Generator): `foreach (tree_path($node) as $parent_node) {...}`
public
static tree_path(T|null $element, callable(T): Array $get_parent[, callable(T): bool|null $while = null ]) : Generator<string|int, T>
Parameters
- $element : T|null
-
the starting node
- $get_parent : callable(T): Array
-
the function to get the parent node of a child node
- $while : callable(T): bool|null = null
-
an optional check when to stop (
$whilemust return false to not rise further in the tree)
Tags
Return values
Generator<string|int, T> —the iterable, directly usable in foreach(...)
when()
When `$test` is a falsy value (as selected by `$null`, `$false`, `$empty` and `$zero`), returns `null`.
public
static when(mixed $test, mixed $v[, callable|null $fn = null ][, bool $null = true ][, bool $false = true ][, bool $empty = false ][, bool $zero = false ]) : mixed
Otherwise returns $v, which can be a function, which is called then (the usual use case for this).
This function is like the ternary operator: $test ? $fn($v) : null, but it handles $fn and $v carefully
and relieves the caller to use a temporary variable for a dynamic test value and more tests
(f.e. when($obj->get(), identity(...), empty: true) returns the get() result only if it is not null, false or the empty string)
Parameters
- $test : mixed
-
the value to test on
- $v : mixed
-
the value to return. can be a callable, which is called then with $test as the only argument.
- $fn : callable|null = null
-
an optional function (only Closure, not just callable) to map the value through (after an optional
$v = $v()call) - $null : bool = true
-
whether null is a falsy value
- $false : bool = true
-
whether false is a falsy value
- $empty : bool = false
-
whether an empty string is a falsy value
- $zero : bool = false
-
whether 0 (zero) is a falsy value
Tags
Return values
mixed —the value, possibly mapped, or null if $test was falsy
when_nots()
Like {@link when()}, but the the falsy values are given as arguments (`$nots`).
public
static when_nots(mixed $test, mixed $v[, callable|null $fn = null ], mixed ...$nots) : mixed
Parameters
- $test : mixed
- $v : mixed
- $fn : callable|null = null
- $nots : mixed