コールバック関数
********
.[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);
});
```
コールバック関数
Nette\Utils\Callback は、PHP
のコールバックを扱う関数を集めた静的クラスです。
インストール:
composer require nette/utils
以下の例では、次のクラスの別名が定義されているものとします。
use Nette\Utils\Callback;
check ($callable, bool $syntax=false): callable
$callable が正しい PHP のコールバックかどうかを調べます。そうでなければ
Nette\InvalidArgumentException を投げます。$syntax が true
の場合は、$callable
がコールバックとして正しい構造かどうかだけを確認し、クラスやメソッドが実際に存在するかは調べません。もとの
$callable を返します。
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
PHP
のコールバックをテキスト表現に変換します。クラスやメソッドが存在する必要はありません。
Callback::toString('trim'); // 'trim'
Callback::toString(['MyClass', 'method']); // 'MyClass::method'
toReflection (callable $callable): \ReflectionMethod|\ReflectionFunction
PHP
のコールバックで使われているメソッドや関数のリフレクションを返します。参照されたメソッドや関数が存在しない場合は
\ReflectionException を投げます。
$ref = Callback::toReflection('trim');
// $ref は ReflectionFunction('trim')
$ref = Callback::toReflection(['MyClass', 'method']);
// $ref は ReflectionMethod('MyClass', 'method')
isStatic (callable $callable): bool
PHP のコールバックがグローバル関数か静的メソッドかを調べます。
Callback::isStatic('trim'); // true
Callback::isStatic(['MyClass', 'method']); // true
Callback::isStatic([$obj, 'method']); // false
Callback::isStatic(function () {}); // false
unwrap (\Closure $closure): callable|array
Closure::fromCallable() で作られたクロージャを解きます。もとの callable
の配列や文字列を返します。
$closure = Closure::fromCallable(['MyClass', 'method']);
Callback::unwrap($closure); // ['MyClass', 'method']
invokeSafe (string $function, array $args,
callable $onError): mixed
ネイティブの PHP 関数 $function を引数 $args
で呼び出し、その際に出る警告やエラーを独自のハンドラで捕まえます。これにより、ネイティブ関数がふつうは警告としてしか報告しない問題に対処できます。$onError
コールバックは 2 つの引数を受け取ります。エラーメッセージ(先頭の function():
接頭辞は取り除かれます)と、その深刻度です。false
を返すと、エラーは標準のエラーハンドラに渡されます。
$result = Callback::invokeSafe('file_get_contents', ['file.txt'], function (string $message, int $severity) {
throw new Exception($message);
});