Skip to content

Commit cad82a7

Browse files
mumumumumumu
committed
Rewrite the callback and callable page
php/doc-en@147b80d
1 parent d24a8e1 commit cad82a7

File tree

1 file changed

+233
-107
lines changed

1 file changed

+233
-107
lines changed

‎language/types/callable.xml‎

Lines changed: 233 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,249 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: eac9eff7b66d8c2b168c25c72de0422126daf8cb Maintainer: takagi Status: ready -->
4-
<!-- Credits: mumumu -->
3+
<!-- EN-Revision: 147b80d1974b969caad1db188a48f4bcd90f5eb8 Maintainer: mumumu Status: ready -->
4+
55
<sect1 xml:id="language.types.callable">
66
<title>コールバック / Callable</title>
7-
8-
<para>
9-
コールバックは、<type>callable</type> 型で表されます。
10-
</para>
11-
12-
<para>
13-
<function>call_user_func</function> や <function>usort</function>
14-
等の関数は、ユーザーが定義するコールバック関数を引数として受け入れます。
15-
コールバック関数は、単純な関数だけでなく、オブジェクトのメソッド
16-
あるいはクラスのstaticメソッドであってもかまいません。
17-
</para>
7+
8+
<simpara>
9+
callable は、
10+
別の関数への引数として渡される関数またはメソッドへのリファレンスです。
11+
これらは、<type>callable</type> 型を宣言することで表されます。
12+
</simpara>
13+
<informalexample>
14+
<programlisting role="php" annotations="non-interactive">
15+
<![CDATA[
16+
<?php
17+
function foo(callable $callback) {
18+
$callback();
19+
}
20+
?>
21+
]]>
22+
</programlisting>
23+
</informalexample>
24+
25+
<simpara>
26+
関数によっては、コールバック関数を引数として受け入れるものがあります。
27+
例として
28+
<function>array_map</function>, <function>usort</function>,
29+
<function>preg_replace_callback</function> が挙げられます。
30+
</simpara>
1831

