https://github.com/camelotproject/common
https://github.com/camelotproject/common
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/camelotproject/common
- Owner: CamelotProject
- License: mit
- Created: 2018-08-31T10:23:41.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-01-09T09:23:21.000Z (over 3 years ago)
- Last Synced: 2025-01-13T08:27:06.510Z (5 months ago)
- Language: PHP
- Size: 144 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Camelot Common
==============
This library provides utility functions to help simplify menial tasks.
The Camelot team believes the PHP error reporting system is a mistake. Many
built-in functions utilize it, leading to inconsistent results and head
scratching.
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).
Table of Contents:
- [Assert](#assert)
- [Deprecated](#deprecated)
- [Ini](#ini)
- [Json](#json)
- [Serialization](#serialization)
- [Str](#str)
-----
## `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
```