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: 6 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. ______________________________________________________ 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 = ''; $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 ->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. ______________________________________________________