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
@@ -15,21 +11,11 @@ php:
 
 matrix:
     include:
-        - php: 5.3
-          dist: precise
-          env: COMPOSER_MEMORY_LIMIT=3G
-        - php: 5.4
-          dist: trusty
-        - php: 5.5
-          dist: trusty
         - php: 7.0
           env: COVERAGE=1
         - 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+.