diff --git a/appendices/reserved.xml b/appendices/reserved.xml index 397f08f9ab..d949e44ca6 100644 --- a/appendices/reserved.xml +++ b/appendices/reserved.xml @@ -369,19 +369,15 @@ The predefined final class Closure was introduced - in PHP 5.3.0. It is used for internal implementation of anonymous functions. - The class has a constructor forbidding the manual creation of the object - (issues E_RECOVERABLE_ERROR) and the - __invoke method with the calling magic. + For more information, see its class + page. - - Special classes diff --git a/language/functions.xml b/language/functions.xml index 06978b3cd2..7281c5a0bc 100644 --- a/language/functions.xml +++ b/language/functions.xml @@ -746,10 +746,8 @@ print $my_cart->getTotal(0.05) . "\n"; - Anonymous functions are currently implemented using the - - Closure class. This is an implementation - detail and should not be relied upon. + Anonymous functions are implemented using the + Closure class. diff --git a/language/predefined/closure.xml b/language/predefined/closure.xml new file mode 100644 index 0000000000..f2aab4425c --- /dev/null +++ b/language/predefined/closure.xml @@ -0,0 +1,85 @@ + + + + + + The Closure class + Closure + + + + +
+ &reftitle.intro; + + Class used to represent anonymous + functions. + + + + Anonymous functions, implemented in PHP 5.3, yield objects of this type. + This fact used to be considered an implementation detail, but it can now + be relied upon. Starting with PHP 5.4, this class has methods that allow + further control of the anonymous function after it has been created. + + + + Besides the methods listed here, this class also has an + __invoke method. This is for consistency with other + classes that implement calling + magic, as this method is not used for calling the function. + + +
+ + +
+ &reftitle.classsynopsis; + + + + Closure + + + + + Closure + + + + + &Methods; + + + + +
+ + + + &language.predefined.closure.construct; + &language.predefined.closure.bind; + &language.predefined.closure.bindto; + + + + diff --git a/language/predefined/closure/bind.xml b/language/predefined/closure/bind.xml new file mode 100644 index 0000000000..cf91ad20ae --- /dev/null +++ b/language/predefined/closure/bind.xml @@ -0,0 +1,134 @@ + + + + + + Closure::bind + + Duplicates a closure with a specific bound object and class scope + + + + + &reftitle.description; + + public static ClosureClosure::bind + Closureclosure + objectnewthis + mixednewscope + 'static' + + + This method is a static version of Closure::bindTo. + See the documentation of that method for more information. + + + + + + &reftitle.parameters; + + + closure + + + The anonymous functions to bind. + + + + + newthis + + + The object to which the given anonymous function should be bound, or + &null; for the closure to be unbound. + + + + + newscope + + + The class scope to which associate the closure is to be associated, or + 'static' to keep the current one. If an object is given, the type of the + object will be used instead. This determines the visibility of protected + and private methods of the bound object. + + + + + + + + &reftitle.returnvalues; + + Returns a new Closure object &return.falseforfailure; + + + + + &reftitle.examples; + + <function>Closure::bind</function> example + +ifoo; +}; + +$bcl1 = Closure::bind($cl1, null, 'A'); +$bcl2 = Closure::bind($cl2, new A(), 'A'); +echo $bcl1(), "\n"; +echo $bcl2(), "\n"; +?> +]]> + + &example.outputs.similar; + + + + + + + + + &reftitle.seealso; + + Anonymous functions + Closure::bindTo + + + + + + diff --git a/language/predefined/closure/bindto.xml b/language/predefined/closure/bindto.xml new file mode 100644 index 0000000000..bc3cfd970b --- /dev/null +++ b/language/predefined/closure/bindto.xml @@ -0,0 +1,160 @@ + + + + + + Closure::bindTo + + Duplicates the closure with a new bound object and class scope + + + + + &reftitle.description; + + public ClosureClosure::bindTo + objectnewthis + mixednewscope + 'static' + + + Create and return a new anonymous + function with the same body and bound variables as this one, but + possibly with a different bound object and a new class scope. + + + + The “bound object” determines the value $this will + have in the function body and the “class scope” represents a class + which determines which private and protected members the anonymous + function will be able to access. Namely, the members that will be + visible are the same as if the anonymous function were a method of + the class given as value of the newscope + parameter. + + + + Static closures cannot have any bound object (the value of the parameter + newthis should be &null;), but this function can + nevertheless be used to change their class scope. + + + + This function will ensure that for a non-static closure, having a bound + instance will imply being scoped and vice-versa. To this end, + non-static closures that are given a scope but a &null; instance are made + static and non-static non-scoped closures that are given a non-null + instance are scoped to an unspecified class. + + + + + If you only want to duplicate the anonymous functions, you can use + cloning instead. + + + + + + + &reftitle.parameters; + + + newthis + + + The object to which the given anonymous function should be bound, or + &null; for the closure to be unbound. + + + + + newscope + + + The class scope to which associate the closure is to be associated, or + 'static' to keep the current one. If an object is given, the type of the + object will be used instead. This determines the visibility of protected + and private methods of the bound object. + + + + + + + + &reftitle.returnvalues; + + Returns the newly created Closure object + &return.falseforfailure; + + + + + &reftitle.examples; + + <function>Closure::bindTo</function> example + +val = $val; + } + function getClosure() { + //returns closure bound to this object and scope + return function() { return $this->val; }; + } +} + +$ob1 = new A(1); +$ob2 = new A(2); + +$cl = $ob1->getClosure(); +echo $cl(), "\n"; +$cl = $cl->bindTo($ob2); +echo $cl(), "\n"; +]]> + + &example.outputs.similar; + + + + + + + + + &reftitle.seealso; + + Anonymous functions + Closure::bind + + + + + + diff --git a/language/predefined/closure/construct.xml b/language/predefined/closure/construct.xml new file mode 100644 index 0000000000..39e4dc2a24 --- /dev/null +++ b/language/predefined/closure/construct.xml @@ -0,0 +1,69 @@ + + + + + + Closure::__construct + Constructor that disallows instantiation + + + + &reftitle.description; + + Closure::__construct + + + + This method exists only to disallow instantiation of the + Closure class. Objects of this class are created + in the fashion described on the + anonymous functions page. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + This method has no return value; it simply emits an error + (of type E_RECOVERABLE_ERROR). + + + + + + &reftitle.seealso; + + + Anonymous functions + + + + + + + diff --git a/language/predefined/interfaces.xml b/language/predefined/interfaces.xml index 73404bf380..7e44f7bd65 100644 --- a/language/predefined/interfaces.xml +++ b/language/predefined/interfaces.xml @@ -15,6 +15,7 @@ &language.predefined.iteratoraggregate; &language.predefined.arrayaccess; &language.predefined.serializable; + &language.predefined.closure;