Good To Know v2.0
, (*1)
Description
The original purpose of this project was to have an easy way of collecting
good-to-know facts for certain pages / features that need explanation., (*2)
To achieve that, the code was engineered in a very generic way:, (*3)
- Fetch all the data with a repository call,
- Apply transformations on the returned collection and/or it's elements via
Listeners.
Since the code uses listeners, it's very easy to add / remove functionality., (*4)
Built-in features
- Parameter injection
- Translation support
Integrations
A simple example
# good-to-know.yml
# When loaded and fetched by the `YamlFileRepository`, these will be converted
# into `Fact` objects.
- text: Something important.
groups: [feature1]
- text: Something important about feature2.
groups: [feature2]
- text: Something important about both features.
groups: [feature1, feature2]
use ZeeCoder\GoodToKnow\GoodToKnow;
use ZeeCoder\GoodToKnow\Repository\YamlFileRepository;
// The `GoodToKnow` object acts as a wrapper around the given repository.
// Every call made to this object is forwarded to the repository.
// The listeners are fired after getting the result collection from the
// repository.
$gtk = new GoodToKnow(
new YamlFileRepository(__DIR__ . '/good-to-know.yml')
// A dispatcher could be passed as the second argument.
// If no dispatcher is given, one gets created
);
// `findAllByGroups` is a method in the `YamlFileRepository` repository.
// It returns a collection of `ZeeCoder\GoodToKnow\Fact` objects.
// (In this case, an `\SplObjectStorage`.)
$collection = $gtk->findAllByGroups([
'feature1'
]);
// The collection would have the "Something important." and
// "Something important about both features." texts as Fact objects.
Listeners
Without listeners, the main GoodToKnow object doesn't do anything apart from
forwarding calls to the repository., (*5)
It gets interesting, when you throw some listeners into the mix., (*6)
The ParameterListener
This listener's job is to inject registered parameters into good-to-know
strings., (*7)
# good-to-know.yml
# When loaded and fetched by the `YamlFileRepository`, these will be converted
# into `Fact` objects.
- text: Something important. %lorem%!
groups: [feature1]
- text: Something important about feature2.
groups: [feature2]
- text: Something important about both features: The upload max filesize is: %upload_max_filesize%.
groups: [feature1, feature2]
// ...
// Assuming the example above
use ZeeCoder\GoodToKnow\ParameterInjector;
use ZeeCoder\GoodToKnow\Events;
use ZeeCoder\GoodToKnow\Listener\ParameterListener;
// Getting the dispatcher, since we didn't provide one explicitly.
$dispatcher = $gtk->getDispatcher();
// Creating the ParameterInjector
$parameterInjector = (new ParameterInjector())
// Registering parameters
->addParameter('%lorem%', 'ipsum')
->addParameter('%upload_max_filesize%', function() {
return ini_get('upload_max_filesize');
})
;
// Adding the listener.
// The TRANSFORM event is fired for every result returned by the repository.
$dispatcher->addListener(
Events::TRANSFORM,
new ParameterListener($parameterInjector)
);
$collection = $gtk->findAllByGroups([
'feature1'
]);
// Now the collection would have the "Something important. ipsum!" and
// "Something important about both features: The upload max filesize is: 2M."
// texts as Fact objects.
The TranslationListener
This listener assumes a translator implementing Symfony's TranslatorInterface., (*8)
use ZeeCoder\GoodToKnow\Events;
use ZeeCoder\GoodToKnow\Listener\TranslationListener;
// Getting the dispatcher, since we didn't provide one explicitly.
$dispatcher = $gtk->getDispatcher();
$dispatcher->addListener(
Events::TRANSFORM,
new TranslationListener(
// Assuming we have a Symfony `$translator` object.
$translator
// The second parameter, is the translation domain. Default: "good-to-know"
)
);
// Now all Fact texts will be translated.
Important, (*9)
The TranslationListener must be registered first, or with a higher priority
than the ParameterListener., (*10)
That way parameters can be injected after translations occured., (*11)
Source
Consider looking at the source files, in order to enhance / alter basic functionality., (*12)
(Creating a Database Repository for example.), (*13)
License
MIT, (*14)
Wallogit.com
