Add a README file

1 files changed, 51 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e3cb3f7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+mailTemplate - Send an email using a PHP template file.
+=======================================================
+
+mailTemplate($\_filename, $\_v) causes the PHP engine to parse the PHP file specified by #\_filename, with the variables
+passed in the variable #\_v, which should output an [RFC-822](https://tools.ietf.org/html/rfc822) (and its
+[successors](https://en.wikipedia.org/wiki/Email#Message_format)) style message.
+The function then extracts the headers from the message, grabs the "To" and "Subject" lines from it, and then passes
+the "To:", "Subject:", message body, and remaining headers, to the PHP
+[mail()](https://secure.php.net/manual/en/function.mail.php) function.
+
+As an example, consider template file "thanks.php"
+
+	To: <<?= $email ?>>
+	Subject: Thank you for your request
+	Content-Type: text/plain; charset=utf-8
+
+	Dear <?= $name =>,
+
+	Thankyou for your request, one of our staff will contact you <?= $when =>.
+	<?php if ($important) { ?>
+
+	Your request is important to us.
+	<?php } ?>
+   
+Which could then be called with:
+
+	mailTemplate("thanks.php", [
+		'email' => "dave@example.com",
+		'name' => "Dave",
+		'when' => "tomorrow",
+		'important' => FALSE,
+	]};
+
+Note that, as of this implementation, \_filename is read using
+[include](https://secure.php.net/manual/en/function.include.php), so it uses the file-finding rules defined therein.
+
+Also, it is worth remembering that PHP eats newlines directly following a PHP close tag. Therefore, if you have:
+
+	To: <?= $recipient ?>
+	Subject: ...
+
+Then the newline following the close tag will be eaten by the PHP parser, and you'll end up with:
+
+	To: example@example.comSubject: ...
+
+To work around this, you need to either make the closing tag not the last thing on the line (e.g. by adding a
+trailing space to the line), or forcibly output a newline yourself from within the PHP, e.g.:
+
+	To: <?= $recipient."\n" ?>
+	Subject: ...
+