eda00738babd1365478b81bb8adb4645b2b8bfbf
[core.git] / inc / classes / main / template / mail / class_MailTemplateEngine.php
1 <?php
2 /**
3  * The own template engine for loading caching and sending out images
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Core Developer Team
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.ship-simu.org
10  * @todo                This template engine does not make use of setTemplateType()
11  *
12  * This program is free software: you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation, either version 3 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program. If not, see <http://www.gnu.org/licenses/>.
24  */
25 class MailTemplateEngine extends BaseTemplateEngine implements CompileableTemplate {
26         /**
27          * Main nodes in the XML tree
28          */
29         private $mainNodes = array(
30                 'mail-data'
31         );
32
33         /**
34          * Sub nodes in the XML tree
35          */
36         private $subNodes = array(
37                 'subject-line',
38                 'sender-address',
39                 'recipient-address',
40                 'message'
41         );
42
43         /**
44          * Mailer instance
45          */
46         private $mailerInstance = null;
47
48         /**
49          * Current main node
50          */
51         private $currMainNode = '';
52
53         /**
54          * Protected constructor
55          *
56          * @return      void
57          */
58         protected function __construct () {
59                 // Call parent constructor
60                 parent::__construct(__CLASS__);
61         }
62
63         /**
64          * Creates an instance of the class TemplateEngine and prepares it for usage
65          *
66          * @param       $applicationInstance    A manageable application
67          * @return      $templateInstance               An instance of TemplateEngine
68          * @throws      BasePathIsEmptyException                If the provided $templateBasePath is empty
69          * @throws      InvalidBasePathStringException  If $templateBasePath is no string
70          * @throws      BasePathIsNoDirectoryException  If $templateBasePath is no
71          *                                                                                      directory or not found
72          * @throws      BasePathReadProtectedException  If $templateBasePath is
73          *                                                                                      read-protected
74          */
75         public static final function createMailTemplateEngine (ManageableApplication $applicationInstance) {
76                 // Get a new instance
77                 $templateInstance = new MailTemplateEngine();
78
79                 // Determine base path
80                 $templateBasePath = $templateInstance->getConfigInstance()->getConfigEntry('application_base_path') . $applicationInstance->getRequestInstance()->getRequestElement('app') . '/';
81
82                 // Is the base path valid?
83                 if (empty($templateBasePath)) {
84                         // Base path is empty
85                         throw new BasePathIsEmptyException($templateInstance, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
86                 } elseif (!is_string($templateBasePath)) {
87                         // Is not a string
88                         throw new InvalidBasePathStringException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_STRING);
89                 } elseif (!is_dir($templateBasePath)) {
90                         // Is not a path
91                         throw new BasePathIsNoDirectoryException(array($templateInstance, $templateBasePath), self::EXCEPTION_INVALID_PATH_NAME);
92                 } elseif (!is_readable($templateBasePath)) {
93                         // Is not readable
94                         throw new BasePathReadProtectedException(array($templateInstance, $templateBasePath), self::EXCEPTION_READ_PROTECED_PATH);
95                 }
96
97                 // Set the base path
98                 $templateInstance->setTemplateBasePath($templateBasePath);
99
100                 // Set template extensions
101                 $templateInstance->setRawTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('raw_template_extension'));
102                 $templateInstance->setCodeTemplateExtension($templateInstance->getConfigInstance()->getConfigEntry('code_template_extension'));
103
104                 // Absolute output path for compiled templates
105                 $templateInstance->setCompileOutputPath($templateInstance->getConfigInstance()->getConfigEntry('base_path') . $templateInstance->getConfigInstance()->getConfigEntry('compile_output_path'));
106
107                 // Return the prepared instance
108                 return $templateInstance;
109         }
110
111         /**
112          * Getter for current main node
113          *
114          * @return      $currMainNode   Current main node
115          */
116         public final function getCurrMainNode () {
117                 return $this->currMainNode;
118         }
119
120         /**
121          * Getter for main node array
122          *
123          * @return      $mainNodes      Array with valid main node names
124          */
125         public final function getMainNodes () {
126                 return $this->mainNodes;
127         }
128
129         /**
130          * Getter for sub node array
131          *
132          * @return      $subNodes       Array with valid sub node names
133          */
134         public final function getSubNodes () {
135                 return $this->subNodes;
136         }
137
138         /**
139          * Handles the start element of an XML resource
140          *
141          * @param       $resource               XML parser resource (currently ignored)
142          * @param       $element                The element we shall handle
143          * @param       $attributes             All attributes
144          * @return      void
145          * @throws      InvalidXmlNodeException         If an unknown/invalid XML node name was found
146          */
147         protected function startElement ($resource, $element, array $attributes) {
148                 // Initial method name which will never be called...
149                 $methodName = 'initEmail';
150
151                 // Make the element name lower-case
152                 $element = strtolower($element);
153
154                 // Is the element a main node?
155                 //* DEBUG: */ echo "START: &gt;".$element."&lt;<br />\n";
156                 if (in_array($element, $this->getMainNodes())) {
157                         // Okay, main node found!
158                         $methodName = 'setEmail' . $this->convertToClassName($element);
159                 } elseif (in_array($element, $this->getSubNodes())) {
160                         // Sub node found
161                         $methodName = 'setEmailProperty' . $this->convertToClassName($element);
162                 } elseif ($element != 'text-mail') {
163                         // Invalid node name found
164                         throw new InvalidXmlNodeException(array($this, $element, $attributes), XmlParser::EXCEPTION_XML_NODE_UNKNOWN);
165                 }
166
167                 // Call method
168                 //* DEBUG: */ echo "call: ".$methodName."<br />\n";
169                 call_user_func_array(array($this, $methodName), $attributes);
170         }
171
172         /**
173          * Ends the main or sub node by sending out the gathered data
174          *
175          * @param       $resource       An XML resource pointer (currently ignored)
176          * @param       $nodeName       Name of the node we want to finish
177          * @return      void
178          * @throws      XmlNodeMismatchException        If current main node mismatches the closing one
179          */
180         protected function endElement ($resource, $nodeName) {
181                 // Make all lower-case
182                 $nodeName = strtolower($nodeName);
183
184                 // Does this match with current main node?
185                 //* DEBUG: */ echo "END: &gt;".$nodeName."&lt;<br />\n";
186                 if (($nodeName != $this->getCurrMainNode()) && (in_array($nodeName, $this->getMainNodes()))) {
187                         // Did not match!
188                         throw new XmlNodeMismatchException (array($this, $nodeName, $this->getCurrMainNode()), XmlParser::EXCEPTION_XML_NODE_MISMATCH);
189                 } elseif (in_array($nodeName, $this->getSubNodes())) {
190                         // Silently ignore sub nodes
191                         return;
192                 }
193
194                 // Construct method name
195                 $methodName = 'finish' . $this->convertToClassName($nodeName);
196
197                 // Call the corresponding method
198                 call_user_func_array(array($this, $methodName), array());
199         }
200
201         /**
202          * Adds the message text to the template engine
203          *
204          * @param       $resource               XML parser resource (currently ignored)
205          * @param       $characters             Characters to handle
206          * @return      void
207          */
208         protected function characterHandler ($resource, $characters) {
209                 // Trim all spaces away
210                 $characters = trim($characters);
211
212                 // Is this string empty?
213                 if (empty($characters)) {
214                         // Then skip it silently
215                         return false;
216                 } // END - if
217
218                 // Add the message now
219                 $this->assignVariable('message', $characters);
220         }
221
222         /**
223          * Intializes the mail
224          *
225          * @return      void
226          * @todo        Add cache creation here
227          */
228         private function initEmail () {
229                 // Unfinished work!
230         }
231
232         /**
233          * Setter for mail data node
234          *
235          * @return      void
236          * @todo        Should we call back the mailer class here?
237          */
238         private function setEmailMailData () {
239                 // Set current main node
240                 $this->currMainNode = 'mail-data';
241         }
242
243         /**
244          * Setter for sender address property
245          *
246          * @param       $senderAddress  Sender address to set in email
247          * @return      void
248          */
249         private function setEmailPropertySenderAddress ($senderAddress) {
250                 // Set the template variable
251                 $this->assignVariable('sender', $senderAddress);
252         }
253
254         /**
255          * Setter for recipient address property
256          *
257          * @param       $recipientAddress       Recipient address to set in email
258          * @return      void
259          */
260         private function setEmailPropertyRecipientAddress ($recipientAddress) {
261                 // Set the template variable
262                 $this->assignVariable('recipient', $recipientAddress);
263         }
264
265         /**
266          * Setter for subject line property
267          *
268          * @param       $subjectLine    Subject line to set in email
269          * @return      void
270          */
271         private function setEmailPropertySubjectLine ($subjectLine) {
272                 // Set the template variable
273                 $this->assignVariable('subject', $subjectLine);
274         }
275
276         /**
277          * Method stub to avoid output
278          *
279          * @return      void
280          */
281         private function setEmailPropertyMessage () {
282                 // Empty for now
283         }
284
285         /**
286          * Gets the template variable "message", stores it back as raw template data
287          * and compiles all variables so the mail message got prepared for output
288          *
289          * @return      void
290          */
291         private function finishMailData () {
292                 // Get the message and set it as new raw template data back
293                 $message = $this->readVariable('message');
294                 $this->setRawTemplateData($message);
295
296                 // Get some variables to compile
297                 //$sender = $this->compileRawCode($this->readVariable('sender'));
298                 //$this->assignVariable('sender', $sender);
299
300                 // Then compile all variables
301                 $this->compileVariables();
302         }
303
304         /**
305          * Invokes the final mail process
306          *
307          * @return      void
308          */
309         private function finishTextMail () {
310                 $this->getMailerInstance()->invokeMailDelivery();
311         }
312
313         /**
314          * Getter for image cache file (FQFN)
315          *
316          * @return      $fqfn   Full-qualified file name of the image cache
317          * @todo        0% done
318          */
319         public function getMailCacheFqfn () {
320                 // Initialize FQFN
321                 $fqfn = '';
322                 $this->debugBackTrace();
323
324                 // Return it
325                 return $fqfn;
326         }
327
328         /**
329          * Setter for mailer instance
330          *
331          * @param       $mailerInstance         A mailer instance
332          * @return      void
333          */
334         public final function setMailerInstance (DeliverableMail $mailerInstance) {
335                 $this->mailerInstance = $mailerInstance;
336         }
337
338         /**
339          * Getter for mailer instance
340          *
341          * @return      $mailerInstance         A mailer instance
342          */
343         protected final function getMailerInstance () {
344                 return $this->mailerInstance;
345         }
346
347         /**
348          * Outputs the mail to the world. This should only the mailer debug class do!
349          *
350          * @param       $responseInstance       An instance of a Responseable class
351          * @return      void
352          */
353         public function transferToResponse (Responseable $responseInstance) {
354                 $responseInstance->writeToBody($this->getCompiledData());
355         }
356 }
357
358 // [EOF]
359 ?>