Docs For Class msg

[line 77]
msg module class. The message module acts as a message repository and offers a centralized way to send event emails.

Message body is managed through Smarty templates stored in database. Message subject is also stored in db but not managed through Smarty. any {{$id_person}} in the html body gets replaced with the id of the person *receiving* the email. Example of use:

  require_once "common/classes/obliquid/msg.php";

  //creates an instance of the msg class
  $tpl_name="cal_meeting";
  $mymsg =& new msg();
  $mymsg->setName($tpl_name);
  if ($mymsg->getSubject($subject)) {
      //retrieves an empty Smarty template, understanding "msg:" resource
      $tpl =& $mymsg->getTemplate();
      //pass variables to the template
      $tpl->assign(array("p" => $p));
      //get the generated message, @ suppress Smarty warnings
      $body = @$tpl->fetch("msg:".$tpl_name);
      $mymsg->setTXTBody($body);
      //builds the extra headers
      $mymsg->SetFrom($name." ".$surname.<".$email.">");
      Any additional extra headers if needed, to be terminated with \r\n
      //$mymsg->setHeaders();
      //queue the emails
      $mymsg->queue($id_person);
      //sends unsent emails that are there longer than the configuration
      //parameter 'queue_min'
      $mymsg->runQueue();
  }

Smarty msg resource gets message body from the message repository. It gets only enabled messages. If no matching message is found Smarty will trigger a warning: "Warning: Smarty error: unable to read template resource:"

Tags:

version:	$Id: msg.php,v 1.37 2005/03/26 22:50:07 slocati Exp $
link:	Smarty templates from other sources

constructor msg [line 124]

void msg(
)

The constructor creates a new Smarty empty template for the message body, and registers the resource "msg" on it.

[ Top ]

method getMsgList [line 235]

an &getMsgList(
[boolean
$onlyenabled = false], [text
$onlyname = ""])

List all existing messages in the current language, if possible, otherwise

fetch them in another language

Tags:

return:

array with the list of messages. Each item is a indexed array with the following fields: (0 => module.name, 1 => msg_text.name, 2 => lang, 3 => subject, 4 => id_msg_text, 5 => msg_text.enable)

Parameters:

boolean	$onlyenabled	by default is false and will return all messages, if set to true, it will return only enabled messages
text	$onlyname	by default it's empty. If it's compiled it will return only the chosen message name

[ Top ]

method getSubject [line 155]

boolean getSubject(
string
&$subject)

Gets the subject line from the database for a message type, and sets it. It can be then changed with setSubject() if needed.

Picks the message in the language of the user, according to languages priorities, later msg class will have to be changed to send to each user in his own language

Tags:

return:

true if could retrieve the resource

Parameters:

string

$subject

the subject of the message

[ Top ]

method getTemplate [line 142]

void &getTemplate(
)

Returns the Smarty template inside the object with msg resource registered,

ready to be used to retrieve message templates from database

[ Top ]

method markSent [line 516]

void markSent(
mixed
$id_msg_queue)

Mark a message in the queue as sent

[ Top ]

method queue [line 322]

number queue(
[integer
$id_person = 0], [text
$callback = 0], [text
$callparms = 0])

Evaluates the message specified based on the rules, and queue zero or more emails.

How the rules work:

1) If a person is referenced by the optional $id_person parameter and it's not in a person or group block list for this $tpl_name, then he/she will receive the email.

2) If the group of a person is in the send list for this $tpl_name, he/she will receive the email, except when he/she's in the person block list for this $tpl_name

3) If the group of a person is in the block list for this $tpl_name, he/she won't receive the email, except when he/she's in the person send list for this $tpl_name

4) If a person is in the block list for this $tpl_name, he/she won't receive the email

5) If a person is in the send list for this $tpl_name, he/she will receive the email

6) A person will receive only one copy of the message even if multiple rules allow the sending

7) A person or a group shall not be in the send and block list for a $tpl_name at the same time. This rule is enforced already by the interface

Tags:

return:

of messages queued up to send

Parameters:

integer	$id_person	an optional person to whom the message is primarly addressed
text	$callback	callback function name
text	$callparms	callback function parameters

[ Top ]

method runQueue [line 431]

integer runQueue(
[boolean
$send = true])

Sends all emails in the queue only if there is one older than queue_min.

Only if there is an email older than queue_min (site configuration parameter) mail messages will be sent, otherwise they will be kept. Only 5 messages will be sent at a maximum, others will be kept until next queue run. The queue is run at each login try, no matter if successful or not, it can also be run manually within the message center.

Tags:

return:

number of sent emails, or number of emails that would have been sent

Parameters:

boolean

$send

optional parameter, normally true. if set to false it won't send any email

[ Top ]

method sendEmail [line 404]

void sendEmail(
mixed
$id)

Send the email inside the queue with the specified id and mark it as sent.

Only text emails are supported at the moment.

[ Top ]

method setFrom [line 220]

void setFrom(
$from
$from)

Sets the mail From: header

Parameters:

$from

$from

string in the form "Name Surname <email@example.com>"

[ Top ]

method setHeaders [line 212]

void setHeaders(
mixed
$headers)

Sets any extra raw header

[ Top ]

method setHTMLBody [line 206]

void setHTMLBody(
mixed
$htmlbody)

Sets the html body of the email

[ Top ]

method setName [line 134]

void setName(
mixed
$tpl_name)

Sets the Smarty template name, defined in table msg_text

[ Top ]

method setSendImmediately [line 186]

void setSendImmediately(
mixed
$sendImmediately)

Set sendImmediately to true to send the next message immediately, without waiting for queue times Please notice that runQueue() is not even necessary because the message will be sent inside the queue method. Messages sent with sendImmediately flag activated are never joined together.

This has been first implemented to send lost passwords without waiting the queue to run, that in our installation is run every 3 hours.

[ Top ]

method setSubject [line 194]

void setSubject(
mixed
$subject)

Sets the subject line to the specified value. This method should be called only when we want to change the predefined template subject.

[ Top ]

method setTXTBody [line 200]

void setTXTBody(
mixed
$txtbody)

Sets the plain text body of the email

[ Top ]

Class: msg

Class Overview

Author(s):

Version:

Methods

Inherited Variables

Inherited Methods

Class Details

Tags:

Class Methods

constructor msg [line 124]

method getMsgList [line 235]

Tags:

Parameters:

method getSubject [line 155]

Tags:

Parameters:

method getTemplate [line 142]

method markSent [line 516]

method queue [line 322]

Tags:

Parameters:

method runQueue [line 431]

Tags:

Parameters:

method sendEmail [line 404]

method setFrom [line 220]

Parameters:

method setHeaders [line 212]

method setHTMLBody [line 206]

method setName [line 134]

method setSendImmediately [line 186]

method setSubject [line 194]

method setTXTBody [line 200]