コールバック関数
************

.[perex]
[api:Nette\Utils\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` が正しい PHP のコールバックかどうかを調べます。そうでなければ `Nette\InvalidArgumentException` を投げます。`$syntax` が `true` の場合は、`$callable` がコールバックとして正しい構造かどうかだけを確認し、クラスやメソッドが実際に存在するかは調べません。もとの `$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]
----------------------------------------------

PHP のコールバックをテキスト表現に変換します。クラスやメソッドが存在する必要はありません。

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


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

PHP のコールバックで使われているメソッドや関数のリフレクションを返します。参照されたメソッドや関数が存在しない場合は `\ReflectionException` を投げます。

```php
$ref = Callback::toReflection('trim');
// $ref は ReflectionFunction('trim')

$ref = Callback::toReflection(['MyClass', 'method']);
// $ref は ReflectionMethod('MyClass', 'method')
```


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

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` で呼び出し、その際に出る警告やエラーを独自のハンドラで捕まえます。これにより、ネイティブ関数がふつうは警告としてしか報告しない問題に対処できます。`$onError` コールバックは 2 つの引数を受け取ります。エラーメッセージ（先頭の `function():` 接頭辞は取り除かれます）と、その深刻度です。`false` を返すと、エラーは標準のエラーハンドラに渡されます。

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