Smarty for e-mail templates

November 29th, 2009

As you’ve realized Smarty can be used to more than just site templates. You can set up templates for almost anything, for example e-mails. When you do this you have to decide on an approach, and I’ll cover three of them here.

Simple and straightforward
You can see this approach in the Smarty manual. The template simply states the message body, and if you have multiple bodies, say one in plain text and one in HTML, you can do like this.

mail.text.tpl:
Hi {$name},

You've got mail!

mail.html.tpl:
// HTML-header here
<body>
<h1>Hi {$name},</h1>

<p>You've got mail!</p>
</body>

Now you can simply fetch your two versions of the mail body and use them with your PHP code to send mails. The benefit here is that you keep a good abstraction, the person who makes the mail templates does not have to care about hos the mail is sent. A drawback is that you can’t store all information for this e-mail in one place; where do you store the subject?

The advanced solution
The advanced solution creates just one template containing all data needed for the e-mail message. Your template could look like this:
gotmail.mail.tpl:
Date: {$mail.date|date_format:"%a, %d %b %Y %H:%M:%S %z"}
From: "{$sender.name}" <{$sender.email}>
To: "{$recipient.name}" <{$recipient.email}>
Subject: New mail

Hi {$recipient.name},

You've got mail!

Here you just fetch the mail data and sends it. The benefit is that you store all data related to the e-mail at the same place. The drawbacks are that this method needs extra parsing to work with the built-in PHP mail() function and the abstraction is poor since the person creating the template now has to know how to enter all mail headers as well.

Best of all?
In this version you get the benefits from the two previous versions, eleminating the drawbacks. Here we can store all information about the e-mail in the template and we can still use them when sending the e-mail using PHP. Consider this template:
gotmail.mail.tpl:
Hi {$name},

You've got mail!
{assign var="subject" value="New mail"}

Now you can, as in the simple version, fetch the template to get the body text and then use the get_template_vars() Smarty method to get the subject from the template. Just apply some more Smarty tweaking using the built-in {capture} function or simply {insert} the templates from the first example to get a multi-body message in just one template file.

The code above should be considered as proof-of-concept or pseudo code, there are a few problems not solved in the examples above.

DocBook for PHP, a tool you can’t afford to ignore

November 27th, 2009

You’ve heard it before but it’s worth mentioning again - you have to properly document you code! Programmers realized this back in the 1960s when the first industrial programming languages were defined, they came up with something called “comment lines”. For 27 years this was apparently considered enough, but in 1993 the first documentation generator was created by Eric Artzt, called Autoduck. Two years later, in 1995, a more commonly known documentation generator was released by Sun Microsystems, called Javadoc. In the year 2000 a similar generator was created by Joshua Eichorn for PHP, called the phpDocumentor and it’s this documentation generator that is the reason why I’m writing this post.

I’ve been using phpDocumentor for quite some time now but only to parse my classes to get an overview. Now I’m building a framework. I soon realized that writing a tutorial for each class wasn’t what I wanted. It’s always good with examples but it doesn’t show how a bunch of classes work together to solve a larger problem. I want to collect all documentation in one place so it’s impractical to write tutorials stored in some other place. So, for the first time I decided I’d take a look at the possibility to use external documentation with phpDocumentor.

DocBook “provides a system for writing structured documents using SGML or XML”, as stated in the preface in the DocBook documentation. It’s used in development projects like PHP and KDE. Although the PEAR manual states that DocBook should be used, nothing is said about the document type and no example is given. Instead, I found an short example in the phpDocumentor quickstart document. A more elementary example than that is hard to find, but if you combine that with the documentation about how you create a reference page in the DocBook documentation you’ll understand what you are doing. You don’t have to use the <refentry> top-level element but it is recommended if your code may become part of PEAR.

Since the phpDocumentor parses the DocBook file you can use some of the phpDocumentor syntax in your external documentation. It’s mainly two tags that you’ll use in your external documentation, and that’s the {@id} and {@toc} tags. The {@link} may also be useful to link between documents. There’s no need for me to dig any deeper in this, you can read a great tutorial about how to write tutorials for PHP at the phpDocumentor site.

Good luck!

Evolution of religion

January 11th, 2009

Since this can be a sensitive subject I guess I’ll start to say that this is a post of a more philosophic nature. Many religions contains wise formulations about common sense that’s being abused and used as a front to gain power at many levels. With that said - let’s go…

In the beginning the religion was used to explain things that couldn’t be described with the knowledge at that point. This kind of religion is often called animism or shamanism and reaches back to the hunter-gatherers, that’s more than 15,000 years ago. The two are very similar in that they both states that the world we live in have spirits, they differ in what role the spirits have though.

The religion then evolved into what’s called polytheism. It means that you believe in multiple gods and you surely have heard of both the Roman mythology and the Greek mythology. Now the stories got a more human form but does not distinguish good from bad, both heroes and gods shows both good and bad sides. The mythologies developed when societies were founded and villages started to grow into cities. The human was no longer considered to be a part of nature but superior to it and thus the respect for animals, plants and natural forces decreased. When living in a society the need for rules and laws grows with the size of the society. As a result the religions we know as of today was formed containing rules for how to treat your neighbours.

During the time when, among others, Christianity was formed and documented or translated, politics and rhetorics had started to grow of importance with the Roman Empire. These new religions was a perfect target for greedy people to influence and inflict the new documents with hidden messages or just state that a certain interpretation is the correct one. There are many examples of how this is abused and how it changes over time. I do not maintain that the “modern” religions was the first ones to be used to gain power, I’m stating that they resulted in an opportunity to spread the message to a larger crowd.

In my opinion it’s obvious that the opportunity to power exists since Christianity ended up as being centrally controlled by the Holy See. A power that in many cases have lead to megalomania with disastrous, and sometimes amusing, results. A recent historic happening is the discovering of the Dead Sea scrolls, where you can get a good picture of the power that the Holy See can inflict.

Religious texts is often studied according to rhetorical principals that for reasons may not be used in modern law practice. This may, or may not, be a good thing, depends on the text and its message, but it’s something that you have to keep in mind when reading. After all, the purpose of the modern religions is to achieve compassion between people, a fantastic thing ruined by false interpretation of the word - call it “free will” if you like. I call it greed.