File Alteration Monitor Functions

Introduction

FAM monitors files and directories, notifying interested applications of changes. More information about FAM is available at » http://oss.sgi.com/projects/fam/.

A PHP script may specify a list of files for FAM to monitor using the functions provided by this extension.

The FAM process is started when the first connection from any application to it is opened. It exits after all connections to it have been closed.

Note:

This extension has been moved to the » PECL repository and is no longer bundled with PHP as of PHP 5.1.0.

Note:

This extension is not available on Windows platforms.

Requirements

This extension uses the functions of the » FAM library, developed by SGI. Therefore you have to download and install the FAM library.

Installation

To use PHP's FAM support you must compile PHP --with-fam[=DIR] where DIR is the location of the directory containing the lib and include directories.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

There are two resource types used in the FAM module. The first one is the connection to the FAM service returned by fam_open(), the second a monitoring resource returned by the fam_monitor_XXX functions.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

Table 89. FAM event constants

Constant	Description
`FAMChanged` (integer)	Some value which can be obtained with fstat(1) changed for a file or directory.
`FAMDeleted` (integer)	A file or directory was deleted or renamed.
`FAMStartExecuting` (integer)	An executable file started executing.
`FAMStopExecuting` (integer)	An executable file that was running finished.
`FAMCreated` (integer)	A file was created in a directory.
`FAMMoved` (integer)	This event never occurs.
`FAMAcknowledge` (integer)	An event in response to fam_cancel_monitor().
`FAMExists` (integer)	An event upon request to monitor a file or directory. When a directory is monitored, an event for that directory and every file contained in that directory is issued.
`FAMEndExist` (integer)	Event after the last FAMEExists event.

Table of Contents

fam_cancel_monitor — Terminate monitoring
fam_close — Close FAM connection
fam_monitor_collection — Monitor a collection of files in a directory for changes
fam_monitor_directory — Monitor a directory for changes
fam_monitor_file — Monitor a regular file for changes
fam_next_event — Get next pending FAM event
fam_open — Open connection to FAM daemon
fam_pending — Check for pending FAM events
fam_resume_monitor — Resume suspended monitoring
fam_suspend_monitor — Temporarily suspend monitoring

Code Examples / Notes » ref.fam

in the example above, I would not use the while(1) and sleep() functions, since then you're back at waiting and polling for file changes, which you were trying to avoid using fam. Instead, you can use while(fam_next_event($resource)), which blocks until there is an event. No polling, no useless wasting of cpu cycles. Anyway, I have some problems with fam: It is very limited and almost useless. - You cannot monitor a directory tree easily, since fam_monitor_directory() is non-recursive. Its an ugly hack, but you can go through each subdir and also monitor it with fam_monitor_directory(). - When you do that, you will have another problem: The events you get contain the code and the filename, but not the pathname of the file that caused the event. Thus, if you monitor two or more directories, and they possibly contain files with the same basename, you cannot find out what file has changed. One ugly solution might be to create a new fam_resource for each directory you want to monitor, but then you cannot use fam_next_event() in your while loop anymore. - When a big file is saved (i.e. with photoshop via samba), you get file_changed events pretty much every second the file is being written to. It is not possible to receive ONE event AFTER the file operation is done. I'm not sure, but I think most of this is not PHPs fault. Its just that fam (or dnotify, which fam uses on linux) sucks very badly. If you search on google, it seems everyone hates fam/dnotify (even linus), but noone has done anything about it yet. If you find out how to work around thing, or if I'm completely wrong about all of this, please post here! Thanks!

yassin ezbakhe

I make a VERY simple class that monitors a folder (and its subfolders) for new or removed files. I use it in order to auto index a folder where I have all my eBooks into a MySQL database. CLASS FILE: <?php class FileAlterationMonitor { private $scanFolder, $initialFoundFiles; public function __construct($scanFolder) { $this->scanFolder = $scanFolder; $this->updateMonitor(); } private function _arrayValuesRecursive($array) { $arrayValues = array(); foreach ($array as $value) { if (is_scalar($value) OR is_resource($value)) { $arrayValues[] = $value; } elseif (is_array($value)) { $arrayValues = array_merge( $arrayValues, $this->_arrayValuesRecursive($value)); } } return $arrayValues; } private function _scanDirRecursive($directory) { $folderContents = array(); $directory = realpath($directory).DIRECTORY_SEPARATOR; foreach (scandir($directory) as $folderItem) { if ($folderItem != "." AND $folderItem != "..") { if (is_dir($directory.$folderItem.DIRECTORY_SEPARATOR)) { $folderContents[$folderItem] = $this->_scanDirRecursive( $directory.$folderItem."\\"); } else { $folderContents[] = $folderItem; } } } return $folderContents; } public function getNewFiles() { $finalFoundFiles = $this->_arrayValuesRecursive( $this->_scanDirRecursive($this->scanFolder)); if ($this->initialFoundFiles != $finalFoundFiles) { $newFiles = array_diff($finalFoundFiles, $this->initialFoundFiles); return empty($newFiles) ? FALSE : $newFiles; } } public function getRemovedFiles() { $finalFoundFiles = $this->_arrayValuesRecursive( $this->_scanDirRecursive($this->scanFolder)); if ($this->initialFoundFiles != $finalFoundFiles) { $removedFiles = array_diff( $this->initialFoundFiles, $finalFoundFiles); return empty($removedFiles) ? FALSE : $removedFiles; } } public function updateMonitor() { $this->initialFoundFiles = $this->_arrayValuesRecursive($this->_scanDirRecursive( $this->scanFolder)); } } ?> A simple script that uses this class could be like this one (use it with PHP CLI): <?php $f = new FileAlterationMonitor($MY_FOLDER_TO_MONITOR) while (TRUE) { sleep(1); if ($newFiles = $f->getNewFiles()) { // Code to handle new files // $newFiles is an array that contains added files } if ($removedFiles = $f->getRemovedFiles()) { // Code to handle removed files // $newFiles is an array that contains removed files } $f->updateMonitor(); }

sergiopaternoster

Here is a simple script to check changes etc. to a file. <?php /* opens a connection to the FAM service daemon */ $fam_res = fam_open (); /* * The second argument is the full pathname * of the file to monitor. * Note that you can't use relative pathnames. */ $nres = fam_monitor_file ( $fam_res, '/home/sergio/test/fam/file_to_monitor.log'); while(1){ if( fam_pending ( $fam_res ) ) $arr = (fam_next_event($fam_res)) ; switch ($arr['code']){ case 1: echo "FAMChanged\n"; break; case 2: echo "FAMDeleted\n"; break; case 3: echo "FAMStartExecuting\n"; break; case 4: echo "FAMStopExecuting\n"; break; case 5: echo "FAMCreated\n"; break; case 6: echo "FAMMoved\n"; break; case 7: echo "FAMAcknowledge\n"; break; case 8: echo "FAMExists\n"; break; case 9: echo "FAMEndExist\n"; break; default: break; } if(isset($arr)) unset($arr); /* In order to avoid too much CPU load */ usleep(5000); } /* Close FAM connection */ fam_close($fam_res); ?> Hope this could help. God Belss PHP! regards Sergio Paternoster