4.0.0 Roadmap

[mattbasta]

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%

[mattbasta]

@vshen94 how do you feel about this?

[dkarvounaris]

I agree with capitalize, but truncate and date_format are useful in cases where as example overflow is not gonna do the same. As example, when text needs to be limited somewhere in size like meta-tags or other real cases I can remember encountered. Same with date_format.

[mattbasta]

@dkarvounaris My thinking around date_format is that it's just a weird wrapper around strftime, which you can use directly in your Brainy templates anyway. It would be better if a plugin existed that was the PHP equivalent of Moment.js (perhaps a wrapper around carbon? I don't know what the standard is). Since there's no L10n/i18n support baked in, date_format implies a best practice but actually leads developers to an antipattern. I'm not sure how we could make it better without hugely increasing the scope of the plugin. Ideas are absolutely welcome.

I have mixed feelings about truncate. It does in fact provide useful functionality, but most of that could be replicated simply by using {$foo|mb_substr($start, $end)}. The $middle option is weird and bad because it produces a string which is nonsensical to humans (this sentence would become The $middle option is weird ...which is nonsensical to humans with a length of 60). The break_words option doesn't work with languages that have non-Romance spacing rules.

My other concern with truncate is again around encouraging developers to do the right thing. If the plugin exists and works, it might discourage developers from using CSS properly and creating inaccessible and brittle UIs. Similar things have been seen within Box's codebase, especially in code written by folks that are not full-time front-end developers.

Please let me know if you think there's anything we can do to soften out these rough edges.

[vctrshn]

@mattbasta lgtm, big fan of removing a lot of those plugins.

Maybe another nice to have - Add some way to prevent including non-strict mode compatible files from templates with strict mode enabled, as we discussed before?

[mattbasta]

@vshen94 added

[dkarvounaris]

Ok, as long there are alternatives that are not too difficult to come up with, when needing such functionality.
As for developers doing the right thing, there will be always some that will find ways to not, you simply can't do that much there ;)
Those however who are experts and do their best for good practices, know their tools and understand pro's and con's of what they are using, usually.

[dkarvounaris]

The 4.0.0 will make it however even more difficult to switch from Smarty to Brainy obviously though, by removing these, some of these are some I've encountered in many templates often. More difficult to convince others to switch.
I'm all for the reduced compilation and IO calls though ;)

[mattbasta]

That's actually a great question that we should answer. Should we continue to try to meet parity with Smarty in these sorts of ways? We've already deviated pretty far. Maybe it's time to create a compatibility wrapper, or some kind of migration helper tool.

That said, the priorities of this project have always been security, speed, and code safety.

[vctrshn]

One more question - is the plan for 4.0.0 to directly make the jump to deleting plugins instead of hiding them behind strict mode as we have been in previous releases (ie for strip_tags)?

As for the migration helper tool, I can see how that may be useful - there were definitely some roadblocks during the upgrade process for each Brainy major version. Maybe even just a test harness of sorts that tries to compile all the templates in a given directory with a particular Brainy version? That would help catch a large portion of the breaking changes between versions.

Or are you talking more about writing a tool that will automagically convert existing Smarty templates to be compatible with Brainy 4 somehow?

The one thing I don't understand is why the migration process couldn't go through previous versions of Brainy first, instead of moving directly from Smarty to Brainy 4.0. In my head, rolling out a large scale migration like this is something that would be approached incrementally anyway. I'm not very familiar with how projects are generally managed - is it common practice in existing large projects to adopt a replacement for a framework by using the bleeding edge version of the replacement?

[mattbasta]

@vshen94 Those are all great questions.

My thought was to start getting rid of things that we've essentially marked as deprecated, and if we're cutting a new major version, no better time to break compatibility. It might be a terrible idea, though, so all ideas are welcome. I'm hesitant to keep growing strict mode, since using Brainy should already be strict mode in a way. In the same way that it's nonsense that you have to turn security features on in Smarty, it's kind of trashy hack that you have to turn strict mode on.

Regarding the migration tool, I was thinking something more along the lines of a linter. We don't even need to implement the full parser (though we could), since the grammar is rather terse and we could probably write rules for each of the things we're changing or removing. Obviously really dumb things like {$foo=$smarty}{$foo->template} would sneak through, but even if we did have a full and proper parser, Brainy isn't based on an AST, meaning static analysis would be nigh impossible. There's a deep rabbit hole there that's probably not worth exploring.

A tool that fixes compatibility errors would be impossible to build, since if we're removing something from Brainy, it wouldn't have anything to replace it with.

What you described with Smarty -> Brainy 1 -> ... -> Brainy 4 is actually exactly what the wiki recommends right now. An incremental migration is actually probably the safest way of going about an upgrade, but humans are lazy and for complex codebases, this might not be possible due to resource issues. Some people might have a relatively small project and want to just rip off the band-aid. Either way, it would be helpful to have a tool to point out problems, regardless of what source and target version you're upgrading between.

As someone who's helped with two very large production Brainy upgrades, what are your thoughts on such a thing? Worth it? Trash? Am I overthinking this?

[vctrshn]

Fair enough, and I agree that the default moving forward should be strict mode compliant.

We're in a slightly different world here since we don't have to rip off the band-aid, so the migration tool wouldn't be as useful, but I agree that it would be something to help make the transition much simpler. Not sure where the priority of that lies though, that's your call!