Skip to content

[Intl] Remove "Writing and Reading Resource Bundles" section #11590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

[Intl] Remove "Writing and Reading Resource Bundles" section #11590

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
174d86c
Update intl.rst
ro0NL May 22, 2019
298f08b
Update intl.rst
ro0NL May 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 1 addition & 154 deletions components/intl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,160 +52,6 @@ replace the intl classes:

Composer automatically exposes these classes in the global namespace.

Writing and Reading Resource Bundles
------------------------------------

The :phpclass:`ResourceBundle` class is not currently supported by this component.
Instead, it includes a set of readers and writers for reading and writing
arrays (or array-like objects) from/to resource bundle files. The following
classes are supported:

* `TextBundleWriter`_
* `PhpBundleWriter`_
* `BinaryBundleReader`_
* `PhpBundleReader`_
* `BufferedBundleReader`_
* `StructuredBundleReader`_

Continue reading if you are interested in how to use these classes. Otherwise
skip this section and jump to `Accessing ICU Data`_.

TextBundleWriter
~~~~~~~~~~~~~~~~

The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Writer\\TextBundleWriter`
writes an array or an array-like object to a plain-text resource bundle. The
resulting .txt file can be converted to a binary .res file with the
:class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler`
class::

use Symfony\Component\Intl\ResourceBundle\Compiler\BundleCompiler;
use Symfony\Component\Intl\ResourceBundle\Writer\TextBundleWriter;

$writer = new TextBundleWriter();
$writer->write('/path/to/bundle', 'en', [
'Data' => [
'entry1',
'entry2',
// ...
],
]);

$compiler = new BundleCompiler();
$compiler->compile('/path/to/bundle', '/path/to/binary/bundle');

The command "genrb" must be available for the
:class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler` to
work. If the command is located in a non-standard location, you can pass its
path to the
:class:`Symfony\\Component\\Intl\\ResourceBundle\\Compiler\\BundleCompiler`
constructor.

PhpBundleWriter
~~~~~~~~~~~~~~~

The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Writer\\PhpBundleWriter`
writes an array or an array-like object to a .php resource bundle::

use Symfony\Component\Intl\ResourceBundle\Writer\PhpBundleWriter;

$writer = new PhpBundleWriter();
$writer->write('/path/to/bundle', 'en', [
'Data' => [
'entry1',
'entry2',
// ...
],
]);

BinaryBundleReader
~~~~~~~~~~~~~~~~~~

The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\BinaryBundleReader`
reads binary resource bundle files and returns an array or an array-like object.
This class currently only works with the `intl extension`_ installed::

use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;

$reader = new BinaryBundleReader();
$data = $reader->read('/path/to/bundle', 'en');

var_dump($data['Data']['entry1']);

PhpBundleReader
~~~~~~~~~~~~~~~

The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\PhpBundleReader`
reads resource bundles from .php files and returns an array or an array-like
object::

use Symfony\Component\Intl\ResourceBundle\Reader\PhpBundleReader;

$reader = new PhpBundleReader();
$data = $reader->read('/path/to/bundle', 'en');

var_dump($data['Data']['entry1']);

BufferedBundleReader
~~~~~~~~~~~~~~~~~~~~

The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\BufferedBundleReader`
wraps another reader, but keeps the last N reads in a buffer, where N is a
buffer size passed to the constructor::

use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
use Symfony\Component\Intl\ResourceBundle\Reader\BufferedBundleReader;

$reader = new BufferedBundleReader(new BinaryBundleReader(), 10);

// actually reads the file
$data = $reader->read('/path/to/bundle', 'en');

// returns data from the buffer
$data = $reader->read('/path/to/bundle', 'en');

// actually reads the file
$data = $reader->read('/path/to/bundle', 'fr');

StructuredBundleReader
~~~~~~~~~~~~~~~~~~~~~~

The :class:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\StructuredBundleReader`
wraps another reader and offers a
:method:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\StructuredBundleReaderInterface::readEntry`
method for reading an entry of the resource bundle without having to worry
whether array keys are set or not. If a path cannot be resolved, ``null`` is
returned::

use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
use Symfony\Component\Intl\ResourceBundle\Reader\StructuredBundleReader;

$reader = new StructuredBundleReader(new BinaryBundleReader());

$data = $reader->read('/path/to/bundle', 'en');

// produces an error if the key "Data" does not exist
var_dump($data['Data']['entry1']);

// returns null if the key "Data" does not exist
var_dump($reader->readEntry('/path/to/bundle', 'en', ['Data', 'entry1']));

Additionally, the
:method:`Symfony\\Component\\Intl\\ResourceBundle\\Reader\\StructuredBundleReaderInterface::readEntry`
method resolves fallback locales. For example, the fallback locale of "en_GB" is
"en". For single-valued entries (strings, numbers etc.), the entry will be read
from the fallback locale if it cannot be found in the more specific locale. For
multi-valued entries (arrays), the values of the more specific and the fallback
locale will be merged. In order to suppress this behavior, the last parameter
``$fallback`` can be set to ``false``::

var_dump($reader->readEntry(
'/path/to/bundle',
'en',
['Data', 'entry1'],
false
));

Accessing ICU Data
------------------

Expand Down Expand Up @@ -442,6 +288,7 @@ Learn more
/reference/forms/types/currency
/reference/forms/types/language
/reference/forms/types/locale
/reference/forms/types/timezone
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i guess this is missing now :)


.. _Packagist: https://packagist.org/packages/symfony/intl
.. _Icu component: https://packagist.org/packages/symfony/icu
Expand Down