Skip to content

bolt/common

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bolt Common

This library provides utility functions to help simplify menial tasks.

Where possible, this library provides some wrappers around some built-in functions. Our code should always throw exceptions instead of triggering errors/warnings/notices (excluding deprecation warnings).

Table of Contents:


Arr

Functions to deal with arrays.

Assert

Additional assertions built on Webmozart\Assert.

isArrayAccessible

Throws InvalidArgumentException if $value is not an array or object implementing ArrayAccess.

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

isInstanceOfAny

Throws InvalidArgumentException if $value is not an instance of one of the given classes/interfaces.

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

isIterable

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

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

Deprecated

Helper methods for triggering deprecation warnings.

warn

Shortcut for triggering a deprecation warning for something.

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

Examples:

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

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.

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

Example:

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.

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.

Examples:

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

has

Checks whether the key exists.

has(string $key): bool

getStr

Get a string value. The default is returned if the key does not exist or the value is empty.

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.

getBool(string $key): bool

getNumeric

Get a numeric value. The default is returned if the key does not exist or the value is empty.

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.

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.

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

Json

Handles JSON parsing/dumping with error handling.

parse

Parses JSON string to array or scalar. Throws ParseException if anything goes wrong.

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.

dump

Dumps mixed to JSON string. Throws DumpException if anything goes wrong.

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.

test

Returns whether the string is valid JSON.

test(string $json): bool

Serialization

Handles PHP serialization parsing/dumping with error handling.

parse

Parses PHP serialized string.

Throws ParseException if a serialized class cannot be found or anything else goes wrong.

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

Note: $options parameter is ignored on PHP 5.

See unserialize() for details.

dump

Dumps anything to a PHP serialized string.

Throws DumpException if the input is not serializable or anything else goes wrong.

dump(mixed $value): string

Str

Common string methods.

replaceFirst

Replaces the first occurrence of the $search text on the $subject.

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

replaceLast

Replaces the last occurrence of the $search text on the $subject.

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

removeFirst

Removes the first occurrence of the $search text on the $subject.

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

removeLast

Removes the last occurrence of the $search text on the $subject.

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

splitFirst

Splits a $subject on the $delimiter and returns the first part.

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

splitLast

Splits a $subject on the $delimiter and returns the last part.

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

endsWith

Returns whether the subjects ends with the search string.

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

className

Returns the class name without the namespace, of a string FQCN, or object.

className(string|object $class): string

humanize

Converts a string from camel case and snake case to a human readable string.

humanize(string $text): string

camelCase

Converts a string from snake case to camel case.

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

snakeCase

Converts a string from camel case to snake case.

snakeCase(string $text): string