Callback-функции
****************

.[perex]
[api:Nette\Utils\Callback] - статический класс с функциями для работы с [callback-функциями PHP |https://www.php.net/manual/en/language.types.callable.php].


Установка:

```shell
composer require nette/utils
```

Во всех примерах предполагается, что определён такой псевдоним класса:

```php
use Nette\Utils\Callback;
```


check($callable, bool $syntax=false): callable .[method]
--------------------------------------------------------

Проверяет, является ли `$callable` корректным callback PHP. Иначе выбрасывает `Nette\InvalidArgumentException`. Если `$syntax` установлен в `true`, функция только проверяет, что у `$callable` корректная структура callback, но не проверяет, существуют ли класс или метод на самом деле. Возвращает исходный `$callable`.

```php
Callback::check('trim'); // без исключения
Callback::check(['NonExistentClass', 'method']); // выбрасывает Nette\InvalidArgumentException
Callback::check(['NonExistentClass', 'method'], true); // без исключения
Callback::check(function () {}); // без исключения
Callback::check(null); // выбрасывает Nette\InvalidArgumentException
```


toString(callable $callable): string .[method]
----------------------------------------------

Преобразует callback PHP в его текстовое представление. Класс или метод существовать не обязаны.

```php
Callback::toString('trim');                // 'trim'
Callback::toString(['MyClass', 'method']); // 'MyClass::method'
```


toReflection(callable $callable): \ReflectionMethod|\ReflectionFunction .[method]
---------------------------------------------------------------------------------

Возвращает рефлексию метода или функции, использованных в callback PHP. Выбрасывает `\ReflectionException`, если указанный метод или функция не существуют.

```php
$ref = Callback::toReflection('trim');
// $ref - это ReflectionFunction('trim')

$ref = Callback::toReflection(['MyClass', 'method']);
// $ref - это ReflectionMethod('MyClass', 'method')
```


isStatic(callable $callable): bool .[method]
--------------------------------------------

Проверяет, является ли callback PHP глобальной функцией или статическим методом.

```php
Callback::isStatic('trim');                // true
Callback::isStatic(['MyClass', 'method']); // true
Callback::isStatic([$obj, 'method']);      // false
Callback::isStatic(function () {});        // false
```


unwrap(\Closure $closure): callable|array .[method]
---------------------------------------------------

Разворачивает замыкание, созданное через `Closure::fromCallable()`. Возвращает исходный массив или строку callable.

```php
$closure = Closure::fromCallable(['MyClass', 'method']);
Callback::unwrap($closure);     // ['MyClass', 'method']
```


invokeSafe(string $function, array $args, callable $onError): mixed .[method]
-----------------------------------------------------------------------------

Вызывает нативную функцию PHP `$function` с аргументами `$args` и при этом перехватывает собственным обработчиком все предупреждения и ошибки, которые она выдаёт. Это позволяет реагировать на проблемы, о которых нативные функции обычно сообщают лишь предупреждением. Callback `$onError` получает два аргумента: сообщение об ошибке (без ведущего префикса `function():`) и её уровень серьёзности. Если он возвращает `false`, ошибка передаётся стандартному обработчику ошибок.

```php
$result = Callback::invokeSafe('file_get_contents', ['file.txt'], function (string $message, int $severity) {
	throw new Exception($message);
});
```