getting_started.md

id	title	sidebar_label
getting_started	Integrating into your app	Getting started

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
• 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.
• fallback array: (Default: []) Fallback translations, e.g. ['de_AT' => 'de_DE']

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 choose md5 or tiger hash 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

1. 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.

2. 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

3. 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