================================================================================
twzFileWatch :: ReadMe - OVERVIEW v3.1.2 2016-08-23
================================================================================
WHAT'S IT FOR?
_________________________
twzFileWatch notifies you when it detects any changes to your files.
PACKAGE CONTENTS
_________________________
aaReadMe.txt ................. overview (this file)
twzFileWatch-doc.txt ......... class reference; explains all the features
twzFileWatch.class.php ....... the twzFileWatch class
twzFileWatch.class.mini.php .. 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
QUICK START
_________________________
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.
IMPLEMENTATION OPTIONS
_________________________
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!
SENDING EMAILS
_________________________
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
twzFileWatchMGA.class.php
TOO MANY FILES?
_________________________
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.
MULTIPLE SITES
_________________________
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.
<?php
//------------------------------------------------ sample script ----
// Poll filewatch on multiple sites
$FWscript=array(
'http://example.com/twzFW-example.php',
'http://www.example.net/twzFW-newsite.php',
'http://www.example.org/twzFW.php',
);
foreach($FWscript as $ThisScript)
{
$parts=parse_url($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);
fclose($fp);
echo 'Called '.$ThisScript."<br />\r\n";
}
//-------------------------------------------------------------------
?>
UPGRADING
_________________________
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
|
Download
