Change phpdoc for files->render()

[BernhardBaumrock]

I'm using $files->render() often to get an array (like an array of translatable strings). The phpdoc states string|bool as return type which makes my IDE show a red line indicating an error that is actually none.

Would be great to change it to @return mixed as it could return any php data type.

https://github.com/processwire/processwire/blob/649d2569abc10bac43e98ca98db474dd3d6603ca/wire/core/WireFileTools.php#L854

This is how I'm using it:
https://github.com/BernhardBaumrock/RockTabulator/blob/9f50c14ddc356736b578b767f7f0fb62e6814cee/RockTabulator.module.php#L80
https://github.com/BernhardBaumrock/RockTabulator/blob/9f50c14ddc356736b578b767f7f0fb62e6814cee/_langs.php

[ryancramerdesign]

@BernhardBaumrock The $files->render() is handled by TemplateFile::render() and this method is designed only to return a string. It even goes through PHP's output buffering, appends/prepends strings to the output and runs it through PHP string functions, so it's a mystery to me how you have it returning an array. :) An interesting side effect.

If you are trying to get an array out of it wouldn't it be better to use PHP's include() instead? I'm reluctant to change the return value for this function since it's being used in a way it's not designed for, despite that it appears to be mysteriously working. However, I understand the need to resolve things that the IDE is calling out. I'm not sure what IDE you are using, but at least in PhpStorm, this works:

$result = $files->render(...); /** @var array $result */

Does that also enable it to resolve the IDE error in your environment?

[BernhardBaumrock]

Thx Ryan, interesting!

Your suggestion works indeed:

before:

after:

The more insteresting part is that render() is not designed for what I'm using it... But I do that often and I think it's a nice workflow. Using render() has the benefit of having all API variables available. That would not be the case on a regular php include(). Also it's nice to be able to define an array of variables that get passed to the rendered file!

I could also use $files->include(...), but that returns a boolean value. Take this example:

$files->include("test.php", ['foo' => 'bar']);
array_merge($result, $whatever);

The problem here is that it is not obvious that the variable in the file must be called $result. If that variable is not defined in that file, the code above would cause at least a warning that $result is not defined. So one would need to do extra checks (if(isset(...) ...) on every include(), which is a step back to what I have when using render().

IMHO it is a lot clearer to just return an array than setting a variable in that file:

// good:
return [
  'foo' => 'bar',
];

// not ideal:
$result = [
  'foo' => 'bar',
];

This might not be a big problem on such simple files, but it can be very comfortable to be able to do a quick if($foo === false) return; anywhere in the file which would lead to a NULL value returned that could be easily handled in the calling file:

$result = $files->render("test.php", ...);
if($result) {
  // whatever
}

Simple, clear, obvious, no errors or warnings.

Maybe a dedicated method for such scenarios could make sense? Something like $files->eval() or $files->execute() ?