One of the advantages of templating is that you can delegate the non-programming bits of your application--design of HTML pages, wording of form letters, and so on--to people who aren't necessarily programmers. One of the disadvantages with powerful templating systems like Text::Template is that it only takes one joker to discover { system("rm -rf /") } and one or both of you is out of a job. Clearly there needs to be a way to secure your templates against this sort of abuse.

Text::Template offers two ways to protect yourself from this kind of coworker, um, I mean abuse. The first is through Perl's ordinary tainting mechanism. In taint mode, Perl will refuse to run templates from external files. This protects you from people meddling with the template files, but only because you can't use template files at all any more; you must specify templates as strings instead.

If you can actually trust the files in the filesystem, then you'll need to tell Text::Template to untaint the file data; this is done with the UNTAINT option:

  my $template = new Text::Template (TYPE => "FILE",
                                     UNTAINT => 1,
                                     SOURCE => $filename);

Now you will be able to use the template in $filename, if $filename itself has passed taint checks.

The second mechanism is much more fine-grained; the SAFE option allows you to specify a Safe compartment in which to run the code snippets:

  my $compartment = new Safe; # Default set of operations is pretty safe
  $text = $template->fill_in(SAFE => $compartment);

If you're really concerned about security, you'll want to do more tweaking than just using the default set of restricted operations.

What if things go wrong in other ways? You don't want your application to die if the code snippets contain invalid Perl, or throw a divide-by-zero error. While Text::Template traps eval errors by default, you may find yourself wanting more control of error handling. This is where the BROKEN option comes in.

The BROKEN option allows you to supply a subroutine reference to execute when a code snippet produces a syntax error or fails in any other way. Without BROKEN, you get a default error message inserted into your output:

  Dear Program fragment delivered error ``syntax error at template line 1'',

By specifying a BROKEN subroutine, you get more control over what is inserted into the output. In many cases, the only sensible thing to do if your template is broken would be to abort processing of the template altogether. You can do this by returning undef from your BROKEN routine, and Text::Template will return as much output as it was able to build up.

Of course, you now need to be able to tell whether the template completed successfully or whether it was aborted by a BROKEN routine. The way to do this is to use the callback argument BROKEN_ARG. If you pass a BROKEN_ARG to your template constructor, it will be passed into your BROKEN callback.* This allows us to do something like this:

  my $succeeded = 1;

  $template->fill_in(BROKEN => \&broken_sub, BROKEN_ARG => \$succeeded);

  if (!$suceeded) {
      die "Template failed to fill in...";
  }

  sub broken_sub {
      my %params = @_;
      ${$params{arg}} = 0;
      undef;
  }

As you can see, the callback is called with a hash; the argument specified by BROKEN_ARG is the arg element of the hash. In this case, that's a reference to the $succeeded flag; we dereference the reference and set the flag to zero, indicating an error, before returning undef to abort processing.

In case you feel you can make use of the broken template, Text::Template supplies the code snippet as the text element of the hash; I haven't been able to think of anything sensible to do with this yet. To assist with error reporting, the other entries in the hash are line, the line number in the template where the error occurred, and error, the value of $@ indicating the error.