Use objects to specify lengths, colors, and border styles

Author: 0b10011

.php_cs.dist

@@ -23,7 +23,7 @@ return PhpCsFixer\Config::create()
             'combine_consecutive_unsets' => true,
             'concat_space' => array('spacing' => 'one'),
             'declare_equal_normalize' => true,
-            'declare_strict_types' => false, // Too early to adopt strict types
+            'declare_strict_types' => true,
             'dir_constant' => true,
             'elseif' => true,
             'encoding' => true,
@@ -71,6 +71,7 @@ return PhpCsFixer\Config::create()
             'no_spaces_after_function_name' => true,
             'no_spaces_around_offset' => true,
             'no_spaces_inside_parenthesis' => true,
+            'no_superfluous_phpdoc_tags' => true,
             'no_trailing_comma_in_list_call' => true,
             'no_trailing_comma_in_singleline_array' => true,
             'no_trailing_whitespace' => true,
@@ -109,10 +110,11 @@ return PhpCsFixer\Config::create()
             'phpdoc_single_line_var_spacing' => true,
             'phpdoc_summary' => false,
             'phpdoc_to_comment' => true,
+            'phpdoc_to_return_type' => false,
             'phpdoc_trim' => true,
             'phpdoc_types' => true,
             'phpdoc_var_without_name' => true,
-            'pow_to_exponentiation' => false,
+            'pow_to_exponentiation' => true,
             'pre_increment' => false,
             'protected_to_private' => true,
             'psr0' => true,
@@ -137,7 +139,7 @@ return PhpCsFixer\Config::create()
             'switch_case_semicolon_to_colon' => true,
             'switch_case_space' => true,
             'ternary_operator_spaces' => true,
-            'ternary_to_null_coalescing' => false, // Cannot use that with PHP 5.6
+            'ternary_to_null_coalescing' => true,
             'trailing_comma_in_multiline_array' => true,
             'trim_array_spaces' => false,
             'unary_operator_spaces' => true,

.travis.yml

@@ -3,10 +3,6 @@ language: php
 dist: xenial
 
 php:
-    - 5.3
-    - 5.4
-    - 5.5
-    - 5.6
     - 7.0
     - 7.1
     - 7.2
@@ -27,9 +23,6 @@ matrix:
         - php: 7.3
           env: DEPENDENCIES="--ignore-platform-reqs"
     exclude:
-        - php: 5.3
-        - php: 5.4
-        - php: 5.5
         - php: 7.0
         - php: 7.3
     allow_failures:

CHANGELOG.md

@@ -5,15 +5,33 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 v0.17.0 (?? ??? 2019)
 ----------------------
+This release marked the addition of strict typing and return type declarations (PHP 7+).
+
 ### Added
 - Add RightToLeft table presentation. @troosan #1550
 - Set complex type in template @troosan #1565
 - Add support for page vertical alignment. @troosan #672 #1569
+- Length validation and automatic unit conversion with `PhpOffice\PhpWord\Style\Lengths\{Absolute, Auto, Percent}` @0b10011 #1669
+- Color validation with `PhpOffice\PhpWord\Style\Colors\{BasicColor, SpecialColor}` @0b10011 #1669
+- BorderStyle validation with `PhpOffice\PhpWord\Style\BorderStyle` @0b10011 #1669
+- Support for additional `border-style` values (`hidden`, `groove`, `ridge`, `inset`, and `outset`) in HTML documents @0b10011 #1669
+- Support for all named colors from CSS in HTML documents @0b10011 #1669
+- Support for borders on `Cell` @0b10011 #1669
+- Support for writing percent and auto column widths on `Table` to ODT files @0b10011 #1669
+- Support for `space` and `shadow` on `Border` (and support for writing to Word2007) @0b10011 #1669
+
+### Changed
+- `float` and `int` are no longer supported for lengths. Only `PhpOffice\PhpWord\Style\Lengths\{Absolute, Auto, Percent}` are allowed. @0b10011 #1669
+- `string` is no longer supported for colors. Only `PhpOffice\PhpWord\Style\Colors\{BasicColor, SpecialColor}` is allowed. @0b10011 #1669
+- `string` is no longer supported for border styles. Only `PhpOffice\PhpWord\Style\BorderStyle` is allowed. @0b10011 #1669
 
 ### Fixed
 - Fix HTML border-color parsing. @troosan #1551 #1570
+- Fixed specifying cell widths, background color, etc on `PhpOffice\PhpWord\Style\Cell` @0b10011 #1669
+- Escape arrays of replacements in `TemplateProcessor` @0b10011 #1669
 
 ### Miscellaneous
