Section: Ability to define gutter and line numbering

Author: ivanlanin

CHANGELOG.md

@@ -39,6 +39,7 @@ This release marked heavy refactorings on internal code structure with the creat
 - ODT Writer: Basic image writing - @ivanlanin
 - ODT Writer: Link writing - @ivanlanin
 - ODT Reader: Basic ODText Reader - @ivanlanin GH-71
+- Section: Ability to define gutter and line numbering
 
 ### Bugfixes
 

docs/containers.rst

@@ -50,6 +50,7 @@ Below are the available settings for section:
 -  ``borderBottomColor`` Border bottom color
 -  ``headerHeight`` Spacing to top of header
 -  ``footerHeight`` Spacing to bottom of footer
+-  ``gutter`` Page gutter spacing
 -  ``colsNum`` Number of columns
 -  ``colsSpace`` Spacing between columns
 -  ``breakType`` Section break type (nextPage, nextColumn, continuous,
@@ -92,6 +93,28 @@ using the ``breakType`` and ``colsNum`` property of the section.
     $section->getSettings()->setBreakType('continuous');
     $section->getSettings()->setColsNum(2);
 
+
+### Line numbering
+
+You can apply line numbering to a section by using the ``lineNumbering``
+property of the section.
+
+.. code-block:: php
+
+    // Method 1
+    $section = $phpWord->addSection(array('lineNumbering' => array()));
+
+    // Method 2
+    $section = $phpWord->addSection();
+    $section->getSettings()->setLineNumbering(array());
+
+Below are the properties of the line numbering style.
+
+-  ``start`` Line numbering starting value
+-  ``increment`` Line number increments
+-  ``distance`` Distance between text and line numbering in twip
+-  ``restart`` Line numbering restart setting continuous|newPage|newSection
+
 Headers
 -------
 

docs/src/documentation.md

@@ -344,6 +344,7 @@ Below are the available settings for section:
 - `borderBottomColor` Border bottom color
 - `headerHeight` Spacing to top of header
 - `footerHeight` Spacing to bottom of footer
+- `gutter` Page gutter spacing
 - `colsNum` Number of columns
 - `colsSpace` Spacing between columns
 - `breakType` Section break type (nextPage, nextColumn, continuous, evenPage, oddPage)
@@ -380,6 +381,26 @@ $section->getSettings()->setBreakType('continuous');
 $section->getSettings()->setColsNum(2);
 ```
 
+### Line numbering
+
+You can apply line numbering to a section by using the `lineNumbering` property of the section.
+
+```php
+// Method 1
+$section = $phpWord->addSection(array('lineNumbering' => array()));
+
+// Method 2
+$section = $phpWord->addSection();
+$section->getSettings()->setLineNumbering(array());
+```
+
+Below are the properties of the line numbering style.
+
+- `start` Line numbering starting value
+- `increment` Line number increments
+- `distance` Distance between text and line numbering in twip
+- `restart` Line numbering restart setting continuous|newPage|newSection
+
 ## Headers
 
 Each section can have its own header reference. To create a header use the `addHeader` method:

src/PhpWord/Settings.php

@@ -16,17 +16,37 @@
  */
 class Settings
 {
-    /** Available Zip library classes */
+    /**
+     * Zip libraries
+     */
     const PCLZIP     = 'PhpOffice\\PhpWord\\Shared\\ZipArchive';
     const ZIPARCHIVE = 'ZipArchive';
 
-    /** Optional PDF Rendering libraries */
+    /**
+     * PDF rendering libraries
+     */
     const PDF_RENDERER_DOMPDF = 'DomPDF';
 
+    /**
+     * Measurement units multiplication factor
+     *
+     * Applied to:
+     * - Section: margins, header/footer height, gutter, column spacing
+     * - Tab: position
+     *
+     * @const int|float
+     */
+    const UNIT_TWIP  = 1; // = 1/20 point
+    const UNIT_CM    = 567;
+    const UNIT_MM    = 56.7;
+    const UNIT_INCH  = 1440;
+    const UNIT_POINT = 20; // = 1/72 inch
+    const UNIT_PICA  = 240; // = 1/6 inch = 12 points
+
     /**
      * Compatibility option for XMLWriter
      *
-     * @var boolean
+     * @var bool
      */
     private static $xmlWriterCompatibility = true;
 
@@ -58,37 +78,46 @@ class Settings
      */
     private static $pdfRendererPath = null;
 
+    /**
+     * Measurement unit
+     *
+     * @var string
+     */
+    private static $measurementUnit = self::UNIT_TWIP;
+
     /**
      * Set the compatibility option used by the XMLWriter
      *
-     * @param boolean $compatibility  This sets the setIndent and setIndentString for better compatibility
-     * @return  boolean Success or failure
+     * This sets the setIndent and setIndentString for better compatibility
+     *
+     * @param bool $compatibility
+     * @return bool
      */
     public static function setCompatibility($compatibility)
     {
         if (is_bool($compatibility)) {
             self::$xmlWriterCompatibility = $compatibility;
             return true;
         }
+
         return false;
     }
 
     /**
      * Return the compatibility option used by the XMLWriter
      *
-     * @return boolean Compatibility
+     * @return bool Compatibility
      */
     public static function getCompatibility()
     {
         return self::$xmlWriterCompatibility;
     }
 
     /**
-     * Set the Zip handler Class that PHPWord should use for Zip file management (PCLZip or ZipArchive)
+     * Set zip handler class
      *
-     * @param  string $zipClass  The Zip handler class that PHPWord should use for Zip file management
-     *   e.g. Settings::PCLZip or Settings::ZipArchive
-     * @return boolean Success or failure
+     * @param  string $zipClass
+     * @return bool
      */
     public static function setZipClass($zipClass)
     {
@@ -97,16 +126,14 @@ public static function setZipClass($zipClass)
             self::$zipClass = $zipClass;
             return true;
         }
+
         return false;
     }
 
     /**
-     * Return the name of the Zip handler Class that PHPWord is configured to use (PCLZip or ZipArchive)
-     *  or Zip file management
+     * Get zip handler class
      *
-     * @return string Name of the Zip handler Class that PHPWord is configured to use
-     *  for Zip file management
-     *  e.g. Settings::PCLZip or Settings::ZipArchive
+     * @return string
      */
     public static function getZipClass()
     {
@@ -118,7 +145,7 @@ public static function getZipClass()
      *
      * @param string $libraryName
      * @param string $libraryBaseDir
-     * @return boolean Success or failure
+     * @return bool Success or failure
      */
     public static function setPdfRenderer($libraryName, $libraryBaseDir)
     {
@@ -141,14 +168,13 @@ public static function getPdfRendererName()
      * Identify the external library to use for rendering PDF files
      *
      * @param string $libraryName
-     * @return boolean Success or failure
+     * @return bool
      */
     public static function setPdfRendererName($libraryName)
     {
         if (!in_array($libraryName, self::$pdfRenderers)) {
             return false;
         }
-
         self::$pdfRendererName = $libraryName;
 
         return true;
@@ -167,7 +193,7 @@ public static function getPdfRendererPath()
      * Location of external library to use for rendering PDF files
      *
      * @param string $libraryBaseDir Directory path to the library's base folder
-     * @return boolean Success or failure
+     * @return bool Success or failure
      */
     public static function setPdfRendererPath($libraryBaseDir)
     {
@@ -178,4 +204,31 @@ public static function setPdfRendererPath($libraryBaseDir)
 
         return true;
     }
+
+    /**
+     * Get measurement unit
+     *
+     * @return int|float
+     */
+    public static function getMeasurementUnit()
+    {
+        return self::$measurementUnit;
+    }
+
+    /**
+     * Set measurement unit
+     *
+     * @param int|float $value
+     * @return bool
+     */
+    public static function setMeasurementUnit($value)
+    {
+        $units = array(self::UNIT_TWIP, self::UNIT_CM, self::UNIT_MM, self::UNIT_INCH, self::UNIT_POINT, self::UNIT_PICA);
+        if (!in_array($value, $units)) {
+            return false;
+        }
+        self::$measurementUnit = $value;
+
+        return true;
+    }
 }