adi_detritus – Sweep up the rubbish
After years of development, multiple enhancements, a succession of Textpattern upgrades, endless fiddling … website installations can get a bit untidy. This is where adi_detritus comes in. It’ll scour your website’s filesystem and plugins for items that are redundant, superfluous or even absent.
However, no changes are made. It’s up to the website administrator to decide what to do with the information presented.
After installing & activating the plugin you’ll see a new item under Admin.
The Detritus tab lists a number of warnings related to the website’s filesystem, plugins and preferences.
In some cases they may be significant, for example a missing .htaccess file.
In other cases, you may view them as inconsequential but untidy, e.g. an old README or licence file left behind from a previous TXP version.
You may even consider them irrelevant, e.g. an empty directory.
There will undoubtedly be some false positives, so be prepared to use a pinch of salt. You’re the boss!
Fine tune the results
You can educate adi_detritus by setting some preferences.
- Ignore non-linked files – the Files directory is often used for items other than those linked to the database, specify a list of files to ignore (default = *.sql *.sql.gz)
- Ignore non-linked images – your Images directory may contain images other than those linked to the database, specify a list of files to ignore (default = *.svg)
- Ignore filesystem items – list of specific directories or files to ignore (default = */.htaccess-dist)
- Style directories – list your style directories so that adi_detritus knows they should exist and can check them for anomalies (default = no style directories)
- Additional directories – list any other directories that are genuine and whose contents should be checked by the plugin (default = no additional directories)
- Non-linked file count threshold – specify what’s considered an “excessive number” of non-linked files (default = 5)
- File size threshold – define what you consider to be a large file – Files directory only, (default = 1MB)
- Image size threshold – define what you consider to be a large image – Images directory only, (default = 500KB)
- Ignore plugins – list plugins that may generate warnings but are actually genuine (default = pap_comconnect)
- List your files or directories on separate lines
- File sizes can be entered 1MB or 1048576
- Wildcards may be used
- All file/directories/wildcards specified in preferences are case sensitive
- Paths for “Ignore filesystem items”, “Style directories” and “Additional directories” are relative to website root
- Paths for unlinked files or images are relative to their respective directories
Where adi_detritus does its rummaging
- Website root directory
- Standard TXP directories: textpattern/, your files directory, your images directory, themes/
- Style directories specified in adi_detritus preferences
- Extra directories specified in adi_detritus preferences
- Installed and cached plugins, as well the plugins directory
Note that subdirectories are not traversed any deeper than the immediate level.
It’s good to moan
Examples of pedantry are:
- Empty directories or files.
- Hidden items that are not recognised.
- Hidden items that are recognised but are possibly questionable (e.g. .DS_Store, .svn).
- Missing items that probably should exist (e.g. .htaccess).
- Unrecognised HTML, JSON, PHP, Textile, text and log files (exceptions are standard files like index.php, README.txt etc).
- error_log – PHP server error logfile.
- rpc directory (if not required by your configuration).
- Old Textpattern licence files (e.g. LICENSE-BSD-3.txt).
- Old Textpattern js scripts directory & file.
- Large files – over the file size threshold specified in preferences.
- Large image files – over the image size threshold specified in preferences.
- Image thumbnail file permissions – lack of writablity can cause issues in TXP Image tab.
- Unreadable files or directories.
- Excessive numbers of files – over-threshold counts of non-linked files.
- Unusual file formats in your style directories.
- Flash files (*.swf)
- Some of the Diagnostics tab checks are duplicated as well – the writability of files/images/themes/plugins directories and the presence of the textpattern/setup folder.
- Plugins that have files in textpattern/plugins but are not installed in the database (TXP 4.8+ only).
- Public-side plugins that are not referenced in the database, have been modified, are inactive, or have unregistered tags.
- Preferences that are perceived to be redundant – perhaps left behind after a plugin has been deleted.
Is there anything that won’t be complained about?
- Standard files & directories in website root, e.g. index.php, css-php, textpattern/ etc.
- favicon.ico and all other image files in website root.
- robots.txt & cgi-bin/ in website root.
- browserconfig.xml, sitemap.xml & webmanifest files in website root (except they will still be validated for appropriate file type).
- Hidden files .htaccess, .htaccess-dist, .ftpquota, .well-known.
- Image files in your images directory that are linked to the database.
- Files in your files directory that are linked to the database.
- Active admin-side plugins – because, of course, they must be in use!
As of TXP 4.8, plugins are stored in the filesystem as well as the database. This means there is potential for mismatches. adi_detritus flags plugins:
- that have had their code modified (in the traditional sense)
- where the plugin code on file doesn’t match the database (this shouldn’t normally happen, unless perhaps there’s been an FTP hiccup)
- where the plugin’s type or load order is different from that specified during installation
- type and load order mismatch detection is dependent on the availablity of the plugin’s manifest.json file
- manifest.json may not always be present, for example, in websites that have been migrated from earlier releases
Missing manifest files will be listed. The lack of a manifest file is not an issue for plugin or website operation.
CSS – unusual or misunderstood?
PHP is not infallible when determining file types. From testing, CSS files can appear to be ‘text/plain’ (fair enough) or ‘text/x-asm’ (do what?). There is a ‘text/css’ type, but I haven’t seen one yet! However, anything else is deemed “unusual” – whether that’s a big deal anyway, I’m not sure.
Questioning the queries
- .DS_Store – OK in a local Mac development site, but no point having it in a live setup.
- .svn – still running Subversion? This subfolder can take up a lot of space.
- .git* – using Git? These can also take up a lot of space.
- Missing .htaccess – without them, third parties can do directory listings. textpattern/.htaccess is supplied by default, and other directories have serving suggestions (.htaccess-dist).
- js scripts directory – this has not been present in TXP distributions since 4.5. As long as you’re not using it you can bin it.
- jquery.js file – this has not been present in TXP distributions since 4.6. As long as you’re not using it you can bin it.
What’s your preference?
The plugin will look at preferences stored in the database and attempt to flag those which are possibly redundant – perhaps due to deleted plugins not tidying up after themselves.
This process relies on plugins storing their preferences associated with recognisable events. These events are taken from the callback list created by TXP Admin which is populated when plugin authors use
register_callback('plugin_function', 'plugin_event'). Some plugins, especially those without their own tabs, may be listed erroneously.
Note that preferences belonging to inactive plugins will also be flagged.
It should be fairly obvious which plugins relate to the redundant preferences listed. If you’re sure you want to delete preferences, then you’ll need to manipulate the database directly – using for example: smd_prefalizer, MySQL CLI, phpMyAdmin, or Sequel Pro.
- Multi-site TXP installations are whole new kettle of worms.
- Lower levels of subdirectories are not examined.
- Mac aliases are seen as text files.
- Generates false warnings for some public-side plugins (similar to pap_comconnect) – i.e. those without any tags. You can always add them to the “Ignore plugin” preference list.
- Not tested with multi-byte character filenames.
- Preferences belonging to inactive plugins will be flagged as “Possibly redundant”.
- Preferences that are genuinely redundant but are stored in the database with live events (e.g. “admin”) won’t be detected.
You can adjust who gets to use the plugin by setting the privileges in options. Default = Publisher only.
To install the Textpack, go to the plugin’s Options tab and click Install textpack. This will copy & install it from a remote server. The number of language strings installed for your language will be displayed.
If the Textpack installation fails (possibly due to an error accessing the remote site), the alternative is to click the Textpack also available online link. This will take you to a website where the Textpack can be manually copied & pasted into the TXP Admin – Language tab.
Additions and corrections to the Textpack are welcome – please use the Textpack feedback form.