Use objects to specify lengths, colors, and border styles

This enables PHPWord to validate input more accurately,
and simplifies setting values for authors.

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: precise
 
 php:
-    - 5.3
-    - 5.4
-    - 5.5
-    - 5.6
     - 7.0
     - 7.1
     - 7.2
@@ -16,12 +12,9 @@ matrix:
     include:
         - php: 7.0
           env: COVERAGE=1
-        - php: 5.3
-          env: COMPOSER_MEMORY_LIMIT=2G
         - php: 7.3
           env: DEPENDENCIES="--ignore-platform-reqs"
     exclude:
-        - php: 5.3
         - php: 7.0
         - php: 7.3
 

CHANGELOG.md

@@ -5,15 +5,22 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 v0.17.0 (?? ??? 2019)
 ----------------------
+This release marked the addition of 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 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
 
 ### Fixed
 - Fix HTML border-color parsing. @troosan #1551 #1570
+- Fixed specifying cell widths, background color, etc on `PhpOffice\PhpWord\Style\Cell` @0b10011 #1669
 
 ### Miscellaneous
+-
 - Use embedded http server to test loading of remote images @troosan #
 
 v0.16.0 (30 dec 2018)

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

@@ -25,7 +25,7 @@ section. Example:
 
     $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

@@ -41,14 +41,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, '
@@ -61,7 +61,7 @@ folder <https://github.com/PHPOffice/PHPWord/tree/master/samples/>`__.
     $fontStyle = new \PhpOffice\PhpWord\Style\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);
 
@@ -139,7 +139,7 @@ default font by using the following two functions:
 .. code-block:: php
 
     $phpWord->setDefaultFontName('Times New Roman');
-    $phpWord->setDefaultFontSize(12);
+    $phpWord->setDefaultFontSize(Absolute::from('pt', 12));
 
 Document settings
 -----------------
@@ -251,25 +251,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 +326,12 @@ 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));
+    $phpWord->getSettings()->setHyphenationZone(\PhpOffice\PhpWord\Style\Lengths\Absolute::from('cm', 1));
 
 Hyphenate Caps
 ~~~~~~~~~~~~~~

docs/installing.rst

@@ -8,7 +8,7 @@ Requirements
 
 Mandatory:
 
-- PHP 5.3.3+
+- PHP 7+
 - `XML Parser <http://www.php.net/manual/en/xml.installation.php>`__ extension
 - `Zend\\Escaper <http://framework.zend.com/manual/current/en/modules/zend.escaper.introduction.html>`__ component
 - Zend\\Stdlib component
@@ -34,7 +34,7 @@ Example:
 
     {
         "require": {
-           "phpoffice/phpword": "v0.14.*"
+           "phpoffice/phpword": "v0.16.*"
         }
     }
 

docs/recipes.rst

@@ -10,9 +10,11 @@ Use absolute positioning relative to margin horizontally and to line vertically.
 
 .. code-block:: php
 
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
     $imageStyle = array(
-        'width' => 40,
-        'height' => 40,
+        'width' => Absolute::from('twip', 40),
+        'height' => Absolute::from('twip', 40),
         'wrappingStyle' => 'square',
         'positioning' => 'absolute',
         'posHorizontalRel' => 'margin',
@@ -72,10 +74,13 @@ Apply 'HeadingN' paragraph style to TextRun or Link. Sample code:
 
 .. code-block:: php
 
+    use PhpOffice\PhpWord\Style\Colors\Hex
+    use PhpOffice\PhpWord\Style\Lengths\Absolute;
+
     $phpWord = new \PhpOffice\PhpWord\PhpWord();
-    $phpWord->addTitleStyle(1, array('size' => 16, 'bold' => true));
-    $phpWord->addTitleStyle(2, array('size' => 14, 'bold' => true));
-    $phpWord->addFontStyle('Link', array('color' => '0000FF', 'underline' => 'single'));
+    $phpWord->addTitleStyle(1, array('size' => Absolute::from('pt', 16), 'bold' => true));
+    $phpWord->addTitleStyle(2, array('size' => Absolute::from('pt', 14), 'bold' => true));
+    $phpWord->addFontStyle('Link', array('color' => new Hex('0000FF'), 'underline' => 'single'));
 
     $section = $phpWord->addSection();