Search by

phil / braille-export

phil

Documents exported to braille: uncontracted French and English in PHP, contracted braille through a translator, braille page layout, and BRF, PEF and Unicode.

0.1.0-alpha 2026-11-20 22:00 UTC

This package is auto-updated.

Last update: 2026-11-21 03:04:41 UTC


README

A document laid out in braille pages and written as BRF, PEF or Unicode braille, in contracted or uncontracted braille.

phil/braille-export is a plain PHP library. It takes a simple structured document — headings, paragraphs, lists, tables, page breaks and print page markers — or a UJO (Universal JSON Output) document, translates its text into braille cells, lays the cells out in braille pages, and writes the pages in the format an embosser, a braille notetaker or a screen reads.

  • Translation goes through the Translator port, one batch per document. UncontractedTranslator writes uncontracted French (Code braille français uniformisé) and English (Unified English Braille) in PHP, with no program to install. Contracted braille, and every other language, comes from a translator with full tables, such as phil/braille-export-liblouis; ChainTranslator puts the PHP translator behind it for when it is missing.
  • Layout follows the braille page: 40 cells by 25 lines by default, paragraphs starting in cell 3, headings centred or in cell 5 and 7 and kept with the line after them, lists indented by level, tables linearized row by row, the braille page number at the end of the last line, the print page at the end of the first line and a line of dots 3-6 where a print page starts. A word too long for a line is cut after its own hyphen when it has one, so that no second hyphen is added.
  • Formats: BRF, the North American ASCII braille file embossers print; PEF 2008-1, the XML of the DAISY Consortium that keeps volumes, sections and pages; Unicode braille for a preview on a screen.

It is a package of its own, apart from the paged-media templates: a braille edition is laid out in cells, not in points, and needs none of a print engine.

Status

Part State
The document model, and UJO documents read into it Implemented and tested
UncontractedTranslator: uncontracted French and English Implemented and tested
ChainTranslator and the Translator port Implemented and tested
BrailleExporter and PageFormat: the layout of braille pages Implemented, tested and fuzzed
BrfWriter, PefWriter, UnicodeWriter Implemented and tested

Documentation

Document What it covers
Installation Requirements, installing, and the translator to choose.
Documents The blocks of a document, and a UJO document read into them.
Translation The Translator port, uncontracted French and English, contracted braille, the chain.
Layout The page format and how each block is laid out: indentation, headings, lists, tables, page numbers, word cutting.
Output formats BRF, PEF and Unicode braille.
Exceptions What the package throws, and when.
Security What any text can and cannot do, and the bounds of an export.
Extension points What an application may replace or add, and when it is stable.
Testing The tests, the fuzz target and the benchmark.
Reference Every public type, with its role.

Quick start

composer require phil/braille-export
use Phil\BrailleExport\BrailleExporter;
use Phil\BrailleExport\Document\Document;
use Phil\BrailleExport\Document\Heading;
use Phil\BrailleExport\Document\Paragraph;
use Phil\BrailleExport\Output\BrfWriter;
use Phil\BrailleExport\Output\PefWriter;
use Phil\BrailleExport\Translation\UncontractedTranslator;

$document = new Document([
    new Heading('Chapitre premier'),
    new Paragraph("Lorsque j'avais six ans, j'ai vu une magnifique image."),
], 'fr', 'Le livre');

$book = new BrailleExporter(new UncontractedTranslator())->layout($document);

file_put_contents('book.brf', new BrfWriter()->write($book));
file_put_contents('book.pef', new PefWriter()->write($book));

Requirements

PHP 8.5 or later with mbstring; phil/ujo 0.1. Contracted braille needs a translator with full tables, such as phil/braille-export-liblouis.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.