PHP Classes

File: aaReadMe.txt

Recommend this page to a friend!
  Classes of Tony  >  FileWatch  >  aaReadMe.txt  >  Download  
File: aaReadMe.txt
Role: Documentation
Content type: text/plain
Description: Overview
Class: FileWatch
Monitor changes in files of a directory
Author: By
Last change: Removed UTF-8 BOM character
Date: 5 years ago
Size: 6,535 bytes


Class file image Download
twzFileWatch :: ReadMe - OVERVIEW                              v3.1.2 2016-08-23


twzFileWatch notifies you when it detects any changes to your files.


aaReadMe.txt ................. overview (this file)
twzFileWatch-doc.txt ......... class reference; explains all the features
twzFileWatch.class.php ....... the twzFileWatch class .. a minified version of twzFileWatch.class.php
twzFW-example.php ............ sample calling script
GPL.txt ...................... software licence
FolderPerms.php .............. companion script; shows directory permissions
twzFileWatchMGA.class.php .... example of changing the email send method


To use twzFileWatch, the only files you need on your server are:
    (1) twzFileWatch.class.php
    (2) your own calling script, based on twzFW-example.php

All the other files in this package are documentation and examples to help you 
make the most of twzFileWatch.

If you are upgrading from an earlier version of twzFileWatch, please read the 
UPGRADING section at the bottom of this file.


The calling script (eg twzFW-example.php) sets up your required options, and 
creates an instance of the twzFileWatch class. Your calling script can be run in 
various ways - your choice. For example:

1. Run as a cron job. The script will run automatically at the times specified 
by you, regardless of any other activity on your site.
2. Called manually/bookmark via HTTP. You can open the script in your browser 
whenever you want to check for changes.
3. Called by another script using HTTP; the other script could be initiated manually, 
or could be running as a cron job. See also: 'MULTIPLE SITES' section below.
4. @INCLUDEd in specific pages, or all pages on a site. The script will only check 
for changes when someone visits the page where the script is included. You can set 
minInterval to avoid excess server load on busy sites. This option is not recommended 
for checking more than a few hundred files, as it could cause a noticable delay 
in page loading times. Also be aware that the minInterval check may cause the script 
to die() - so make sure it's the last thing on the page, preferably after the 
closing </html> tag!


twzFileWatch uses PHP's mail() function to send email.

Some web hosts (particularly shared hosting) have restrictions on allowing emails 
being sent from the hosting server. If this is a problem for you, you can extend 
the twzFileWatch class to replace its _emailSend() method, and send email by some 
custom or 3rd party method. For an example of this (using the Mailgun API), see 


In some cases FileWatch may exceed its permitted execution time, particularly 
if it's checking many thousands of files, or you have called useChecksums() 
with many files.

There are several possible soutions to this; for example:

You might use multiple calling scripts, each one checking a subset of the files. 
Each calling script would have its own CheckFolder, SaveFile and other settings.

To avoid having to add a new cron job for each calling script, a better solution 
might be to write a single calling script that runs FileWatch with different 
settings depending on the time of day. A single cron job could be set up to run 
at say 2am, 3am and 4am. Your calling script could then decide which 'fileset' 
to check each run. Because each 'fileset' must use a different SaveFile, your 
script could also decide which set to run based on the oldest SaveFile.


If you manage several web sites and want them all checked by twzFileWatch, you 
will need to upload the twzFileWatch class and a calling script to each site.
However you can avoid having to create a cron job for each site by making a script 
that polls the calling script on each site in turn. That way, you only need to 
create one cron job for this 'master' script, and when run it will call twzFileWatch 
on all of your sites.

To do this, the calling script on each site needs to be web-accessible (ie located 
somewhere under public_html), and must send the results via email (ie not echoed 
to the screen).

The sample master script below shows how you could implement this. You just need 
to put the URL of all your calling scripts into the $FWscript array.

The sample script calls each URL, then immediately closes the connection so it 
doesn't have to wait for the result. It also sends a close=yes parameter to 
twzFileWatch, which will detect this and disconnect itself from the master script, 
but continue running.

//------------------------------------------------ sample script ----
// Poll filewatch on multiple sites


foreach($FWscript as $ThisScript)
    $fp = fsockopen($parts['host'],
        isset($parts['port']) ? $parts['port'] : 80,
        $errno, $errstr, 30);

    $out = "GET ".$parts['path']."?close=yes HTTP/1.1\r\n"
        ."Host: ".$parts['host']."\r\n"."Connection: Close\r\n\r\n";
    fwrite($fp, $out);
    echo 'Called '.$ThisScript."<br />\r\n";


If you're upgrading from twzFileWatch v3.0 or earlier and you were using 
twzFileWatch logging, you should be aware of some changes that may affect your 
current calling script. 

Previously, the full result was being written to the log file. Now the default 
is a single line summary per run; if you still want the full result logged, you 
should call the logFile() method with 'full' LogStyle.

The new logFile() method replaces these old methods, which are no longer available: 
logFileBase(), logName() and logDate().

For further information, see twzFileWatch-doc.txt

For more information send a message to info at phpclasses dot org.