1932
<sect2 xml:id="language.types.callable.passing">
20-
<title>受け渡し</title>
21-
22-
<para>
23-
PHP 関数はその名前を単に文字列、または
24-
<link linkend="functions.first_class_callable_syntax">第一級callable</link>
25-
として渡します。
26-
どのようなビルトインまたはユーザー定義の関数も渡すことができます。
27-
ただし、
33+
<title>callable の作成</title>
34+
35+
<simpara>
36+
callable は、呼び出し可能な何かを表す型です。
37+
コールバック関数をパラメータとして期待する関数や、
38+
メソッドの引数として渡すことができますし、
39+
直接呼び出すこともできます。
40+
41+
<type>callable</type> 型は、
42+
クラスのプロパティの型宣言には使えません。
43+
代わりに、<classname>Closure</classname> を型宣言に使ってください。
44+
</simpara>
45+
46+
<simpara>
47+
callable は、複数の異なる方法で作成できます:
48+
</simpara>
49+
50+
<itemizedlist>
51+
<listitem>
52+
<simpara><classname>Closure</classname> オブジェクト</simpara>
53+
</listitem>
54+
<listitem>
55+
<simpara>関数またはメソッドの名前を含む文字列</simpara>
56+
</listitem>
57+
<listitem>
58+
<simpara>
59+
配列。クラス名または <type>object</type>
60+
をインデックス 0 に、メソッド名をインデックス 1 に含みます。
61+
</simpara>
62+
</listitem>
63+
<listitem>
64+
<simpara>
65+
<link linkend="object.invoke">__invoke()</link>
66+
マジックメソッドを実装した &object;
67+
</simpara>
68+
</listitem>
69+
</itemizedlist>
70+
71+
<simpara>
72+
<classname>Closure</classname> オブジェクトは、
73+
<link linkend="functions.anonymous">無名関数</link>、
74+
<link linkend="functions.arrow">アロー関数</link>、
75+
<link linkend="functions.first_class_callable_syntax">第一級callableを生成する記法</link>、
76+
もしくは <methodname>Closure::fromCallable</methodname>
77+
メソッドを使って作成できます。
78+
</simpara>
79+
80+
<note>
81+
<simpara>
82+
<link linkend="functions.first_class_callable_syntax">第一級callableを生成する記法</link>
83+
は、PHP 8.1.0 以降でのみ利用可能です。
84+
</simpara>
85+
</note>
86+
87+
<example>
88+
<title>
89+
<classname>Closure</classname> を使ったコールバックの例
90+
</title>
91+
<programlisting role="php">
92+
<![CDATA[
93+
<?php
94+
// Using anonymous function syntax
95+
$double1 = function ($a) {
96+
return $a * 2;
97+
};
98+
99+
// Using first-class callable syntax
100+
function double_function($a) {
101+
return $a * 2;
102+
}
103+
$double2 = double_function(...);
104+
105+
// Using arrow function syntax
106+
$double3 = fn($a) => $a * 2;
107+
108+
// Using Closure::fromCallable
109+
$double4 = Closure::fromCallable('double_function');
110+
111+
// Use the closure as a callback here to
112+
// double the size of each element in our range
113+
$new_numbers = array_map($double1, range(1, 5));
114+
print implode(' ', $new_numbers) . PHP_EOL;
115+
116+
$new_numbers = array_map($double2, range(1, 5));
117+
print implode(' ', $new_numbers) . PHP_EOL;
118+
119+
$new_numbers = array_map($double3, range(1, 5));
120+
print implode(' ', $new_numbers) . PHP_EOL;
121+
122+
$new_numbers = array_map($double4, range(1, 5));
123+
print implode(' ', $new_numbers);
124+
125+
?>
126+
]]>
127+
</programlisting>
128+
&example.outputs.81;
129+
<screen>
130+
<![CDATA[
131+
2 4 6 8 10
132+
2 4 6 8 10
133+
2 4 6 8 10
134+
2 4 6 8 10
135+
]]>
136+
</screen>
137+
</example>
138+
139+
<simpara>
140+
callable は、
141+
関数名や static メソッドを含む文字列でも表現できます。
142+
ビルトイン関数、またはユーザー定義関数も使えます。
143+
但し、以下のような言語構造は除きます:
28144
<function>array</function>, <function>echo</function>,
29-
<function>empty</function>, <function>eval</function>,
30-
<function>exit</function>, <function>isset</function>,
31-
<function>list</function>, <function>print</function> あるいは
145+
<function>empty</function>, <function>eval</function>,
146+
<function>isset</function>,
147+
<function>list</function>, <function>print</function>,
32148
<function>unset</function>
33-
といった言語構造はコールバックとしては使えないことに注意しましょう。
34-
</para>
35-
36-
<para>
37-
オブジェクトのインスタンスを渡すには配列を使います。
38-
配列の 0 番目の要素にオブジェクトを、
39-
そして 1 番目の要素にメソッド名を指定します。
40-
protected メソッドや private メソッドは、クラスの内部からはアクセスできます。
41-
</para>
42-
43-
<para>
44-
static メソッドの場合、オブジェクトのインスタンスは不要です。
45-
0 番目の要素として、オブジェクトのかわりにクラス名を指定します。
46-
<literal>'ClassName::methodName'</literal> 形式で指定することもできます。
47-
</para>
48-
49-
<para>
50-
一般的なユーザー定義関数とは異なり、
51-
<link linkend="functions.anonymous">無名関数</link> と
52-
<link linkend="functions.arrow">アロー関数</link> もパラメータとして渡せます。
53-
</para>
149+
</simpara>
150+
151+
<simpara>
152+
static メソッドは、クラスの <type>object</type>
153+
型をインスタンス化せずに使えます。
154+
クラス名をインデックス 0 に、
155+
メソッド名をインデックス 1 に配置した配列を作成するか、
156+
<literal>'ClassName::methodName'</literal> のような、
157+
スコープ解決演算子 <literal>::</literal> を使った特殊構文が使えます。
158+
</simpara>
159+
160+
<simpara>
161+
インスタンス化された <type>object</type>
162+
のメソッドは、<type>object</type> をインデックス 0 に、
163+
メソッド名をインデックス 1 に配置した配列を作成することで、
164+
callable にできます。
165+
</simpara>
166+
167+
<simpara>
168+
<classname>Closure</classname> オブジェクトと callable 型の主な違いは、
169+
<classname>Closure</classname>
170+
オブジェクトがスコープに依存せず常に呼び出せるのに対し、
171+
callable はスコープに依存する場合があり、
172+
直接呼び出せない可能性がある点です。
173+
<classname>Closure</classname> が、callable を作成する望ましい方法です。
174+
</simpara>
175+
176+
<note>
177+
<simpara>
178+
<classname>Closure</classname> オブジェクトは、
179+
それが作成されたスコープにバインドされますが、
180+
クラスメソッドを文字列または配列で参照する callable は、
181+
それらが呼び出されたスコープの内部で解決されます。
182+
callable を private または protected メソッドから作成し、
183+
クラスのスコープ外から呼び出せるようにするには、
184+
<methodname>Closure::fromCallable</methodname> または、
185+
<link linkend="functions.first_class_callable_syntax">第一級callableを生成する記法</link> を使います。
186+
</simpara>
187+
</note>
188+
189+
<simpara>
190+
PHP は、コールバック引数として使えるものの、
191+
直接は呼び出せない callable を作成できます。
192+
これらはコンテキスト依存の callable であり、
193+
例えば <literal>'parent::method'</literal> や
194+
<literal>["static", "method"]</literal>
195+
の形で、クラスの継承階層におけるクラスメソッドを参照します。
196+
</simpara>
54197

