Document usage of $data variable in Tpl or use UUID

[cstmth]

Description

To my understanding, templates and snippets are always provided with a $data variable. I could not find any documentation regarding that.

I just wanted to use an optional $data variable myself as a snippet attribute and found out that if I do not pass anything for it, I get the value of the ominous $data variable.

@fabianmichael told me the variable is being defined here: https://github.com/getkirby/kirby/blob/main/src/Filesystem/F.php#L423

Expected behavior

Fabian also suggested to

• either note this behaviour somewhere in the documentation
• or instead use a UUID, possibly somewhat like this:

function tpl($data) {
  $varName = '__' . bin2hex(random_bytes(16));
  $$varName = $data;
  unset($data);
  extract($$varName);
  // include template file
}

To reproduce

1. Use fresh Kirby Plainkit
2. Dump $data in template/snippet

Your setup

Kirby Version
5.0.4

[fabianmichael]

I thought about this a little further and changing the variable name to somehting random would be a problem in some instances, e.g. for nesting snippets. I use the pattern of extending snippets a lot and pass down variables from the "parent" snippet, where having $data variable is pretty handy. But it should detinitely be mentioned in the docs, that data cannot be used as param name or if it is used it can only be accessed via $data['data'].

[afbora]

Here's my thoughts on the UUID approach:

I think the random variable name solution might cause some problems in real use - debug issues, performance overhead and nested snippets.

Maybe simpler solution?

Looking at the current code, what if we just add $data to the protected variables with triple underscore and unset the $data variable? Like this:

protected static function loadIsolated(string $file, array $data = [])
{
    // extract the $data variables in this scope to be accessed by the included file;
    // protect $file and $data against being overwritten by user variables
    $___file___ = $file;
    $___data___ = $data;

    // Clear $data so users can use it
    unset($data);
    
    // Extract user variables (including any 'data' key they might have)
    extract($___data___);
    
    return include $___file___;
}

This is basically the current approach but also protects $data. Very small change but fixes the issue:

• Users can now use $data as parameter name
• No breaking changes
• Keeps the triple underscore pattern Kirby already uses
• Simple and clean

What do you think? This seems like the minimal change that solves the problem.

[fabianmichael]

@afbora After writing a few more snippets, I think it is more handy to keep it as is and make $data available in snippets. This comes in handy when nesting snippets and passing down variables to nested snippets.

In the company where I work, we use a base plugin for all of our project that provides snippets that can be overriden or extended. Example: The button is registred as something like components/button and additionally as base/components/button. That allows us to extend the button snippet in our projects by placing a snippet in site/snippets/components/button.php and just including the original button snippet by passing down $data (we have to unset $data['slot'] and $data['slots']). That means we basically rely on $data being available. The three-underscore-syntax would still work of course, but having the $data variable officially documented would probably my preferred choice by now.