"Extending twig - defining functions" documentation is misleading

[katanacrimson]

Looking at the documentation for defining functions for use inside of twig templates, the documentation is very misleading.

"Adding a function is similar to adding a filter. This can be done by calling the addFunction() method on the Twig_Environment instance:"

<?php
    $twig = new Twig_Environment($loader);
    $twig->addFunction('functionName', new Twig_Function_Function('someFunction'));
    $twig->addFunction('otherFunction', new Twig_Function_Method($this, 'someMethod'));

What the variable $this is supposed to be is not even stated at all -- not a type, not an interface, nothing. By omitting these details, the documentation instead implies that the first param will accept any object that is passed.

The source code itself, however, shows this:

https://github.com/fabpot/Twig/blob/master/lib/Twig/Function/Method.php#L23
public function __construct(Twig_ExtensionInterface $extension, $method, array $options = array())

So, there's clearly a problem here. The way it is explained in the documentation is that you can provide an object and name a method, and twig will basically create a new "function" inside the templates that aliases to that method; looking at the source code however, you instead have to code a new object that implements a specific interface, fulfill the methods in the interface, and then work in your own code around that. This is much, much more complex.

The documentation and the reality of the implementation for Twig_Function_Method are worlds apart and definitely need rectified.

As a user, I'd like to see the implementation be modified to mirror what the documentation states (and not the other way around); having to do that much more work to import a function that is supposed to refer to an already-defined object method is cumbersome and ridiculous.

[stof]

The doc is true for the sentence you copied from it. Twig_Function_Method is very similar to Twig_Filter_Method which has exactly the constructor signature :)

[stof]

And allowing any objects is not possible at all due to the way the compiled template works. They would not have access to the object whereas the Twig extension is available through the environment. The Twig_Filter_Method and Twig_Function_Method are intended to be used when defining the filters and functions in a Twig extension.

[katanacrimson]

Then that should be clarified in the docs then. Assumptions and implications have no place in documentation.

[web-dev]

The $this psuedo variable actually has special meaning in php: it is the current instance of an object. This knowledge makes the documentation much clearer.

See:
http://www.php.net/manual/en/language.oop5.basic.php

[katanacrimson]

@web-dev obviously. It is, however, meaningless without _context_.

[sheikhan]

your doc is more misleading dude