+-
 - Use embedded http server to test loading of remote images @troosan #
 
 v0.16.0 (30 dec 2018)

README.md

@@ -101,8 +101,13 @@ The following is a basic usage example of the PHPWord library.
 <?php
 require_once 'bootstrap.php';
 
+use PhpOffice\PhpWord\PhpWord;
+use PhpOffice\PhpWord\Style\Font;
+use PhpOffice\PhpWord\Style\Colors\Hex;
+use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
 // Creating the new document...
-$phpWord = new \PhpOffice\PhpWord\PhpWord();
+$phpWord = new PhpWord();
 
 /* Note: any element you append to a document must reside inside of a Section. */
 
@@ -127,14 +132,14 @@ $section->addText(
     '"Great achievement is usually born of great sacrifice, '
         . 'and is never the result of selfishness." '
         . '(Napoleon Hill)',
-    array('name' => 'Tahoma', 'size' => 10)
+    array('name' => 'Tahoma', 'size' => Absolute::from('pt', 10))
 );
 
 // Adding Text element with font customized using named font style...
 $fontStyleName = 'oneUserDefinedStyle';
 $phpWord->addFontStyle(
     $fontStyleName,
-    array('name' => 'Tahoma', 'size' => 10, 'color' => '1B2232', 'bold' => true)
+    array('name' => 'Tahoma', 'size' => Absolute::from('pt', 10), 'color' => new Hex('1B2232'), 'bold' => true)
 );
 $section->addText(
     '"The greatest accomplishment is not in never falling, '
@@ -144,10 +149,10 @@ $section->addText(
 );
 
 // Adding Text element with font customized using explicitly created font style object...
-$fontStyle = new \PhpOffice\PhpWord\Style\Font();
+$fontStyle = new Font();
 $fontStyle->setBold(true);
 $fontStyle->setName('Tahoma');
-$fontStyle->setSize(13);
+$fontStyle->setSize(Absolute::from('pt', 13));
 $myTextElement = $section->addText('"Believe you can and you\'re halfway there." (Theodor Roosevelt)');
 $myTextElement->setFontStyle($fontStyle);
 

composer.json

@@ -58,19 +58,19 @@
         "fix": "Fixes issues found by PHP-CS"
     },
     "require": {
-        "php": "^5.3.3 || ^7.0",
+        "php": "^7.0",
         "ext-xml": "*",
         "zendframework/zend-escaper": "^2.2",
         "phpoffice/common": "^0.2.9"
     },
     "require-dev": {
         "ext-zip": "*",
         "ext-gd": "*",
-        "phpunit/phpunit": "^4.8.36 || ^7.0",
-        "squizlabs/php_codesniffer": "^2.9",
-        "friendsofphp/php-cs-fixer": "^2.2",
-        "phpmd/phpmd": "2.*",
-        "phploc/phploc": "2.* || 3.* || 4.*",
+        "phpunit/phpunit": "^6.0 || ^7.0",
+        "squizlabs/php_codesniffer": "*",
+        "friendsofphp/php-cs-fixer": "*",
+        "phpmd/phpmd": "*",
+        "phploc/phploc": "*",
         "dompdf/dompdf":"0.8.*",
         "tecnickcom/tcpdf": "6.*",
         "mpdf/mpdf": "5.7.4 || 6.* || 7.*",

docs/containers.rst

@@ -23,9 +23,11 @@ section. Example:
 
 .. code-block:: php
 
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
     $sectionStyle = array(
         'orientation' => 'landscape',
-        'marginTop' => 600,
+        'marginTop' => Absolute::from('twip', 600),
         'colsNum' => 2,
     );
 

docs/elements.rst

@@ -218,11 +218,11 @@ Table style can be defined with ``addTableStyle``:
 .. code-block:: php
 
     $tableStyle = array(
-        'borderColor' => '006699',
-        'borderSize'  => 6,
-        'cellMargin'  => 50
+        'borderColor' => new Hex('006699'),
+        'borderSize'  => Absolute::from('twip', 6),
+        'cellMargin'  => Absolute::from('twip', 50)
     );
-    $firstRowStyle = array('bgColor' => '66BBFF');
+    $firstRowStyle = array('bgColor' => new Hex('66BBFF'));
     $phpWord->addTableStyle('myTable', $tableStyle, $firstRowStyle);
     $table = $section->addTable('myTable');
 
@@ -235,7 +235,7 @@ You can span a cell on multiple columns by using ``gridSpan`` or multiple rows b
 
 .. code-block:: php
 
-    $cell = $table->addCell(200);
+    $cell = $table->addCell(Absolute::from('twip', 200));
     $cell->getStyle()->setGridSpan(5);
 
 See ``Sample_09_Tables.php`` for more code sample.
@@ -260,10 +260,10 @@ Examples:
     $section->addImage(
         'mars.jpg',
         array(
-            'width'         => 100,
-            'height'        => 100,
-            'marginTop'     => -1,
-            'marginLeft'    => -1,
+            'width'         => Absolute::from('twip', 100),
+            'height'        => Absolute::from('twip', 100),
+            'marginTop'     => Absolute::from('twip', -1),
+            'marginLeft'    => Absolute::from('twip', -1),
             'wrappingStyle' => 'behind'
         )
     );
@@ -285,7 +285,7 @@ header reference. After creating a header, you can use the
 
     $section = $phpWord->addSection();
     $header = $section->addHeader();
-    $header->addWatermark('resources/_earth.jpg', array('marginTop' => 200, 'marginLeft' => 55));
+    $header->addWatermark('resources/_earth.jpg', array('marginTop' => Absolute::from('twip', 200), 'marginLeft' => Absolute::from('twip', 55)));
 
 Objects
 -------
@@ -316,7 +316,7 @@ Options for ``$tocStyle``:
 
 - ``tabLeader``. Fill type between the title text and the page number. Use the defined constants in ``\PhpOffice\PhpWord\Style\TOC``.
 - ``tabPos``. The position of the tab where the page number appears in *twip*.
-- ``indent``. The indent factor of the titles in *twip*.
+- ``indent``. The indent factor of the titles (``\PhpOffice\PhpWord\Style\Lengths\Absolute``).
 
 Footnotes & endnotes
 --------------------
@@ -437,13 +437,13 @@ Line elements can be added to sections by using ``addLine``.
 
 Available line style attributes:
 
-- ``weight``. Line width in *twip*.
-- ``color``. Defines the color of stroke.
+- ``weight``. Line width (``\PhpOffice\PhpWord\Style\Lengths\Absolute``).
+- ``color``. Defines the color of stroke (``\PhpOffice\PhpWord\Style\Colors\BasicColor``).
 - ``dash``. Line types: dash, rounddot, squaredot, dashdot, longdash, longdashdot, longdashdotdot.
 - ``beginArrow``. Start type of arrow: block, open, classic, diamond, oval.
 - ``endArrow``. End type of arrow: block, open, classic, diamond, oval.
-- ``width``. Line-object width in *pt*.
-- ``height``. Line-object height in *pt*.
+- ``width``. Line-object width (``\PhpOffice\PhpWord\Style\Lengths\Absolute``).
+- ``height``. Line-object height (``\PhpOffice\PhpWord\Style\Lengths\Absolute``).
 - ``flip``. Flip the line element: true, false.
 
 Chart

docs/faq.rst

@@ -18,7 +18,7 @@ the merrier, right?
 I’ve been running PHPWord from CodePlex flawlessly, but I can’t use the latest PHPWord from GitHub. Why?
 --------------------------------------------------------------------------------------------------------
 
-PHPWord requires PHP 5.3+ since 0.8, while PHPWord 0.6.3 from CodePlex
+PHPWord requires PHP7.0+ since 0.17 (PHP 5.3+ since 0.8), while PHPWord 0.6.3 from CodePlex
 can run with PHP 5.2. There’s a lot of new features that we can get from
 PHP 5.3 and it’s been around since 2009! You should upgrade your PHP
 version to use PHPWord 0.8+.

docs/general.rst

@@ -15,8 +15,14 @@ folder <https://github.com/PHPOffice/PHPWord/tree/master/samples/>`__.
     <?php
     require_once 'bootstrap.php';
 
+    use PhpOffice\PhpWord\IOFactory;
+    use PhpOffice\PhpWord\PhpWord;
+    use PhpOffice\PhpWord\Style\Font;
+    use PhpOffice\PhpWord\Style\Colors\Hex;
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
     // Creating the new document...
-    $phpWord = new \PhpOffice\PhpWord\PhpWord();
+    $phpWord = new PhpWord();
 
     /* Note: any element you append to a document must reside inside of a Section. */
 
@@ -41,14 +47,14 @@ folder <https://github.com/PHPOffice/PHPWord/tree/master/samples/>`__.
         '"Great achievement is usually born of great sacrifice, '
             . 'and is never the result of selfishness." '
             . '(Napoleon Hill)',
-        array('name' => 'Tahoma', 'size' => 10)
+        array('name' => 'Tahoma', 'size' => Absolute::from('pt', 10))
     );
 
     // Adding Text element with font customized using named font style...
     $fontStyleName = 'oneUserDefinedStyle';
     $phpWord->addFontStyle(
         $fontStyleName,
-        array('name' => 'Tahoma', 'size' => 10, 'color' => '1B2232', 'bold' => true)
+        array('name' => 'Tahoma', 'size' => Absolute::from('pt', 10), 'color' => new Hex('1B2232'), 'bold' => true)
     );
     $section->addText(
         '"The greatest accomplishment is not in never falling, '
@@ -58,23 +64,23 @@ folder <https://github.com/PHPOffice/PHPWord/tree/master/samples/>`__.
     );
 
     // Adding Text element with font customized using explicitly created font style object...
