When filing bugs, try to be as thorough as possible:
Bug fixes and general improvements to the existing codebase are always welcome. New features are also welcome, but will be judged on an individual basis. If you'd rather not risk wasting your time implementing a new feature only to see it turned down, please start the discussion by opening an issue.
Where applicable, new features should follow the existing model of wrapping them around a KeyValueStore object, which is in turn also a KeyValueStore. Like how an adapter can be wrapped inside a StampedeProtected, which can in turn be wrapped inside a TransactionalStore. This keeps functionality nicely isolated (single responsibility) while still offering a consistent API.
Don't forget to add your changes to the changelog.
To run the complete test suite, for all adapters:
Or a specific adapter (in this case Memcached):
vendor/bin/phpunit --group "Memcached"
Or a couple of adapters (in this case the SQL group):
vendor/bin/phpunit --group "MySQL,PostgreSQL,SQLite"
Some adapter rely on external services (cache server) & libraries (client-side APIs). If you need help to install these, take a look inside the tests/.travis directory, where the installation scripts for Travis CI are located.
A lot of them use Docker to launch the cache servers but you can always install
the servers natively, in which case you may need to alter the adapters
configuration (e.g. because you're running the server on a different port). This
configuration is located in tests/Adapters, in the
method of every adapter. If you do need to alter these in order to run the tests
on your machine, make sure not to commit those changes!
Travis CI has been configured to run a matrix of all supported PHP versions & adapters individually. Upon submitting a new pull request, that test suite will be run & report back on your pull request. Please make sure the test suite passes.
Please include tests for every change or addition to the code.
To add a new adapter, just add a new AdapterNameTest.php file in the
tests/Adapters directory, similar to the existing adapters.
That file should implement AdapterInterface &
::get should return that
adapter's KeyValueStore implementation & throw a
MatthiasMullie\Scrapbook\Exception\Exception in case it fails to initialize.
These adapter tests can also include adapter-specific tests. Just look at MemoryStoreTest.php, for example.
To create a new test that can be run for all adapters, make sure it extends from
AdapterProviderTestInterface and has a
::suite that calls
AdapterProvider. Or just extend
AdapterTestCase directly, which has that already
All code must follow PSR-2. Just make sure to run php-cs-fixer before submitting the code, it'll take care of the formatting for you:
vendor/bin/php-cs-fixer fix src vendor/bin/php-cs-fixer fix tests
Document the code thoroughly!
Note that Scrapbook is MIT-licensed, which basically allows anyone to do anything they like with it, without restriction.