bolt/common

Common utilities for all Bolt libraries

Bolt Common

This library provides utility functions to help simplify menial tasks., _(*1)

The Bolt team believes the PHP error reporting system is a mistake. Many built-in functions utilize it, leading to inconsistent results and head scratching., _(*2)

This library provides some wrappers around some of these functions. Our code should always throw exceptions instead of triggering errors/warnings/notices (excluding deprecation warnings)., _(*3)

Table of Contents: - Assert - Deprecated - Ini - Json - Serialization - Str, _(*4)

Assert

Additional assertions built on Webmozart\Assert, _(*5)

isArrayAccessible

Throws InvalidArgumentException if $value is not an array or object implementing ArrayAccess., _(*6)

isArrayAccessible($value, string $message = ''): void

isInstanceOfAny

Throws InvalidArgumentException if $value is not an instance of one of the given classes/interfaces., _(*7)

isInstanceOfAny($value, string[] $classes, string $message = ''): void

isIterable

Throws InvalidArgumentException if $value is not an iterable. Same as isTraversable(), just a better name., _(*8)

isIterable($value, string $message = ''): void

Deprecated

Helper methods for triggering deprecation warnings., _(*9)

warn

Shortcut for triggering a deprecation warning for something., _(*10)

warn(string $subject, string|float $since = null, string $suggest = ''): void

Examples:, _(*11)

// Triggers warning: "Doing foo is deprecated."
Deprecated::warn('Doing foo');

// Triggers warning: "Doing foo is deprecated since 3.3 and will be removed in 4.0."
Deprecated::warn('Doing foo', 3.3);

// Triggers warning: "Doing foo is deprecated since 3.3 and will be removed in 4.0. Do bar instead."
Deprecated::warn('Doing foo', 3.3, 'Do bar instead');

method

Shortcut for triggering a deprecation warning for a method., _(*12)

method(string|float $since = null, string $suggest = '', string $method = null): void

$suggest can be a sentence describing what to use instead. Or it can be a method name or class::method which will be converted to a sentence., _(*13)

$method defaults to the method/function it was called from. - If called from constructor, warning message says the class is deprecated. - If called from magic method, warning message says the method/property called with is deprecated., _(*14)

Example:, _(*15)

class Foo
{
    public function world()
    {
        // Triggers warning: "Foo::world() is deprecated since 3.3 and will be removed in 4.0. Use hello() instead."
        Deprecated::method(3.3, 'hello');
    }
}

cls

Shortcut for triggering a deprecation warning for a class., _(*16)

cls(string $class, string|float $since = null, string $suggest = null): void

$suggest can be a sentence describing what to use instead. Or it can be a class name which will be converted to a sentence., _(*17)

Examples:, _(*18)

// Triggers warning: "Foo\Bar is deprecated."
Deprecated::cls('Foo\Bar');

// Triggers warning: "Foo\Bar is deprecated. Use Bar\Baz instead."
Deprecated::cls('Foo\Bar', null, 'Bar\Baz');

Ini

Handles setting and retrieving values from PHP's configuration., _(*19)

has

Checks whether the key exists., _(*20)

has(string $key): bool

getStr

Get a string value. The default is returned if the key does not exist or the value is empty., _(*21)

getStr(string $key, string $default = null): ?string

getBool

Get a boolean value. False is returned if the key does not exist or the value is empty., _(*22)

getBool(string $key): bool

getNumeric

Get a numeric value. The default is returned if the key does not exist or the value is empty., _(*23)

getNumeric(string $key, int|float $default = null): int|float|null

getBytes

Get a memory size value, such as memory_limit, and convert it to an integer. The default is returned if the key does not exist or the value is empty., _(*24)

getBytes(string $key, int $default = null): ?int

set

Set a new value for the given key. Throws RuntimeException if the key does not exist, it is not editable, or something goes wrong., _(*25)

set(string $key, ?scalar $value): void

Json

Handles JSON parsing/dumping with error handling., _(*26)

parse

Parses JSON string to array or scalar. Throws ParseException if anything goes wrong., _(*27)

parse(string $json, int $options = 0, int $depth = 512): string

We use seld/jsonlint to determine why the parsing failed and include it in the exception message., _(*28)

dump

Dumps mixed to JSON string. Throws DumpException if anything goes wrong., _(*29)

dump(mixed $data, int $options = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE, int $depth = 512): string

If input contains invalid UTF-8 characters we try to convert these for you before failing., _(*30)

test

Returns whether the string is valid JSON., _(*31)

test(string $json): bool

Serialization

Handles PHP serialization parsing/dumping with error handling., _(*32)

parse

Parses PHP serialized string., _(*33)

Throws ParseException if a serialized class cannot be found or anything else goes wrong., _(*34)

parse(string $value, array $options = []): mixed

Note: $options parameter is ignored on PHP 5., _(*35)

See unserialize() for details., _(*36)

dump

Dumps anything to a PHP serialized string., _(*37)

Throws DumpException if the input is not serializable or anything else goes wrong., _(*38)

dump(mixed $value): string

Str

Common string methods., _(*39)

replaceFirst

Replaces the first occurrence of the $search text on the $subject., _(*40)

replaceFirst(string $subject, string $search, string $replace, bool $caseSensitive = true): string

replaceLast

Replaces the last occurrence of the $search text on the $subject., _(*41)

replaceLast(string $subject, string $search, string $replace, bool $caseSensitive = true): string

removeFirst

Removes the first occurrence of the $search text on the $subject., _(*42)

removeFirst(string $subject, string $search, bool $caseSensitive = true): string

removeLast

Removes the last occurrence of the $search text on the $subject., _(*43)

removeLast(string $subject, string $search, bool $caseSensitive = true): string

splitFirst

Splits a $subject on the $delimiter and returns the first part., _(*44)

splitFirst(string $subject, string $delimiter): string

splitLast

Splits a $subject on the $delimiter and returns the last part., _(*45)

splitLast(string $subject, string $delimiter): string

endsWith

Returns whether the subjects ends with the search string., _(*46)

endsWith(string $subject, string $search, bool $caseSensitive = true): bool

className

Returns the class name without the namespace, of a string FQCN, or object., _(*47)

className(string|object $class): string

humanize

Converts a string from camel case and snake case to a human readable string., _(*48)

humanize(string $text): string

camelCase

Converts a string from snake case to camel case., _(*49)

camelCase(string $text, bool $lowercaseFirstChar = false): string

snakeCase

Converts a string from camel case to snake case., _(*50)

snakeCase(string $text): string