55198
<note>
56-
<para>
57-
PHP 8.1.0 以降では、
58-
無名関数を作るための記法として、<link linkend="functions.first_class_callable_syntax">第一級callableを生成する記法</link> も使えます。
59-
</para>
199+
<simpara>
200+
PHP 8.2.0 以降では、
201+
コンテキスト依存の callable は推奨されなくなりました。
202+
<literal>'parent::method'</literal> を
203+
<literal>parent::class . '::method'</literal>
204+
形式に置き換えることでコンテキスト依存を除去するか、
205+
<link linkend="functions.first_class_callable_syntax">第一級callableを生成する記法</link> を使ってください。
206+
</simpara>
60207
</note>
61208

62-
<para>
63-
一般的には、
64-
<link linkend="object.invoke">__invoke()</link> を実装した任意のオブジェクトもパラメータとして渡せます。
65-
</para>
66-
67-
<para>
68-
<example>
69-
<title>
70-
コールバック関数の例
71-
</title>
72-
<programlisting role="php">
209+
<example>
210+
<title>
211+
<function>call_user_function</function>
212+
を使って、様々なタイプの callable を呼び出す
213+
</title>
214+
<programlisting role="php">
73215
<![CDATA[
74-
<?php
216+
<?php
75217
76-
// コールバック関数の例
218+
// An example callback function
77219
function my_callback_function() {
78220
echo 'hello world!', PHP_EOL;
79221
}
80222
81-
// コールバックメソッドの例
223+
// An example callback method
82224
class MyClass {
83225
static function myCallbackMethod() {
84226
echo 'Hello World!', PHP_EOL;
85227
}
86228
}
87229
88-
// タイプ 1: 単純なコールバック
89-
call_user_func('my_callback_function');
230+
// Type 1: Simple callback
231+
call_user_func('my_callback_function');
90232
91-
// タイプ 2: staticメソッドのコール
92-
call_user_func(array('MyClass', 'myCallbackMethod'));
233+
// Type 2: Static class method call
234+
call_user_func(['MyClass', 'myCallbackMethod']);
93235
94-
// タイプ 3: オブジェクトメソッドのコール
236+
// Type 3: Object method call
95237
$obj = new MyClass();
96-
call_user_func(array($obj, 'myCallbackMethod'));
238+
call_user_func([$obj, 'myCallbackMethod']);
97239
98-
// タイプ 4: staticメソッドのコール
240+
// Type 4: Static class method call
99241
call_user_func('MyClass::myCallbackMethod');
100242
101-
// タイプ 5: 相対指定によるstaticメソッドのコール
243+
// Type 5: Static class method call using ::class keyword
244+
call_user_func([MyClass::class, 'myCallbackMethod']);
245+
246+
// Type 6: Relative static class method call
102247
class A {
103248
public static function who() {
104249
echo 'A', PHP_EOL;
@@ -111,60 +256,41 @@ class B extends A {
111256
}
112257
}
113258
114-
call_user_func(array('B', 'parent::who')); // A, 但し PHP 8.2.0 以降は非推奨
259+
call_user_func(['B', 'parent::who']); // deprecated as of PHP 8.2.0
115260
116-
// タイプ 6: __invoke を実装したオブジェクトを callable として用いる
261+
// Type 7: Objects implementing __invoke can be used as callables
117262
class C {
118263
public function __invoke($name) {
119-
echo 'Hello ', $name, PHP_EOL;
264+
echo 'Hello ', $name;
120265
}
121266
}
122267
123268
$c = new C();
124269
call_user_func($c, 'PHP!');
125270
?>
126271
]]>
127-
</programlisting>
128-
</example>
129-
</para>
130-
<para>
131-
<example>
132-
<title>
133-
クロージャ (<classname>Closure</classname>) を使ったコールバックの例
134-
</title>
135-
<programlisting role="php">
272+
</programlisting>
273+
&example.outputs;
274+
<screen>
136275
<![CDATA[
137-
<?php
138-
// クロージャ
139-
$double = function($a) {
140-
return $a * 2;
141-
};
142-
143-
// 数値の範囲
144-
$numbers = range(1, 5);
276+
hello world!
277+
Hello World!
278+
Hello World!
279+
Hello World!
280+
Hello World!
145281
146-
// ここでクロージャをコールバックとして使用し、
147-
// 指定した範囲の各要素の二倍の値を計算します
148-
$new_numbers = array_map($double, $numbers);
149-
150-
print implode(' ', $new_numbers);
151-
?>
282+
Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
283+
A
284+
Hello PHP!
152285
]]>
153-
</programlisting>
154-
&example.outputs;
155-
<screen>
156-
<![CDATA[
157-
2 4 6 8 10
158-
]]>
159-
</screen>
160-
</example>
161-
</para>
286+
</screen>
287+
</example>
162288

163289
&note.func-callback-exceptions;
164290
</sect2>
165291

166292
</sect1>
167-
293+
168294
<!-- Keep this comment at the end of the file
169295
Local variables:
170296
mode: sgml

0 commit comments

Comments
 (0)