Right to left languages

Right to left languages tutorial

Global RTL settings

If you mainly use phpdocx to generate Word documents written in a "right to left" language you may save some typing by establishing global RTL properties in the phpdocxconfig.ini file located in the config folder (that sits directly in the root folder of the phpdocx installation).

In order to do so you should only uncomment (remove the initial ";") the following two lines in phpdocxconfig.ini:

After doing so all your Word content will be assumed to be "right to left" unless explicitly stated.

RTL settings per document

Unless your main source of content for your Word documents come from "right to left" sources you may not want to modify the global configuration settings of phpdocx but rather to do so just for specific documents.

Whenever you are certain that a document is mainly going to include "right to left" content you may instruct phpdocx to treat content by default as RTL by calling the setRTL method just after the standard call to the constructor:

The setRTL method accepts an array as parameter with keys 'bidi' and 'rtl' that are set by default to 'on', although you can set them explicitly to 'off' in case you want to override the global RTL settings discussed in the previous heading.

The setRTL method does not only instruct phpdocx about the fact that the Word content is supposed to be "right to left" but it also modifies some general page layout properties regarding gutters, footnote and endnote separators, etcetera.

RTL settings for specific content

Although you can refer to the API documentation for the use of the bidi and rtl options available for each method, we would like to include here some general comments that will be useful to understand the general logic of the process.

If you have already set the global phpdocx RTL properties, or you used the setRTL method, you may ignore what follows, but we guess that there may pop up plenty of situations were left to right and right to left content may be mixed in a given document so one may need to know how to switch from one to the other.

    WARNING:

  • We do not recommend to run setRTL(array('bidi' => 'on'/'off', 'rtl' => 'on'/'off')) to switch the RTL properties from one part of the document to another because this method sets some document wide properties and you may get unexpected results.

Paragraph wide properties

In order to properly format left to right paragraphs one should generally set the 'bidi' optional parameter to 'on'.

This parameter is available in the following methods (we highlight in bold the parameters that accept that option):

  • addComment($options)
  • addEndnote($options)
  • addFootnote($options)
  • addDateAndHour($options)
  • addHeading($text, $level, $options)
  • addMergefield($name, $mergeParameters, $options)
  • addPageNumber($type, $options)
  • addSimpleField($fieldName, $type, $format, $options)
  • addSection($sectionType, $paperType, $options)
  • addText($textParams, $paragraphParams)
  • modifyPageLayout($paperType, $options)

Text formatting properties

The other required formatting property 'rtl' can be equally set to 'on' in the above methods with the only difference that the addText method accepts also the rtl option in the $textParams variable (in order to format the individual runs of text that may compose the whole paragraph).

Left to right tables

The formatting of tables is equally simple, you only need to set the 'bidi' option to 'on' in the $tableProperties parameter of the addTable method.

    WARNING:

  • If you include WORDML fragments in the individual table cells the content of those fragments should be correctly set up for proper right to left display.
A simple example

We are now going to generate a simple document with some content in Hebrew and Arabic: