New `PhpWord::save()` method to encapsulate `IOFactory`

CHANGELOG.md

@@ -13,6 +13,7 @@ This release added drawing shapes (arc, curve, line, polyline, rect, oval) eleme
 - Paragraph:  Added shading to the paragraph style for full width shading - @lrobert GH-264
 - RTF Writer: Support for sections, margins, and borders - @ivanlanin GH-249
 - Section: Ability to set paper size, e.g. A4, A3, and Legal - @ivanlanin GH-249
+- General: New `PhpWord::save()` method to encapsulate `IOFactory` - @ivanlanin
 
 ### Bugfixes
 

README.md

@@ -100,15 +100,10 @@ $fontStyle->setSize(22);
 $myTextElement = $section->addText('Hello World!');
 $myTextElement->setFontStyle($fontStyle);
 
-// Finally, write the document:
+// Finally, save the document:
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');
+$phpWord->save('helloWorld.docx');
-$objWriter->save('helloWorld.docx');
+$phpWord->save('helloWorld.odt', 'ODText');
-
+$phpWord->save('helloWorld.rtf', 'RTF');
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'ODText');
-$objWriter->save('helloWorld.odt');
-
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'RTF');
-$objWriter->save('helloWorld.rtf');
 ```
 
 ## Known issues

docs/general.rst

@@ -43,15 +43,10 @@ folder <https://github.com/PHPOffice/PHPWord/tree/master/samples/>`__.
     $myTextElement = $section->addText('Hello World!');
     $myTextElement->setFontStyle($fontStyle);
 
-    // Finally, write the document:
+    // Finally, save the document:
-    $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');
+    $phpWord->save('helloWorld.docx');
-    $objWriter->save('helloWorld.docx');
+    $phpWord->save('helloWorld.odt', 'ODText');
-
+    $phpWord->save('helloWorld.rtf', 'RTF');
-    $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'ODText');
-    $objWriter->save('helloWorld.odt');
-
-    $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'RTF');
-    $objWriter->save('helloWorld.rtf');
 
 Settings
 --------

docs/src/documentation.md

@@ -238,15 +238,10 @@ $fontStyle->setSize(22);
 $myTextElement = $section->addText('Hello World!');
 $myTextElement->setFontStyle($fontStyle);
 
-// Finally, write the document:
+// Finally, save the document:
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');
+$phpWord->save('helloWorld.docx');
-$objWriter->save('helloWorld.docx');
+$phpWord->save('helloWorld.odt', 'ODText');
-
+$phpWord->save('helloWorld.rtf', 'RTF');
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'ODText');
-$objWriter->save('helloWorld.odt');
-
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'RTF');
-$objWriter->save('helloWorld.rtf');
 ```
 
 ## Settings

samples/Sample_Header.php

@@ -4,7 +4,6 @@
  */
 use PhpOffice\PhpWord\Autoloader;
 use PhpOffice\PhpWord\Settings;
-use PhpOffice\PhpWord\IOFactory;
 
 error_reporting(E_ALL);
 define('CLI', (PHP_SAPI == 'cli') ? true : false);
@@ -59,12 +58,11 @@ function write($phpWord, $filename, $writers)
     $result = '';
 
     // Write documents
-    foreach ($writers as $writer => $extension) {
+    foreach ($writers as $format => $extension) {
-        $result .= date('H:i:s') . " Write to {$writer} format";
+        $result .= date('H:i:s') . " Write to {$format} format";
-        if (!is_null($extension)) {
+        if ($extension !== null) {
-            $xmlWriter = IOFactory::createWriter($phpWord, $writer);
+            $targetFile = __DIR__ . "/results/{$filename}.{$extension}";
-            $xmlWriter->save(__DIR__ . "/{$filename}.{$extension}");
+            $phpWord->save($targetFile, $format);
-            rename(__DIR__ . "/{$filename}.{$extension}", __DIR__ . "/results/{$filename}.{$extension}");
         } else {
             $result .= ' ... NOT DONE!';
         }

src/PhpWord/PhpWord.php

@@ -260,6 +260,43 @@ class PhpWord
         }
     }
 
+    /**
+     * Save to file or download
+     *
+     * All exceptions should already been handled by the writers
+     *
+     * @param string $filename
+     * @param string $format
+     * @param bool $download
+     * @return bool
+     */
+    public function save($filename, $format = 'Word2007', $download = false)
+    {
+        $mime = array(
+            'Word2007'  => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            'ODT'       => 'application/vnd.oasis.opendocument.text',
+            'RTF'       => 'application/rtf',
+            'HTML'      => 'text/html',
+            'PDF'       => 'application/pdf',
+        );
+
+        $writer = IOFactory::createWriter($this, $format);
+
+        if ($download === true) {
+            header("Content-Description: File Transfer");
+            header('Content-Disposition: attachment; filename="' . $filename . '"');
+            header('Content-Type: ' . $mime[$format]);
+            header('Content-Transfer-Encoding: binary');
+            header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
+            header('Expires: 0');
+            $filename = 'php://output'; // Change filename to force download
+        }
+
+        $writer->save($filename);
+
+        return true;
+    }
+
     /**
      * Create new section
      *

tests/PhpWord/Tests/PhpWordTest.php

@@ -158,4 +158,16 @@ class PhpWordTest extends \PHPUnit_Framework_TestCase
         $phpWord = new PhpWord();
         $phpWord->loadTemplate($templateFqfn);
     }
+
+    /**
+     * Test save
+     */
+    public function testSave()
+    {
+        $phpWord = new PhpWord();
+        $section = $phpWord->addSection();
+        $section->addText('Hello world!');
+
+        $this->assertTrue($phpWord->save('test.docx', 'Word2007', true));
+    }
 }