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.
Because Scrapbook supports a wide range of PHP versions and has adapters for a good amount of services, testing could be laborious.
Docker images has been created to set up the entire environment, or just a specific combination of PHP version + adapters. These can be launched from the command line, as configured in the makefile. Just make sure you have installed Docker & Docker-compose.
To run the complete test suite, for all adapters, on the latest PHP release:
Or a specific adapter (in this case Memcached):
make test ADAPTER=Memcached
Or a couple of adapters (in this case the SQL group):
make test ADAPTER=MySQL,PostgreSQL,SQLite
Or with a specific PHP version:
make test PHP=7.0 ADAPTER=MySQL,PostgreSQL,SQLite
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.