Question

Is my use of @global correct in the following case?

// File: my_special_class.php
<?php
...
class MySpecialClass {

    function display_template() {
        // Following variable will be available from context of 'template.php':
        $instance = array( 'title' => 'Test Page' );

        include('template.php');
    }

}

// File: template.php
<?php
/**
 * Template for ...
 *
 * @copyright Me
 * @version 1
 *
 * @global array $instance Template instance parameters.
 */
?>
<h1><?php echo $instance['title']; ?></h1>

Is there a standard way of documenting this?

It is primarily a reminder for those reading the code, but it would be useful if this information was also present under phpDocumentor generated documentation.

Answer 1

Actually, your $instance variable is not in the global scope, based on this code… it is local to the MySpecialClass::display_template() function only.

If you want to highlight, from the template.php documentation page, that there is something of significance to the reader with regard to the $instance variable, you could use the @see tag in template.php’s file-level docblock (the location that you currently have the @global tag) to point the reader to the MySpecialClass’s function that sets $instance:

<?php
/**
 * Template for ...
 *
 * @copyright Me
 * @version 1
 *
 * @see MySpecialClass::display_template() to see how $instance is populated
 */
?>
<h1><?php echo $instance['title']; ?></h1>