PHP Classes

File: twzFileWatch-doc.txt

Recommend this page to a friend!
  Classes of Tony  >  FileWatch  >  twzFileWatch-doc.txt  >  Download  
File: twzFileWatch-doc.txt
Role: Documentation
Content type: text/plain
Description: Documentation
Class: FileWatch
Monitor changes in files of a directory
Author: By
Last change: updated for new version
Date: 5 years ago
Size: 14,188 bytes


Class file image Download
twzFileWatch :: class reference                                v3.1.2 2016-08-23

twzFileWatch is a PHP class which can send you an email when it 
detects any changes to file names, dates or sizes in specific folders.

This document explains methods and parameters used by twzFileWatch.



twzFileWatch is used by creating a simple PHP script which sets
the required options, then calls the checkFiles() class method.

    require 'twzFileWatch.class.php';

    $SiteName    = 'SAMPLE';
    $CheckFolder = './';
    $DrillDown   = 999;
    $Email       = '';

    $fw = new twzFilewatch($SiteName, $CheckFolder, $DrillDown, $Email);

For more information see twzFW-example.php, twzFW-example2.php and aaReadMe.txt



When creating an instance of the twzFileWatch class, you need to 
specify four parameters, as below:

    $fw = new twzFilewatch(SiteName, CheckFolder, RecurseLevel, EmailTo);

SiteName .......... string (mandatory)
                    This is used in the email subject, and is particularly useful
                    if you're using FileWatch to monitor multiple sites.

CheckFolder ....... string|array (mandatory)
                    Directory or directories to check for changes. If you only want 
                    to check one directory (and perhaps its sub-directories), 
                    CheckFolder can be a string (eg './' for the current directory, 
                    or '../' for the parent directory). To check multiple specific 
                    directories, CheckFolder can be an array of strings.

RecurseLevel ...... integer (mandatory)
                    This determines whether sub-folders are checked, and if so 
                    how deep. If RecurseLevel is zero no sub-folders will be 
                    checked, only the folder(s) named in CheckFolder. Use 1 to 
                    check sub-folders, 2 to check sub-sub-folders, etc. 
                    For "infinite" recursion just use a big number, eg 999. 
                    If the CheckFolder parameter is an array, the same RecurseLevel 
                    applies to all folders.

EmailTo ........... string (mandatory)
                    This is the email address where notification of changes is sent,
                    or up to 3 email addresses separated by commas.
                    See also: emailBcc() method

FollowSymlinks .... boolean (optional, defaults to false)
                    On a unix-based web server there is often a symbolic link 
                    called www pointing to public_html. You don't want to check 
                    both www and public_html because they are actually the same 
                    location. If for any reason you DO want to follow symbolic 
                    links, you can set this parameter to true.



                    This is the method called to actually do all the work. 
                    You should always call this method, as the last step.

->saveFile( string pathname )
                    This method sets the location and name of the save-file.
                    FileWatch works by creating a list of files and storing the 
                    list in a text file (the save-file). Next time it is run, 
                    FileWatch compares this list with the current files and 
                    reports the differences. The save-file must be writable by 
                    your PHP script.

->doSendEmail( boolean send=true )
                    The main purpose of FileWatch is to send an email to you.
                    However for testing purposes you can turn off the email and
                    echo the results instead, by calling doSendEmail(false).

->reportAlways( boolean always=true )
                    Normally FileWatch only sends an email when it detects a change
                    to the files it's watching. By calling reportAlways(true),
                    you can receive an email even if no changes were detected.

->reportBase( bool|string show=true )
                    If any of the directories in CheckFolder are relative paths, 
                    they will be relative to the directory where your PHP script 
                    resides. In this case, the reportBase() method determines  
                    whether the base folder path is included in the email result.
                    The value of the 'show' parameter can be false to exclude this 
                    information, true to show it with the default 'Base directory is..' 
                    text, or another string to replace this default. If you don't 
                    call this method, the base folder will be included with the 
                    default text.

->reportDuration( bool|string show=true )
                    This method determines whether the processing time is shown in 
                    the email result. The value of the 'show' parameter can be false 
                    to exclude this information, true to show it with the default 
                    'Processing time' text, or another string to replace this 
                    default. If you don't call this method, the processing time 
                    will NOT be included.
                    NOTE: The time reported is actually elapsed time, not CPU time; 
                    it will vary depending on how busy the server is with other things.

->reportTime( bool|string show=true )
                    This method determines whether the current server time is shown 
                    in the email result. The value of the 'show' parameter can be 
                    false to exclude this information, true to show it with the 
                    default 'Current server time' text, or another string to replace 
                    this default. If you don't call this method, the server time 
                    will NOT be included.
                    TIP: If the current time seems wrong, consider setting the 
                    desired timezone by adding date_default_timezone_set() to your 
                    calling script.
                        eg date_default_timezone_set('Australia/Hobart');
                    For supported timezones see

