Kappa\PlaceholderProcessor 
Easy system for working with placeholders in texts, (*1)
Content
Requirements
Full list of dependencies you can get from Composer config file, (*2)
Installation
The best way to install Kappa\PlaceholderProcessor is using Composer, (*3)
$ composer require kappa/placeholderprocessor
Usages
1. step - Prepare custom placeholder processors
There is a few rules how to create a custom placeholder processors. Each you placeholder
processor must implements \Kappa\PlaceholderProcessor\IPlaceholderProcessor interface or
and it is recommended you can extend your class from
\Kappa\PlaceholderProcessor\PlaceholderProcessor class which implements this interface and
prepares logic for easy and quick usage., (*4)
For example:, (*5)
<?php
use Kappa\PlaceholderProcessor\PlaceholderProcessor;
class MySuperPlaceholderProcessor extends PlaceholderProcessor
{
private $db;
public function __construct(Database $db)
{
$this->db = $db;
}
public function configure()
{
$this->setName("mySuperPlaceholderProcessor");
$this->setExternalSources(['user_id']);
}
public function run(array $sources = [])
{
return $this->db->find('users', $sources['user_id'])->getName();
}
}
This placeholder will replace %mySuperPlaceholderProcessor% placeholder by user name by id
which is set as external source., (*6)
You must configure your processor in configure method. In this method you must set name
of placeholder if format %<name>%. In this case this placeholder will be works with
%mySuperPlaceholderProcessor% placeholder., (*7)
The second important settings is list of external sources. This list will be used for automatic
compare with $source in run method. You can be sure that each of item from external source
will be in $source in run method. This sources will be given from
TextFormatter::format($text, $sources)., (*8)
Returns from run method will be used for replacing placeholder., (*9)
2. step - Create a new instance
For translate placeholders you need instance of Kappa\PlaceholderProcessor\TextFormatter, (*10)
You can create this instance manually, (*11)
$textFormatter = new TextFormatter([
new MySuperPlaceholderProcessor()
]);
or you can use setPlaceholders(array) method, (*12)
$textFormatter = new TextFormatter();
$textFormatter->setProcessors([
new MySuperPlaceholderProcessor()
]);
or when you use Nette Framework you can
register this package as extension, (*13)
services:
mySuperProcessor:
class: MySuperPlaceholderProcessor
tags: [kappa.placeholder_processor]
extensions:
placeholderProcessor: Kappa\PlaceholderProcessor\DI\PlaceholderProcessorExtension
placeholderProcessor:
strict: true
```php
public function __construct(TextFormatter $textFormatter) {
}
of course you can add single processor $textFormatter->addProcessor(new MySuperPlaceholderProcessor());., (*14)
3. step - Usage
Now we have custom placeholder and instance of formatter and you can try translate this text
Hello %mySuperPlaceholderProcessor%, %foo%, (*15)
$textFormatter = new TextFormatter([
new mySuperPlaceholderProcessor($db)
]);
$output = $textFormatter->format('Hello %mySuperPlaceholderProcessor%, %foo%', ['user_id' => 1]);
Formatter replace %mySuperPlaceholderProcessor% by logic in MySuperPlaceholderProcessor class.
This processor gets user_id from external source (second argument in format method), find
user in database and returns his name which can be used for replacing original placeholder.
Placeholder %foo% will be ignored because there isn't any processor with this name., (*16)
Output: Hello Joe, %foo%., (*17)
Strict mode
Strict mode is turn off by default., (*18)
When you need strict mode which throws exception when in text is placeholder which hasn't any
processor (as %foo% in previous example). You can turn on (or off) by setStrictMode(true)
method or when you use Nette Framework in config file by strict: true, (*19)
Wallogit.com
