From 37b74f75786afd2019808cf35839ac632b754de3 Mon Sep 17 00:00:00 2001
From: Hartmut Holzgraefe <hholzgra@php.net>
Date: Fri, 4 Jul 2003 21:43:55 +0000
Subject: [PATCH] is_callable documented as suggested in user note / bug #21124
 credits go to php4 at developersdesk dot com

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@134197 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/var/functions/is-callable.xml | 99 +++++++++++++++----------
 1 file changed, 60 insertions(+), 39 deletions(-)

diff --git a/reference/var/functions/is-callable.xml b/reference/var/functions/is-callable.xml
index deb36c0cf7..e072e77fc4 100644
--- a/reference/var/functions/is-callable.xml
+++ b/reference/var/functions/is-callable.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/var.xml, last change in rev 1.87 -->
   <refentry id="function.is-callable">
    <refnamediv>
     <refname>is_callable</refname>
     <refpurpose>
-     Find out whether the argument is a valid callable construct
+     Verify that the contents of a variable can be called as a function
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -17,55 +17,76 @@
       <methodparam choice="opt"><type>string</type><parameter>callable_name</parameter></methodparam>
      </methodsynopsis>
     <para>
-     &warn.undocumented.func;
+     Verify that the contents of a variable can be called as a function.
+     This can check that a simple variable contains the name of a valid
+     function, or that an array contains a properly encoded object and
+     function name.
     </para>
-<!--
-    <simpara>
-     The <parameter>var</parameter> parameter is the name of a function or method.  
-     Also, class or object methods are specified by passing a numerical array with 
-     two elements: the class or object, and a method name.
-    </simpara>
-    <simpara>
-     The optional <parameter>syntax_only</parameter> parameter will check
-     only for syntax and defaults to &false;  The third <parameter>
-     callable_name</parameter> parameter is also optional.
-    </simpara>
     <para>
-     In our example below note, however, that despite the implication that 
-     <literal>a::b()</literal> is a callable static method, this is not the 
-     case.
-     <example>
-      <title>Using <function>is_callable</function></title>
-      <programlisting role="php">
+     The  var  parameter can be either the name of a function stored in
+     a string variable, or an object and the name of a method within the
+     object, like this: 
+     <screen>array( $SomeObject, 'MethodName' )</screen>
+    </para>
+    <para>
+     If the <parameter>syntax_only</parameter> argument is &true; the
+     function only verifies that <parameter>var</parameter> might be a
+     function or method. It will only reject simple variables that are
+     not strings, or an array that does not have a valid structure to be
+     used as a callback. The valid ones are supposed to have only 2
+     entries, the first of which is an object or a string, and the
+     second a string.
+    </para>
+    <para>
+     The <parameter>callable_name</parameter> argument receives the
+     "callable name".  In the example below it's
+     "someClass:someMethod".  Note, however, that despite the
+     implication that someClass::SomeMethod() is a callable static
+     method, this is not the case.
+    </para>
+    <informalexample>
+     <programlisting>
 <![CDATA[
-<?php
-class a 
-{
-    var $c;
-		
-    function b() {
-        return($this->c);
-    }
+<? php
+//  How to check a variable to see if it can be called
+//  as a function.
+
+//
+//  Simple variable containing a function
+//
+
+function someFunction() {
 }
 
-$d = new a;
+$functionVariable = 'someFunction';
 
-if(is_callable(array($d, 'b'), FALSE, $name)) {
+var_dump( is_callable( $functionVariable, false, $callable_name ));  // bool(true)
+
+echo $callable_name, "\n";  // someFunction
+
+//
+//  Array containing a method
+//
+
+class someClass {
+
+  function someMethod() {
+  }
 
-    echo $name;
 }
 
-/* The above will print:
-    
-    a::
+$anObject = new someClass();
+
+$methodVariable = array( $anObject, 'someMethod' );
+
+var_dump( is_callable( $methodVariable, true, $callable_name ));  //  bool(true)
+
+echo $callable_name, "\n";  //  someClass:someMethod
 
-*/
 ?>
 ]]>
-      </programlisting>
-     </example>
-    </para>
--->
+     </programlisting>
+    </informalexample>   
    </refsect1>
   </refentry>