phil / braille-export
Documents exported to braille: uncontracted French and English in PHP, contracted braille through a translator, braille page layout, and BRF, PEF and Unicode.
Package info
github.com/parler-haut-interagir-librement/braille-export
pkg:composer/phil/braille-export
Requires
- php: >=8.5
- ext-mbstring: *
- phil/ujo: ^0.1@dev
Requires (Dev)
- ext-ctype: *
- ext-dom: *
- phpunit/phpunit: ^13.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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
Translatorport, one batch per document.UncontractedTranslatorwrites 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 asphil/braille-export-liblouis;ChainTranslatorputs 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.