User:Jonathans/tack

introduction
tack is a content templating system for PHP. this is the only paragraph of this document that is not written in e-prime.1

design philosophy
tack consists of one function. why? a template is really just a part of the view in the MVC architecture. in fact, it's the output.  your view code is not your view output. your view code doesn't belong in the view output. no code at all belongs in the output.  it was never necessary to put code into html, or even mini-languages that are pre-processed. a web designer is not supposed to perform a programmer's job -- even if they understand the view logic.2

the problem
most templating systems support too much logic in their parser. for a one-man team, this makes designers and programmers think they can step on each other's toes, when they go to do an MVC project with other people. obviously, the view is the duty of the designers! this is wrong.

designers work on the presentation and not the business logic of the application, and by this are responsible for the templates. they need some logic and flow control (if-then-else, for-each) to be able to envision and develop their project, especially without any knowledge of the business logic, but they don't need to put that logic into the template. that code belongs with the rest of the code.

the programmers are working under MVC; they will understand the logic when it is written in spec., and then they will code the view component to spec., and then changes to either the templates or the view code will not affect one another. sure, the site won't display correctly, but it will be immediately obvious in testing, because all of the logic is in one place.

a solution?
it my opinion that tack provides the most obvious solution to this problem, by forcing orthogonality into the projects in which it is implemented. there are other solutions, certainly, but many offer no comparable (and often downright miserable) scalability or too much mini-language (noose) to bungle the project (hang yourself) with.

tack-0.3.1
to obtain a copy of the source code to this version of tack, visit this temporary repository.

SYNOPSIS.
in_template a string of text containing any number of "template variables". these must conform to the regex declared in the header of tk_parse, described below. a match on a template variable that is not later found in key_pairs is eliminated from the output string, unless keep_unparsed_vars is true. regex_pattern ::= /\{\$[A-Z_0-9]+\}/  variables are alphanumeric and uppercase. variables may contain underscores. variables are prefixed with $. variables and their prefix are encapsulated with curly brackets: { }</li> </ol> key_pairs an array of  pairs where each   is the name of a target template variable, , to be discovered in the string in_template.

RETURN VALUES.
returns a copy of in_template, but with all instances of the keys in key_pairs replaced with the associated value. instances not located in key_pairs will be ignored. returns FALSE if input parameters are of the wrong type.

PERFORMANCE.
as of version 0.3.1, tack is comparable to smarty in processing time under certain loads. a benchmark was performed using a series of template files of particular size, each containing some number of template variables. values denoted as block data were then generated in kilobyte size of increasing powers of 2 and substituted into the input string.

the results are impressive. tack consists of one function and must perform regular expression matching on the template file during every pass -- although the regex itself is compiled only once -- and cannot cache the results, even though the template file itself does not change. smarty performs precaching of parsed templates, so that even as block data changes the template is encoded only once. smarty is a rather large and heavily featured object class, with plugins, and its cached templates are stored on disk. i believe this is where it lags behind.

this benchmark displays running times in msec for tk_parse, the library version of tack, alongside tpl_parse, the php version of tack, and a smarty object with caching turned on, using a 5kb template file.



this benchmark displays the same on a 40kb template file. values inbetween were similarly conclusive. the full benchmark report is available here.



issues at hand with this release are apparent. the overhead of using regular expressions is noticable on large template files. a precompiler for the files would be of significant value, but, a system of caching a binary compilation of this data is still under consideration.

USAGE.
it's really quite simple: &lt;? $arr = array('FOO' => 'world!'); var_dump(tk_parse('hello {$FOO}', $arr)); ?&gt;

your expected output: string(12): "hello world!"

and even after caching precompiler is finally implemented, this will likely not change.

tack-0.3.?
this section contains the design specification for the next revision of tack. the next revision intends to implement caching of templates to improve the performance of tack per machine.

the security implications of this new draft are obvious. tack will share all cached templates across all sites that the webserver is using php in. some kind of meshing with an external, safer cache system would be required to better secure this data. as it stands, any user can overwrite any template, which essentially equates to all content on any given page on any given site served by the host machine.

consider  a specialized   type. consider  a specialized   type.

tack_parse
calls  unless   found in table. calls  to fetch and parse the requested data. backwards compatible. slower than compile/execute when performing multiple parses of the same template, because of the hash check on each call.

tack_compile
compile a template and store it in cache, return a hash key to reference it. if an md5 collision occurs, do not compile, and return the hash. generate.

tack_execute
parse a precompiled template in cache with the given context.

tack_fetch
fetch the specified compiled template as a php array. useful for storing in memcached or something. maybe.

tack_store
complement function of. store a template expression in php  format in cache, addressed by the given hash, return true. if an md5 collision occurs, do not store, and return true. generate. return false if memory cannot be allocated or expression is in a bad format. caveat: this function cannot determine if hash is actually the compiled form of the original template string whose hash is provided.

tack_purge
clear the hash-specified template out of the cache, return true. if no template_hash is specified, clear out all template expressions from template cache. if an invalid hash is specified, return false.

MSHUTDOWN
tack_purge should be called on module shutdown, clearing all template expressions from cache.

errata
[1] i lied.

[2] actually, if they don't understand the logic, you might consider hiring someone who is not mentally retarded.