->emailSubject( string subj1 [, string subj2 ] )
                    This method lets you change the default subject of emails sent 
                    by FileWatch. subj1 is for the usual email sent when changes 
                    are detected. subj2 is for the email sent when NO changes 
                    were detected, which applies only with reportAlways(true).
                    If either or both are empty, defaults will be used. Either can
                    optionally contain a placeholder "[SiteName]", which will be
                    replaced by the SiteName string.

->emailBcc( string email )
                    Use this method if you want the notification email bcc'd to 
                    another address in addition to the EmailTo option. This can
                    be a single address, or up to 3 comma-separated addresses.

->minInterval( string interval )
                    FileWatch has a safety valve to stop it from being run too 
                    often, especially if it has been INCLUDEd in a normal web page.
                    FileWatch will only check files for changes if the previous 
                    check was more than 'interval' ago. 'interval' is an English
                    expression such as '5 minutes' or '24 hours'; the default
                    is '1 hour'. If you are testing FileWatch by running it in a 
                    browser, you might want to set this to something smaller, eg
                    minInterval('5 seconds').

->excludeFolders( array folders )
                    This method can be used to exclude specific folders from being
                    checked. Each folder name must start with an existing entry in
                    CheckFolder. For example if CheckFolder is './public_html' then 
                    to exclude the images folder you would specify 
                    excludeFolders( array('./public_html/images') )

->excludeFiles( array files )
                    This method can be used to exclude specific files from being 
                    checked. For example if you have log files you know will change 
                    but you don't want to be notified about them, you can set 
                    excludeFiles( array('main.log', 'other.log') )
                    Entries in this array can be just filenames or (relative) 
                    pathnames. For example, you can exclude ./admin/index.php but 
                    not every index.php file, provided that './admin/' is one of 
                    the folders in CheckFolder.

->serverDomain( string domain )
                    If present, domain will be used to build the email FROM address. 
                    If you don't call this method, or you pass it an empty string, 
                    FileWatch will use the hostname of the server it's running on.

->suppressNewList( bool suppress=true )
                    The first time FileWatch is run, every file will be "new". 
                    You can call SuppressNewList(true) to avoid listing every file 
                    in this case. If you don't call this method, the full list 
                    is shown.

->logFile( string basename [, string appendspec [, string logstyle ] ] )
                    FileWatch can optionally record each run in a log file.
                    The location and name of the log file will be built from the 
                    basename and appendspec, the latter being fed through the PHP 
                    date() function. The file extension is always '.log'.
                    The default appendspec '_Y-m' converts to the current year and 
                    month. For example, if you call logFile('../temp/Filewatch') 
                    then the log file will be ../temp/Filewatch_2016-09.log (for 
                    September 2016). This naming scheme means that a new log file 
                    will be created every month.
                    The logstyle parameter can be either 'line' (the default), which 
                    writes a single summary line each run, or 'full' which writes the 
                    entire result - the same as is included in the email sent to you.
                    If you don't call this method or you give it an empty string 
                    for basename, no log file will be created.
                    TIP: if logstyle is 'full' and appendspec includes the full date 
                    and time (eg '_Y-m-d-His') then all details for each run will be 
                    saved in a separate file.

->useChecksums( bool use [, int level [, bool onDate ] ] )
                    In most cases, FileWatch just keeps an eye on file sizes and 
                    last-modified dates. Some recent exploits have tried to avoid 
                    detection by updating the last-modified date after it changes 
                    a file. This is not a huge problem, because FileWatch will 
                    still identify a change to the file size, and new files will 
                    also be reported even if their last-modified date is an old one. 
                    However we expect that eventually exploits will become more 
                    sophisticated by removing some white space from their target file 
                    (the same number of bytes that are added by the exploit), and 
                    setting its last-modified date back to what it was previously. 
                    If this happens, FileWatch would not identify the file as changed 
                    (although it will still report new files). To remedy this 
                    situation, FileWatch offers another layer of detection by 
                    keeping a checksum hash for files, which can identify even a 
                    tiny change in a file's contents. To use checksums, simply call 
                    useChecksums(true). WARNING: calculating a checksum for every 
                    file will obviously take longer, so be careful if checking a lot 
                    of files. You might consider reducing the number of files to 
                    check if you're using checksums. The useChecksums method has two 
                    optional parameters, 'level' and 'onDate'. 'level' specifies how 
                    far down the directory tree you want to keep checksums for files. 
                    (This is similar to RecurseLevel, except it only applies to 
                    checksums. 'level' can never be more than RecurseLevel). 
                    By default 'level' is set to 1 to reduce the server load on 
                    large sites. Usually checksum changes are only reported if the 
                    filesize and filedate have not changed (if these ARE changed 
                    the file will be reported as changed anyway, and if size has 
                    changed the checksum would definitely be different). If the 
                    third parameter 'onDate' is true, the checksum will also be 
                    checked if the file size is unchanged but the date HAS changed.
For more information send a message to info at phpclasses dot org.