-    $fontStyle = new \PhpOffice\PhpWord\Style\Font();
+    $fontStyle = new Font();
     $fontStyle->setBold(true);
     $fontStyle->setName('Tahoma');
-    $fontStyle->setSize(13);
+    $fontStyle->setSize(Absolute::from('pt', 13));
     $myTextElement = $section->addText('"Believe you can and you\'re halfway there." (Theodor Roosevelt)');
     $myTextElement->setFontStyle($fontStyle);
 
     // Saving the document as OOXML file...
-    $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');
+    $objWriter = IOFactory::createWriter($phpWord, 'Word2007');
     $objWriter->save('helloWorld.docx');
 
     // Saving the document as ODF file...
-    $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'ODText');
+    $objWriter = IOFactory::createWriter($phpWord, 'ODText');
     $objWriter->save('helloWorld.odt');
 
     // Saving the document as HTML file...
-    $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'HTML');
+    $objWriter = IOFactory::createWriter($phpWord, 'HTML');
     $objWriter->save('helloWorld.html');
 
     /* Note: we skip RTF, because it's not XML-based and requires a different example. */
@@ -138,8 +144,10 @@ default font by using the following two functions:
 
 .. code-block:: php
 
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
     $phpWord->setDefaultFontName('Times New Roman');
-    $phpWord->setDefaultFontSize(12);
+    $phpWord->setDefaultFontSize(Absolute::from('pt', 12));
 
 Document settings
 -----------------
