box / brainy

A faster, safer templating library for PHP

Brainy

Brainy is a replacement for the popular Smarty templating language. It is a fork from the Smarty 3 trunk.

Brainy is still very new and it's likely that you will encounter some issues. Please report any problems that you encounter.

Why Brainy?

• Brainy generates clean and fast code by default.
• Brainy has security defaults that align better with best practices.
• Brainy does not include features that are infrequently used and increase code bloat.

Because Brainy is a fork of Smarty 3, it shares much of the same syntax and features while eliminating dangerous footguns and making it hard to write bad code.

Getting Started

Check out the Getting Started page on the wiki.

Minimum Requirements

• PHP 7.3+
• mbstring PHP extension

The mbstring extension is required in order to properly support Unicode in templates and user-provided content. Brainy 3 cannot be run in a mode that does not handle Unicode properly.

Contributing to Brainy

For information on how to set up a local dev environment and run the tests, see the wiki page on Hacking on Brainy.

Where is Brainy headed?

See the project roadmap for information on upcoming releases.

Requested Contributions

If you're interested in helping out, pull requests for the following tasks will be warmly welcomed:

• Convert all non-public methods to use camel case.
• Add proper PHPDoc annotations to all functions and methods.
• Refactoring:
  • Eliminate dead code
  • @ error suppression
  • Increase code coverage
  • etc.
• Help identify and resolve potential security issues, or find ways to help developers avoid security issues.
• Performance optimization of generated code

At the time of writing, the project has approximately 68% line coverage.

Support

Need to contact us directly? Email [email protected] and be sure to include the name of this project in the subject.

Copyright and License

Copyright 2014-2015 Box, Inc. All rights reserved.

Copyright 2002 – 2014 New Digital Group, Inc.

This library is licensed under the GNU Lesser Public License. A copy of the license should have been provided.

brainy's Issues

The 2.0.1 tag doesn't point to the right commit

Contributor permissions

It would be nice to have contributor permissions again. After all, I've got the most knowledge around how the code works and how it's used in practice.

Remove `$_IS_WINDOWS`

We should either refactor away the need for this or change it to use a proper means for detecting Windows environments.

Brainy 3 feature tracker

• {assign}
• {block}
• {break}
• {call}
• {capture}
• {continue}
• {extends}
• {function}
• {for}
• {forelse}
• {foreach}
• {foreachelse}
• {if}
• {elseif}
• {else}
• {include}
• {ldelim}
• {rdelim}
• {literal}
• {strip}
• {while}
• Smarty variable
  • $smarty.foreach
  • $smarty.capture
  • $smarty.now
  • $smarty.template
  • $smarty.version
  • $smarty.ldelim
  • $smarty.rdelim

Great work!

Just wanted to say that I'm quite excited to find this project. Keep up to good work! Looking forward for the version 3 awesomeness!

Brainy whitespace rules does not take into html entities (ie &nbsp)

4.0.0 Roadmap

Please update this issue with more.

Must-haves:

• Delete the html_* plugins for good, because they're scary
• Delete the count_* plugins, because they're mostly unused
• Delete the strip_tags plugin, since it's most likely not safe
• Delete all plugins banned in strict mode
• Delete the following plugins, because they violate web best practices:
  • capitalize: Use text-transform in CSS instead.
  • truncate: Use overflow and text-overflow in CSS instead.
  • date_format: Does not support proper localization, out of scope of Brainy.
• Remove the make_timestamp and escape_special_chars shared plugins, as they're only depended on by the plugins being removed above.
• Remove $smarty->template, which is banned in strict mode.
• Remove syntax features banned by strict mode.
• Remove support for built-in functions with side effects that are banned in strict mode: reset(), current(), etc.
• Remove SmartyBC.
• Remove the inline param from {include}.
• {* set stricter *} that requires all included templates to be strict

Nice-to-haves:

• AST-based parser and compiler
• Make it impossible to {include} or fetch a file outside of one of the recognized template directories.
• Mode that reports which assigned variables were not accessed
  • API should be similar to fetchedTemplate() overridable method
  • Should be enabled with a static flag
  • May be possible to implement by making the scope array inside TemplateData be an object implementing PHP's ArrayAccess interface with zero overhead while mode is off (no new code branches)
• Make buildFilepath not be insane.

Stretch:

• 80% code coverage
• ~100% code coverage for bundled plugins
• Cut compilation times by 25%
• Reduce IO-related PHP calls (filemtime, getcwd, etc.) by 25%

Ternary operator pls

It would be really darn cool if the ternary operator was a thing.

Right now:

{if $condition} 
    {$var = $true_option}   
{else}  
    {$var = $false_option}  
{/if}

Super premium:
{$var = $condition ? $true_option : $false_option}

Remove `secure_dir` support

Remove secure_dir from the Security class. It's no longer used, and fetching templates from a directory other than one provided is not allowed.

Ternary operators should propagate static wrappers up to modifier enforcement

{$var ? 'foo' : 'bar'} should not trigger modifier enforcement because there is no unsanitized data being returned.

Optimization: Compile safe lookups to individual methods

Currently, the safe lookup operation is compiled as a param to Lookups::safeLookup(). Removing the param and having one method per safe lookup type would cut down on branches and make it easier for HHVM to warm up.

Tests should be massaged to allow PHPUnit's `strict="true"`

There's plenty of work to be done to make the tests strict. Most of this involves making sure the tests produce no output.

Variable Variable prohibition in strict mode causes failures where it should not (as late as release 2.1.1)

{for $i=0 to $foo.bar.baz-1}
{for $i=0 to count($foo)-1}
{for $i=0 to count($foo)-1 step 2}
{for $i=1 to $foo}
{for $i=count($foo)-1 to 0 step -1}
{for $i=0 to 5 step 2}

Windows support

You recommend dropping the constant DIRECTORY_SEPARATOR and always use a forward slash. The code will be easier to read and the library will work on any system, including Windows. It currently fails on Windows because it tried to remove compiled template files without escaping the backslash, thus not forming correct paths.

P.S. The quick start guide is outdated. It took me a while to find out "new Box\Brainy\Brainy()".

Remove `allow_super_globals` support

allow_super_globals should be removed from the Security class. It is no longer used.

`$_valid` check in compiled templates should be wrapped in a function

This is for HHVM support. Currently it's in the root of the compiled file, which hh_client isn't happy about (because $_smarty_tpl is undefined when the template is inspected statically).