https://github.com/bolt/common
Common utilities for Bolt
https://github.com/bolt/common
bolt php
Last synced: 3 months ago
JSON representation
Common utilities for Bolt
- Host: GitHub
- URL: https://github.com/bolt/common
- Owner: bolt
- License: mit
- Created: 2017-07-18T19:07:01.000Z (over 8 years ago)
- Default Branch: 3.0
- Last Pushed: 2021-11-08T14:47:47.000Z (about 4 years ago)
- Last Synced: 2025-04-16T11:25:08.927Z (9 months ago)
- Topics: bolt, php
- Language: PHP
- Homepage: https://bolt.cm
- Size: 270 KB
- Stars: 18
- Watchers: 12
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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](#arr)
- [Assert](#assert)
- [Deprecated](#deprecated)
- [Ini](#ini)
- [Json](#json)
- [Serialization](#serialization)
- [Str](#str)
-----
## 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`.
```php
isArrayAccessible($value, string $message = ''): void
```
### `isInstanceOfAny`
Throws `InvalidArgumentException` if `$value` is not an instance of one of the
given classes/interfaces.
```php
isInstanceOfAny($value, string[] $classes, string $message = ''): void
```
### `isIterable`
Throws `InvalidArgumentException` if `$value` is not an _iterable_. Same as
`isTraversable()`, just a better name.
```php
isIterable($value, string $message = ''): void
```
## `Deprecated`
Helper methods for triggering deprecation warnings.
### `warn`
Shortcut for triggering a deprecation warning for something.
```php
warn(string $subject, string|float $since = null, string $suggest = ''): void
```
Examples:
```php
// 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.
```php
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:
```php
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.
```php
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:
```php
// 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.
```php
has(string $key): bool
```
### `getStr`
Get a string value. The default is returned if the key does not exist or the
value is empty.
```php
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.
```php
getBool(string $key): bool
```
### `getNumeric`
Get a numeric value. The default is returned if the key does not exist or the
value is empty.
```php
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.
```php
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.
```php
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.
```php
parse(string $json, int $options = 0, int $depth = 512): string
```
We use [`seld/jsonlint`](https://github.com/Seldaek/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.
```php
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.
```php
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.
```php
parse(string $value, array $options = []): mixed
```
Note: `$options` parameter is ignored on PHP 5.
See [`unserialize()`](http://php.net/manual/en/function.unserialize.php) for
details.
### `dump`
Dumps anything to a PHP serialized _string_.
Throws `DumpException` if the input is not serializable or anything else goes
wrong.
```php
dump(mixed $value): string
```
## `Str`
Common string methods.
### `replaceFirst`
Replaces the first occurrence of the $search text on the $subject.
```php
replaceFirst(string $subject, string $search, string $replace, bool $caseSensitive = true): string
```
### `replaceLast`
Replaces the last occurrence of the $search text on the $subject.
```php
replaceLast(string $subject, string $search, string $replace, bool $caseSensitive = true): string
```
### `removeFirst`
Removes the first occurrence of the $search text on the $subject.
```php
removeFirst(string $subject, string $search, bool $caseSensitive = true): string
```
### `removeLast`
Removes the last occurrence of the $search text on the $subject.
```php
removeLast(string $subject, string $search, bool $caseSensitive = true): string
```
### `splitFirst`
Splits a $subject on the $delimiter and returns the first part.
```php
splitFirst(string $subject, string $delimiter): string
```
### `splitLast`
Splits a $subject on the $delimiter and returns the last part.
```php
splitLast(string $subject, string $delimiter): string
```
### `endsWith`
Returns whether the subjects ends with the search string.
```php
endsWith(string $subject, string $search, bool $caseSensitive = true): bool
```
### `className`
Returns the class name without the namespace, of a string FQCN, or object.
```php
className(string|object $class): string
```
### `humanize`
Converts a string from camel case and snake case to a human readable string.
```php
humanize(string $text): string
```
### `camelCase`
Converts a string from snake case to camel case.
```php
camelCase(string $text, bool $lowercaseFirstChar = false): string
```
### `snakeCase`
Converts a string from camel case to snake case.
```php
snakeCase(string $text): string
```