add the updateFields option on document settings

When set to true, word will ask you to update the fields in the document
when you open the document.

CHANGELOG.md

@@ -18,8 +18,9 @@ This is the last version to support PHP 5.3
 - Support for Comments - @troosan #1067
 - Support for paragraph textAlignment - @troosan #1165
 - Add support for HTML underline tag <u> in addHtml - @zNightFalLz #1186
-- Allow to change cell width unit - guillaume-ro-fr #986
+- Allow to change cell width unit - @guillaume-ro-fr #986
 - Allow to change the line height rule @troosan
+- Allow to force an update of all fields on opening a document - @troosan #951
 
 ### Fixed
 - Loosen dependency to Zend

docs/general.rst

@@ -271,3 +271,12 @@ points to twips.
     $sectionStyle->setMarginLeft(\PhpOffice\PhpWord\Shared\Converter::inchToTwip(.5));
     // 2 cm right margin
     $sectionStyle->setMarginRight(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(2));
+
+Automatically Recalculate Fields on Open
+----------------------------------------
+
+To force an update of the fields present in the document, set updateFields to true
+
+.. code-block:: php
+
+    $phpWord->getSettings()->setUpdateFields(true);

samples/Sample_17_TitleTOC.php

@@ -4,6 +4,7 @@ include_once 'Sample_Header.php';
 // New Word document
 echo date('H:i:s'), ' Create new PhpWord object', EOL;
 $phpWord = new \PhpOffice\PhpWord\PhpWord();
+$phpWord->getSettings()->setUpdateFields(true);
 
 // New section
 $section = $phpWord->addSection();

src/PhpWord/Metadata/Settings.php

@@ -116,6 +116,13 @@ class Settings
      */
     private $themeFontLang;
 
+    /**
+     * Automatically Recalculate Fields on Open
+     *
+     * @var bool
+     */
+    private $updateFields = false;
+
     /**
      * Radix Point for Field Code Evaluation
      *
@@ -345,6 +352,22 @@ class Settings
         $this->themeFontLang = $themeFontLang;
     }
 
+    /**
+     * @return bool
+     */
+    public function hasUpdateFields()
+    {
+        return $this->updateFields;
+    }
+
+    /**
+     * @param bool $updateFields
+     */
+    public function setUpdateFields($updateFields)
+    {
+        $this->updateFields = $updateFields === null ? false : $updateFields;
+    }
+
     /**
      * Returns the Radix Point for Field Code Evaluation
      *

src/PhpWord/Writer/Word2007/Part/Settings.php

@@ -147,6 +147,7 @@ class Settings extends AbstractPart
         $this->setOnOffValue('w:doNotTrackMoves', $documentSettings->hasDoNotTrackMoves());
         $this->setOnOffValue('w:doNotTrackFormatting', $documentSettings->hasDoNotTrackFormatting());
         $this->setOnOffValue('w:evenAndOddHeaders', $documentSettings->hasEvenAndOddHeaders());
+        $this->setOnOffValue('w:updateFields', $documentSettings->hasUpdateFields());
 
         $this->setThemeFontLang($documentSettings->getThemeFontLang());
         $this->setRevisionView($documentSettings->getRevisionView());

tests/PhpWord/Metadata/SettingsTest.php

@@ -153,4 +153,14 @@ class SettingsTest extends \PHPUnit\Framework\TestCase
         $oSettings->setZoom(Zoom::FULL_PAGE);
         $this->assertEquals('fullPage', $oSettings->getZoom());
     }
+
+    /**
+     * Test Update Fields on update
+     */
+    public function testUpdateFields()
+    {
+        $oSettings = new Settings();
+        $oSettings->setUpdateFields(true);
+        $this->assertTrue($oSettings->hasUpdateFields());
+    }
 }