File Integrity Checks

The files check (installation integrity) class

Over the years we have noticed a signifficant number of clients reporting issues which were unlikely to happen. After careful investigation we were seeing that their problems were down to some component files not having been copied, not replaced during an update or having been removed, renamed or tampered with by overreaching "anti-malware" scripts installed by low quality hosts. Hosts scripts and user mistakes aside, the component files not being copied or replaced seem to be the consequence of an elusive Joomla! installer bug which dates as far back as Joomla! 1.5.5. I have personally seen this once on my dev server but I could not reproduce it to debug it. One of the most likely necessary –but not sufficient– conditions to trigger it seems to be a difference in top-level folder structure between the currently installed version and the update being installed. A second install of the latest version on top of the half-updated latest version seems to fix this issue. Your guess about it is as good as mine...

The missing/tampered files issue called for a way to detect it. If detected, the user can be given the simple instruction to install the extension again using the extension package (ZIP) file, without uninstalling it first. It's very simple and very effective. The detection was the difficult part. This is where the FOF30\Utils\FilesCheck class comes into play. It can perform a quick or thorough scan of a list of directories and files, making sure they are not missing or out of date / tampered with. The quick scan only checks that the directories exist and that the files exist and have the correct size. The thorough (a.k.a. "slow") scan also checks the SHA-1 or MD5 signatures of the files as well.

Before using it you need to create a file called fileslist.php in your component's back-end root directory, e.g. administrator/components/com_foobar/fileslist.php. The file needs to have the following contents:

<?php defined('_JEXEC') or die;

$phpFileChecker = array(
	'version' => '1.2.3',
	'date' => '2014-10-16',
	'directories' => array(
		'administrator/components/com_foobar',
		// ... add a list of directories here ...
	),
	'files' => array(
		// Format: file_name => array(file_size_in_bytes, md5, sha1)
		'administrator/components/com_foobar/access.xml' => array('705', '09aa0351a316bf011ecc8c1145134761', 'b95f00c7b49a07a60570dc674f2497c45c4e7152'),
		// ... add a list of files here ...
	)
);

The version and date are your component's version and release date, exactly as shown in the XML manifest file. They will be compared against the values cached in the #__extensions table. If there is a difference between the values in the file and those cached in the #__extensions table isWrongFilesVersion() will return true, telling you that the fileslist.php file itself is out of date, or there was a problem with the installation of the component (which is why the #__extensions record would have the wrong version / release date of the component cached).

The directory and file names are relative to the site's root. Please note that you cannot currently check files outside the site's root. The name of this file and the name and format of the PHP array containing this information is fixed.

You can create a files check object using the following syntax:

$checker = new FOF30\Utils\FilesCheck('com_foobar', '1.2.3', '2014-10-16');

All three parameters are mandatory. If you don't care to check the version and date you can pass empty strings. Be aware that in this case you will NOT know if a file is really missing / has been tampered with or the component's fileslist.php wasn't copied over.

You can get a quick integrity result by calling

$isInstallationCorrect = $checker->fastCheck();

If any of the directories is missing, or a file is missing / has the wrong file size this will return false.

A slow, more thorough check can also run by using

$result = $checker->slowCheck($index);

Please note that a slow check may take too long on a slow host. That's why it is designed to run in discrete steps. The $index parameter is the files array index from which to start scanning. If you are starting a new scan always set it to 0. The scan will take at most 3 seconds. The format of the result array is:

array(
	'done'	=> false,
	'files'	=> array(),
	'folders'	=> array(),
	'idx'	=> $idx
);

done will be false if there is a need for more scanning steps, true if the scanning has completed. If done is false the next scan should start from the index value returned in idx. If missing folders are found they are returned in the folders array. If missing or out-of-date / tampered files are found they are returned in the files array.