Integrating into your app
We recommend you read the best practices for advice on how to best prepare your applications. We strongly encourage you to do so.
π¦ Installing
$ composer require richarddobron/fbt
Add this lines to your code:
- We recommend setting the author, project and path options.
<?php
// require ("vendor/autoload.php");
\fbt\FbtConfig::set('author', 'your name');
\fbt\FbtConfig::set('project', 'project');
\fbt\FbtConfig::set('path', '/path/to/storage');
π§ Configuration
Options
The following options can be defined:
- project
string: (Default:website app) Project to which the text belongs - author
string: Text author - preserveWhitespace
bool: (Default:false)- FBT normally consolidates whitespace down to one space (
' '). - Turn this off by setting this to
true
- FBT normally consolidates whitespace down to one space (
- viewerContext
string: (Default:\fbt\Runtime\Shared\IntlViewerContext::class) - locale
string: (Default:en_US) User locale. - fbtCommon
string: (Default:[]) common string's, e.g.[['text' => 'desc'], ...] - fbtCommonPath
string: (Default:null) Path to the common string's module. - path
string: Cache storage path for generated translations & source strings.
Below are the less important parameters.
- collectFbt
bool: (Default:true) Collect fbt instances from the source and store them to a JSON file. - prettyPrint
bool: (Default:true) Pretty print source strings in a JSON file. - hash_module
string: (Default:md5) Hash module. You can choosemd5ortigerhash module. - md5_digest
string: (Default:hex) MD5 digest. - driver
string: (Default:json) Currently, only JSON storage is supported.
π IntlInterface
Optional implementation of IntlInterface on UserDTO.
Example code:
<?php
namespace App;
use fbt\Transform\FbtTransform\Translate\IntlVariations;
use fbt\Lib\IntlViewerContextInterface;
use fbt\Runtime\Gender;
class UserDTO implements IntlViewerContextInterface
{
public function getLocale(): string
{
return $this->locale;
}
public static function getGender(): int
{
if ($this->gender === 'male') {
return IntlVariations::GENDER_MALE;
}
if ($this->gender === 'female') {
return IntlVariations::GENDER_FEMALE;
}
return IntlVariations::GENDER_UNKNOWN;
}
}
After implementation, set viewerContext:
$loggedUserDto = ...;
\fbt\FbtConfig::set('viewerContext', $loggedUserDto)
π Commands
- This command collects FBT strings across whole application in PHP files.
php ./vendor/bin/fbt collect-fbts --path=./path/to/fbt/ --src=./path/to/project/
Read more about FBTs extracting.
- This command generates the missing translation hashes from collected source strings.
php ./vendor/bin/fbt generate-translations --source=./path/to/fbt/.source_strings.json --translations=./path/to/fbt/*.json
- This command creates translation payloads stored in JSON file.
php ./vendor/bin/fbt translate --path=./path/to/fbt/ --translations=./path/to/fbt/*.json
Read more about translating.
π API
- fbt(...);
- fbt::param(...);
- fbt::enum(...);
- fbt::name(...);
- fbt::plural(...);
- fbt::pronoun(...);
- fbt::sameParam(...);
- fbt::c(...);
echo fbt('You just friended ' . \fbt\fbt::name('name', 'Sarah', 2 /* gender */), 'names');
π¨ Example Usage
fbtTransform() & endFbtTransform()
fbtTransform(): This function will turn output buffering on. While output buffering is active no output is sent from the script (other than headers), instead the output is stored in an internal buffer.
endFbtTransform(): This function will send the contents of the topmost output buffer (if any) and turn this output buffer off.
<?php fbtTransform(); ?>
...
<fbt desc="auto-wrap example">
Go on an
<a href="#">
<span>awesome</span> vacation
</a>
</fbt>
...
<?php endFbtTransform(); ?>
// result: Go on an <a href="#"><span>awesome</span> vacation</a>
fbt()
fbt(
[
'Go on an ',
\fbt\createElement('a', \fbt\createElement('span', 'awesome'), ['href' => '#']),
' vacation',
],
'It\'s simple',
['project' => "foo"]
)
// result: Go on an <a href="#"><span>awesome</span> vacation</a>
fbt('You just friended ' . \fbt\fbt::name('name', 'Sarah', 2 /* gender */), 'names')
// result: You just friended Sarah
fbt('A simple string', 'It\'s simple', ['project' => "foo"])
// result: A simple string