README

👁 Latest Stable Version
👁 Minimum PHP Version
👁 Build Status
👁 Coverage
👁 Quality Score
👁 Software License

Detect .htaccess capabilities through live tests.

There are cases where the only way to to learn if a given .htaccess capability is enabled / supported on a system is by examining it "from the outside" through a HTTP request. This library is build to handle such testing easily.

This is what happens behind the scenes:

1. Some test files for a given test are put on the server (at least an .htaccess file)
2. The test is triggered by doing a HTTP request
3. The response is interpreted

Usage

To use the library, you must provide a path to where the test files are going to be put and the corresponding URL that they can be reached. Besides that, you just need to pick one of the tests that you want to run.

require 'vendor/autoload.php';
use HtaccessCapabilityTester\HtaccessCapabilityTester;

$hct = new HtaccessCapabilityTester($baseDir, $baseUrl);

if ($hct->moduleLoaded('headers')) {
 // mod_headers is loaded (tested in a real .htaccess by using the "IfModule" directive)
}
if ($hct->rewriteWorks()) { 
 // rewriting works

}
if ($hct->htaccessEnabled() === false) {
 // Apache has been configured to ignore .htaccess files
}

// A bunch of other tests are available - see API

While having a reliable moduleLoaded() method is a great improvement over current state of affairs, beware that it is possible that the server has ie mod_rewrite enabled, but at the same time has disallowed using ie the "RewriteRule" directive in .htaccess files. This is why the library has the rewriteWorks() method and similar methods for testing various capabilites fully (check the API overview below). Providing tests for all kinds of functionality, would however be too much for any library. Instead this library makes it a breeze to define a custom test and run it through the customTest($def) method. To learn more, check out the Running your own custom tests document.

API overview

Test methods in HtaccessCapabilityTester

All the test methods returns a test result, which is true for success, false for failure or null for inconclusive.

The tests have the following in common:

• If the server has been set up to ignore .htaccess files entirely, the result will be failure.
• If the server has been set up to disallow the directive being tested (AllowOverride), the result is failure (both when configured to ignore and when configured to go fatal)
• A 403 Forbidden results in inconclusive. Why? Because it could be that the server has been set up to forbid access to files matching a pattern that our test file unluckily matches. In most cases, this is unlikely, as most tests requests files with harmless-looking file extensions (often a "request-me.txt"). A few of the tests however requests a "test.php", which is more likely to be denied.
• A 404 Not Found results in inconclusive
• If the request fails completely (ie timeout), the result is inconclusive

Most tests are implemented as a definition such as the one accepted in customTest(). This means that if you want one of the tests provided by this library to work slightly differently, you can easily grab the code in the corresponding class in the Testers directory, make your modification and call customTest().

Other methods in HtaccessCapabilityTester

Stable API?

The 0.9 release is just about right. I do not expect any changes in the part of the API that is mentioned above. So, if you stick to that, it should still work, when the 1.0 release comes.

Changes in the new 0.9 release:

• Request failures (such as timeout) results in inconclusive.
• If you have implemented your own HttpRequester rather than using the default, you need to update it. It must now return status code "0" if the request failed (ie timeout)

Expected changes in the 1.0 release:

• TestResult class might be disposed off so the "internal" Tester classes also returns bool|null.
• Throw custom exception when test file cannot be created

Platforms

Works on (at least):

• OS: Ubuntu (22.04, 20.04), Windows (2022, 2019), Mac OS (13, 12, 11, 10.15)
• PHP: 5.6 - 8.2

Each new release will be tested on all combinations of OSs and PHP versions that are supported by GitHub-hosted runners. Except that we do not below PHP 5.6.
Status: 👁 Giant test

Testing consists of running the unit tests. The code in this library has pretty good code coverage (~90% coverage).

We also test future versions of PHP monthly, in order to catch problems early.
Status: 👁 PHP 8.3
👁 PHP 8.4

Installation

Require the library with Composer, like this:

composer require rosell-dk/htaccess-capability-tester