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.
http://tweezy.net.au/filewatch.html
______________________________________________________
USAGE EXAMPLE
______________________________________________________
twzFileWatch is used by creating a simple PHP script which sets
the required options, then calls the checkFiles() class method.
<?php
require 'twzFileWatch.class.php';
$SiteName = 'SAMPLE';
$CheckFolder = './';
$DrillDown = 999;
$Email = 'yourself@example.com';
$fw = new twzFilewatch($SiteName, $CheckFolder, $DrillDown, $Email);
$fw->saveFile('../../temp/twzFW3.txt');
$fw->reportAlways(true);
$fw->checkFiles();
?>
For more information see twzFW-example.php, twzFW-example2.php and aaReadMe.txt
______________________________________________________
CONSTRUCTOR
______________________________________________________
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.
______________________________________________________
PUBLIC METHODS
______________________________________________________
->checkFiles()
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 http://php.net/manual/en/timezones.php
->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.
______________________________________________________
|
Download
