bolt / common
🧰 Common utilities for all Bolt libraries
Installs: 293 929
Dependents: 9
Suggesters: 0
Security: 0
Stars: 18
Watchers: 9
Forks: 6
Open Issues: 2
Requires
- php: >=7.2.5 || ^8.0
- seld/jsonlint: ^1.7
- webmozart/assert: ^1.6
Requires (Dev)
- phpunit/phpunit: ^7.5
- symfony/phpunit-bridge: ^3.4
- symplify/easy-coding-standard: ^8.2.3
This package is auto-updated.
Last update: 2024-11-08 21:43:29 UTC
README
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