Daniele Alessandri
b1ebc8df2f
This commit is a complete rewrite of the classes previously contained
in the Predis\Option namespace aimed at lowering the initialization
overhead while bringing in more consistency. The overall idea is still
the same with a mini DI container, Predis\Configuration\Options, which
carries options with values that can be initialized lazily.
The first difference with our previous implementation is that now even
user-defined options can be initialized lazily, everything needed is
an object responding to the __invoke() magic method such as a closure.
Other kind of callable arguments (strings, arrays) will be treated as
plain values. The only drawback is that we cannot pass any instance of
classes implementing __invoke() as an option value, but considered the
limited scope of our use case we can say it's more of an acceptable
compromise. Callbacks used for lazy initialization will receive two
arguments upon invokation:
- The current instance of Predis\Configuration\Option ($options)
- A string containing the name of the option ($option)
This is an example in actual code:
$options = new Predis\Configuration\Options([
'exceptions' => true,
'profile' => '2.8',
'distributor' => function () {
return new Predis\Cluster\Distribution\KetamaPureRing();
},
'cluster' => function ($options) {
$distr = $options->distributor;
$strategy = new Predis\Cluster\PredisClusterHashStrategy($distr);
$cluster = new Predis\Connection\PredisCluster();
return $cluster;
},
'connections' => function ($options, $option) {
$factory = $options->getDefault($option);
$factory->define('tcp', 'Predis\Connection\PhpiredisConnection');
return $factory;
},
]);
As you can see there's very little difference compared to before in
the actual usage as most changes are under the hood. Some options such
as "exceptions" and "replication" can now correctly parse bool values
from strings (so the string "false" is not evaluated as boolean true).
While options were initially conceived to configure the client and its
behavior, the concept has matured and it's perfectly fine to consider
the use of Predis\Configuration\Options to propagate configurations to
inner parts of the library.
About testing Predis
ATTENTION: Do not ever run this test suite against instances of Redis running in production environments or containing data you are interested in! If you still want to test this software on a production server without hitting the database, please read ahead to undestand how to disable integration tests.
Predis ships with a comprehensive test suite that uses PHPUnit to cover every
aspect of the library. The suite is organized into several unit groups with the
PHPUnit @group annotation which makes it possible to run only selected groups
of tests. The main groups are:
- disconnected: generic tests that verify the correct behaviour of the library without requiring an active connection to Redis.
- connected: integration tests that require an active connection to Redis
- commands: tests for the implementation of Redis commands.
- slow: tests that might slow down the execution of the test suite, they can be either connected or disconnected.
A list of all the available groups in the suite can be obtained by running:
$ phpunit --list-groups
Groups of tests can be disabled or enabled via the XML configuration file or the
standard command-line test runner. Please note that due to a bug in PHPUnit,
older versions ignore the --group option when the group is excluded in the XML
configuration file. More details about this issue are available on PHPUnit's bug
tracker.
Certain groups of tests that require native extensions, such as ext-curl or
ext-phpiredis, are excluded by default in the XML configuration file. If you want
to test Predis using the phpiredis-based connection or against an instance of Webdis,
you should remove those groups of tests from the exclusion list in phpunit.xml.
Combining groups for inclusion or exclusion with the command-line runner
$ phpunit --group disconnected --exclude-group commands,slow
Integration tests
The suite performs integration tests against a running instance of Redis (>= 2.4.0 is required) to verify the correct behaviour of the implementation of each command and certain abstractions implemented in Predis depending on them. These tests are identified by the connected group.
Integration tests for commands that are not defined in the specified server profile
(see the value of the REDIS_SERVER_VERSION constant in phpunit.xml) are marked
as skipped automatically.
By default, the test suite is configured to execute integration tests using the
server profile for Redis v2.4 (which is the current stable version of Redis). You
can optionally run the suite against a Redis instance built from the unstable
branch with the development profile by changing the REDIS_SERVER_VERSION to dev
in the phpunit.xml file.
If you do not have a Redis instance up and running or available for testing, you can completely disable integration tests by excluding the connected group:
$ phpunit --exclude-group connected
Slow tests
Certain tests can slow down the execution of the test suite. These tests can be disabled by excluding the slow group:
$ phpunit --exclude-group slow
Testing Redis commands
We also provide an helper script in the bin directory that can be used to automatically
generate a file with the scheleton of a test case to test a Redis command by specifying
the name of the class in the Predis\Command namespace (only classes in this namespace
are considered valid). For example, to generate a test case for SET (represented by the
Predis\Command\StringSet class):
$ ./bin/generate-command-test.php --class=StringSet
Each command has its own realm (commands that operate on strings, lists, sets and such)
and this realm is automatically inferred from the name of the specified class. The realm
can be also specified manually using the --realm option.