@@ -251,25 +259,34 @@ name. Use the following functions:
 Measurement units
 -----------------
 
-The base length unit in Open Office XML is twip. Twip means "TWentieth
-of an Inch Point", i.e. 1 twip = 1/1440 inch.
+While Open Office XML uses twentieths of a point ("twips" or 1/1440 inch)
+for most of its measurements,
+all lengths in PHPWord use an instance of ``\PhpOffice\PhpWord\Style\Lengths\Length``.
+Most measurements are limited to absolute units
+(rather than percent or "auto" values),
+so those use ``\PhpOffice\PhpWord\Style\Lengths\Absolute`` exclusively.
+Methods are typehinted to ensure the right measurement is provided.
 
-You can use PHPWord helper functions to convert inches, centimeters, or
-points to twip.
+You can use ``\PhpOffice\PhpWord\Style\Lengths\Absolute``
+to specify lengths in units you're comfortable with (eg, "pt"),
+and PHPWord will automatically convert those lengths
+to the appropriate ones for the format being exported to.
 
 .. code-block:: php
 
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
     // Paragraph with 6 points space after
     $phpWord->addParagraphStyle('My Style', array(
-        'spaceAfter' => \PhpOffice\PhpWord\Shared\Converter::pointToTwip(6))
-    );
+        'spaceAfter' => Absolute::from('pt', 6)
+    ));
 
     $section = $phpWord->addSection();
     $sectionStyle = $section->getStyle();
     // half inch left margin
-    $sectionStyle->setMarginLeft(\PhpOffice\PhpWord\Shared\Converter::inchToTwip(.5));
+    $sectionStyle->setMarginLeft(Absolute::from('in', .5));
     // 2 cm right margin
-    $sectionStyle->setMarginRight(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(2));
+    $sectionStyle->setMarginRight(Absolute::from('cm', 2));
 
 Document protection
 -------------------
@@ -317,12 +334,14 @@ There is no limit if the option is not set or the provided value is ``0``.
 Hyphenation Zone
 ~~~~~~~~~~~~~~~~
 
-The hyphenation zone (in *twip*) is the allowed amount of whitespace before hyphenation is applied.
+The hyphenation zone is the allowed amount of whitespace before hyphenation is applied.
 The smaller the hyphenation zone the more words are hyphenated. Or in other words, the wider the hyphenation zone the less words are hyphenated.
 
 .. code-block:: php
 
-    $phpWord->getSettings()->setHyphenationZone(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(1));
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
+    $phpWord->getSettings()->setHyphenationZone(Absolute::from('cm', 1));
 
 Hyphenate Caps
 ~~~~~~~~~~~~~~