Location: PHPKode > scripts > Log watcher > log-watcher/log_watcher_class.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Class: Log watcher</title>
</head>
<body>
<center><h1>Class: Log watcher</h1></center>
<hr />
<ul>
<p><b>Version:</b> <tt>@(#) $Id: log_watcher_class.php,v 1.4 2004/07/27 07:55:36 mlemos Exp $</tt></p>
<h2><a name="table_of_contents">Contents</a></h2>
<ul>
<li><a href="#2.1.1">Summary</a></li>
<ul>
<li><a href="#3.2.0">Name</a></li>
<li><a href="#3.2.0.0">Author</a></li>
<li><a href="#3.2.0.1">Copyright</a></li>
<li><a href="#3.2.0.2">Version</a></li>
<li><a href="#3.2.0.3">Purpose</a></li>
<li><a href="#3.2.0.4">Usage</a></li>
</ul>
<li><a href="#4.1.1">Variables</a></li>
<ul>
<li><a href="#5.2.11">error</a></li>
<li><a href="#5.2.12">log_file_name</a></li>
<li><a href="#5.2.13">log_pointer_extension</a></li>
<li><a href="#5.2.14">watcher_email</a></li>
<li><a href="#5.2.15">watcher_name</a></li>
<li><a href="#5.2.16">system_email</a></li>
<li><a href="#5.2.17">system_name</a></li>
<li><a href="#5.2.18">mailer</a></li>
<li><a href="#5.2.19">mail</a></li>
<li><a href="#5.2.20">report_message_template</a></li>
</ul>
<li><a href="#6.1.1">Functions</a></li>
<ul>
<li><a href="#7.2.5">OpenLog</a></li>
<li><a href="#7.2.6">GetNewLogLine</a></li>
<li><a href="#9.2.7">MailNews</a></li>
<li><a href="#11.2.8">CloseLog</a></li>
</ul>
</ul>
<p><a href="#table_of_contents">Top of the table of contents</a></p>
</ul>
<hr />
<ul>
<h2><li><a name="2.1.1">Summary</a></li></h2>
<ul>
<h3><a name="3.2.0">Name</a></h3>
<p>Log watcher</p>
<h3><a name="3.2.0.0">Author</a></h3>
<p>Manuel Lemos (<a href="mailto:hide@address.com">hide@address.com</a>)</p>
<h3><a name="3.2.0.1">Copyright</a></h3>
<p>Copyright &copy; (C) Manuel Lemos 2003</p>
<h3><a name="3.2.0.2">Version</a></h3>
<p>@(#) $Id: log_watcher_class.php,v 1.4 2004/07/27 07:55:36 mlemos Exp $</p>
<h3><a name="3.2.0.3">Purpose</a></h3>
<p>Watch a log file and send the newly added log lines to a given e-mail address.</p>
<h3><a name="3.2.0.4">Usage</a></h3>
<p>Set the <tt><a href="#variable_log_file_name">log_file_name</a></tt> variable with the name of the log file that is meant to be watched.</p>
<p> Call the function <tt><a href="#function_OpenLog">OpenLog</a></tt> to start watching a new log file or to resume watching a previously analysed log file.</p>
<p> Call the function <tt><a href="#function_MailNews">MailNews</a></tt> to send the newly added log file lines to the e-mail address specified by the variable <tt><a href="#variable_watcher_email">watcher_email</a></tt>.</p>
<p> Call the function <tt><a href="#function_CloseLog">CloseLog</a></tt> to close the log file and store the position of the current end of log line in the pointer file. The pointer file name is defined by the <tt><a href="#variable_log_file_name">log_file_name</a></tt> variable appending the <tt><a href="#variable_log_pointer_extension">log_pointer_extension</a></tt> configuration variable value.</p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="variables"></a><a name="4.1.1">Variables</a></li></h2>
<ul>
<li><tt><a href="#variable_error">error</a></tt></li><br />
<li><tt><a href="#variable_log_file_name">log_file_name</a></tt></li><br />
<li><tt><a href="#variable_log_pointer_extension">log_pointer_extension</a></tt></li><br />
<li><tt><a href="#variable_watcher_email">watcher_email</a></tt></li><br />
<li><tt><a href="#variable_watcher_name">watcher_name</a></tt></li><br />
<li><tt><a href="#variable_system_email">system_email</a></tt></li><br />
<li><tt><a href="#variable_system_name">system_name</a></tt></li><br />
<li><tt><a href="#variable_mailer">mailer</a></tt></li><br />
<li><tt><a href="#variable_mail">mail</a></tt></li><br />
<li><tt><a href="#variable_report_message_template">report_message_template</a></tt></li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
<h3><a name="variable_error"></a><li><a name="5.2.11">error</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>Store the message that is returned when an error occurs.</p>
<h3>Usage</h3>
<p>Check this variable to understand what happened when a call to any of the class functions has failed.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_log_file_name"></a><li><a name="5.2.12">log_file_name</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>Name of the log file to watch.</p>
<h3>Usage</h3>
<p>Set this variable to the full or relative path of the log file before it is watched by the class functions.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_log_pointer_extension"></a><li><a name="5.2.13">log_pointer_extension</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>'.ptr'</tt></p>
<h3>Purpose</h3>
<p>Extension to append to the log file name to define the name of the file where is stored a pointer that records the last log line that was processed.</p>
<h3>Usage</h3>
<p>Change this variable only of the default is not suitable.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_watcher_email"></a><li><a name="5.2.14">watcher_email</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>E-mail address of the person that will be notified about the new log lines.</p>
<h3>Usage</h3>
<p>Set this variable with the address to where the report of the new log lines is sent by the function <tt><a href="#function_MailNews">MailNews</a></tt>.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_watcher_name"></a><li><a name="5.2.15">watcher_name</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>Name of the person that will be notified about the new log lines.</p>
<h3>Usage</h3>
<p>Setting this variable is optional.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_system_email"></a><li><a name="5.2.16">system_email</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>E-mail address of the system that will be sending the new log lines report messages.</p>
<h3>Usage</h3>
<p>Set this variable with the address that will be used by the function <tt><a href="#function_MailNews">MailNews</a></tt> as sender of the messages. If possible, this address will also serve as bounce address in case it is not possible to deliver the messages for some reason.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_system_name"></a><li><a name="5.2.17">system_name</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>'Log Watcher'</tt></p>
<h3>Purpose</h3>
<p>Name of the person that will be notified about the new log lines.</p>
<h3>Usage</h3>
<p>Setting this variable is optional.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_mailer"></a><li><a name="5.2.18">mailer</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>'http://www.phpclasses.org/logwatcher $Revision: 1.4 $'</tt></p>
<h3>Purpose</h3>
<p>Identification of the mailer system that is specified in the <tt>X-Mailer:</tt> headers as sender of the report e-mail messages.</p>
<h3>Usage</h3>
<p>Do not change this variable unless you have a reason to change the identification of the mailer system that is sending the report messages.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_mail"></a><li><a name="5.2.19">mail</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>Name of the global function that will be called to send e-mail messages.</p>
<h3>Usage</h3>
<p>If for some reason the PHP mail() function does not work in your environment or you prefer to use a better alternative, set this variable to the name of the alternative global function. It should take the same parameters as the PHP mail() function.</p>
<p> If this variable is set to an empty string, the PHP mail() function will be used.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_report_message_template"></a><li><a name="5.2.20">report_message_template</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>'Hello {WATCHER},{BREAK}{BREAK}The log file {LOG} has the following new lines:{BREAK}{BREAK}{LINES}{BREAK}{SYSTEM}{BREAK}'</tt></p>
<h3>Purpose</h3>
<p>Template that defines how the new log lines report messages are formatted.</p>
<h3>Usage</h3>
<p>Change this variable only if it is necessary to change the default report message template.</p>
<p> The template is a string that has special marks that are replaced by specific values. These are the currently supported marks:</p>
<p> <tt>{BREAK}</tt> - message line break. Used this instead of hardcoded line breaks as the class will replace these marks by the appropriate line breaking character sequence according to the system sending the messages.</p>
<p> <tt>{LINES}</tt> - Text of the newly added lines.</p>
<p> <tt>{LOG}</tt> - Name of the log file as defined by the <tt><a href="#variable_log_file_name">log_file_name</a></tt> variable.</p>
<p> <tt>{SYSTEM}</tt> - Name of the system that is sending the report messages as defined by the <tt><a href="#variable_system_name">system_name</a></tt> variable.</p>
<p> <tt>{WATCHER}</tt> - Name of the person to send the report messages as defined by the <tt><a href="#variable_watcher_name">watcher_name</a></tt> variable.</p>
<p><a href="#variables">Variables</a></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="functions"></a><a name="6.1.1">Functions</a></li></h2>
<ul>
<li><tt><a href="#function_OpenLog">OpenLog</a></tt></li><br />
<li><tt><a href="#function_GetNewLogLine">GetNewLogLine</a></tt></li><br />
<li><tt><a href="#function_MailNews">MailNews</a></tt></li><br />
<li><tt><a href="#function_CloseLog">CloseLog</a></tt></li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
<h3><a name="function_OpenLog"></a><li><a name="7.2.5">OpenLog</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> OpenLog(</tt><tt>)</tt></p>
<h3>Purpose</h3>
<p>Open the log file and seek to the position of the line that was read for the last time, or to the end of the file if the log is being opened for the first time.</p>
<h3>Usage</h3>
<p>Call this function first to start processing the log file. Specify the name of the log file in the <tt><a href="#variable_log_file_name">log_file_name</a></tt> variable before calling this function.</p>
<h3>Return value</h3>
<p>Indicates whether the log file was successfully opened.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_GetNewLogLine"></a><li><a name="7.2.6">GetNewLogLine</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> GetNewLogLine(</tt><ul>
<tt>(output) <i>string &amp;</i> </tt><tt><a href="#argument_GetNewLogLine_line">line</a></tt><tt>,</tt><br />
<tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_GetNewLogLine_end_of_log">end_of_log</a></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Retrieve the next new line of the log if it was not yet reached the end of the file. This function is mostly meant to assist the function <tt><a href="#function_MailNews">MailNews</a></tt> or others that may be implemented in the future.</p>
<h3>Usage</h3>
<p>If you need to use this function, call it after successfully calling the <tt><a href="#function_OpenLog">OpenLog</a></tt> function. Check the value of the <tt><a href="#argument_GetNewLogLine_end_of_log">end_of_log</a></tt> argument after calling this function to determine if it was reached the end of the log file. If the end of the log file was not yet reached, the <tt><a href="#argument_GetNewLogLine_line">line</a></tt> argument will return the log line that was read, already without any end of line characters.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_GetNewLogLine_line">line</a></b></tt> - Return the next line that to be read from the log file.</p>
<p><tt><b><a name="argument_GetNewLogLine_end_of_log">end_of_log</a></b></tt> - Return a flag value that indicates if it was reached the end of the log file.</p>
</ul>
<h3>Return value</h3>
<p>Indicates whether the next log line was retrieved successfully or it was reached the end of the log file.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_MailNews"></a><li><a name="9.2.7">MailNews</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> MailNews(</tt><ul>
<tt><i>string</i> </tt><tt><a href="#argument_MailNews_subject">subject</a></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Read all the new lines of the log file and send them in a message to the address defined in the <tt><a href="#variable_watcher_email">watcher_email</a></tt> variable. If there are no new lines in the log file, nothing happens.</p>
<h3>Usage</h3>
<p>Call this function after successfully calling the <tt><a href="#function_OpenLog">OpenLog</a></tt> function.  Before calling this function, specify the addresses of the watcher person that will receive the report messages and the system that is sending them in the variables <tt><a href="#variable_watcher_email">watcher_email</a></tt> and <tt><a href="#variable_system_email">system_email</a></tt> respectively.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_MailNews_subject">subject</a></b></tt> - Subject of the message to be sent.</p>
</ul>
<h3>Return value</h3>
<p>Indicates whether the message was successfully sent or there were no new log files to notify.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_CloseLog"></a><li><a name="11.2.8">CloseLog</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> CloseLog(</tt><tt>)</tt></p>
<h3>Purpose</h3>
<p>Close a previously opened log file and stores the end of log file position in the log pointer file.</p>
<h3>Usage</h3>
<p>Call this function after calling the function <tt><a href="#function_MailNews">MailNews</a></tt> successfully.</p>
<h3>Return value</h3>
<p>Indicates whether the closing the log file and storing the log pointer position was done successfully.</p>
<p><a href="#functions">Functions</a></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>

<hr />
<address>Manuel Lemos (<a href="mailto:hide@address.com">hide@address.com</a>)</address>
</body>
</html>
Return current item: Log watcher