Added full PHPWord api, README.md correction

README.md

@@ -22,7 +22,15 @@ bin/cake plugin load PhpWordView
 
 ## Usage
 
-The templates are expected to be present in `src/Templates/Model/docx/`. Template files are just plain word document, not Word model documents.
+
+
+Two different ways to render.
+
+### PHPWord TemplateProcessor
+
+To be used if you need to render simple documents. Serialize the data you want to insert into the template.
+
+The templates are expected to be present in `src/Templates/Model/docx/`, and having `.docx` filename extension. Template files are just plain word document, not Word model documents.
 
 [Create a template document](https://phpword.readthedocs.io/en/latest/templates-processing.html)
 
@@ -31,12 +39,8 @@ public function imprimatur()
 {
     $imprimatur = '667';
     $this->viewBuilder()
-         ->setClassName('PhpWordView.PhpWord')
-         ->options([
-             'wordConfig' => [
-                 'filename' => 'imprimatur-' . $imprimatur,
-             ]
-         ]);
+         ->setClassName('PhpWordView.PhpWord');
+
     $data = [
         'title' => 'Beati Pauperes Spiritu,
         'imprimatur' => $imprimatur,
@@ -46,8 +50,39 @@ public function imprimatur()
 }
 ```
 
-The downloaded filename can be specified with the viewBuilder options.
+### PHPWord full api
+
+To be used when a simple search-replace is not sufficient.
+
+The view files are expected to be present in `src/Templates/Model/docx/`, but having `.ctp` filename extension. Inside your view files you will have access to the PHPWord library with `$this->PhpWord`. Check the [PHPWord](https://github.com/PHPOffice/PHPWord) documentation on how to use PHPWord.
+
+Don't set the `_serialize` variable.
+
+```php
+public function imprimatur($id)
+{
+    $this->viewBuilder()
+         ->setClassName('PhpWordView.PhpWord');
+    $imprimatur = $this->Imprimaturs->get($id);
+    $this->set(compact('imprimatur'));
+}
+```
+
+### Downloaded filename
+
+The downloaded filename can be specified with the viewBuilder options, default is the action name.
+
+```php
+    $this->viewBuilder()
+         ->setClassName('PhpWordView.PhpWord')
+         ->options([
+             'wordConfig' => [
+                 'filename' => 'imprimatur-' . $id,
+             ]
+         ]);
+
+```
 
 ## Troubleshooting
 
-A `Could not close zip file /tmp/PhpWord5gJC0Z` Exception might mean that there is a problem with the template.docx file have incorrect line ending. This can be solved by specifying docx files as binary in the `.gitattributes` file. 
+A `Could not close zip file /tmp/PhpWord5gJC0Z` Exception might mean that there is a problem with the template.docx file have incorrect line ending. This can be solved by specifying docx files as binary in the `.gitattributes` file.

src/View/PhpWordView.php

@@ -7,6 +7,8 @@
 use Cake\Http\Response;
 use Cake\Http\ServerRequest;
 use Cake\View\View;
+use PhpOffice\PhpWord\IOFactory;
+use PhpOffice\PhpWord\PhpWord;
 use PhpOffice\PhpWord\TemplateProcessor;
 
 /**
@@ -15,7 +17,8 @@
  * By setting the 'serialize' view builder option, you can specify a view variable
  * that will replace to corresponding placeholder in the template file.
  *
- * This plugin uses only the templateRender functionnality of PhpWord.
+ * This plugin uses the templateRender functionnality of PhpWord if _serialized
+ * variable is passed, full PHPWord API otherwise.
  */
 class PhpWordView extends View
 {
@@ -47,6 +50,13 @@ class PhpWordView extends View
      */
     protected $_ext = '.docx';
 
+    /**
+     * PHPWord instance
+     *
+     * @var PhpWord
+     */
+    public $PhpWord = null;
+
     /**
      * Constructor
      *
@@ -98,8 +108,29 @@ public function render($view = null, $layout = null)
             : $this->getTemplate();
         $this->response = $this->response->withDownload($filename);
 
+        if (!empty($this->viewVars['_serialize'])) {
+            return $this->serialize();
+        } else {
+            $this->PhpWord = new PhpWord();
+            $this->_ext = '.ctp';
+            $content = parent::render($view, false);
+            if ($this->response->type() == 'text/html') {
+                return $content;
+            }
+            $this->Blocks->set('content', $this->output());
+
+            return $this->Blocks->get('content');
+        }
+    }
+
+    /**
+     * Serialize view vars.
+     *
+     * @return string The serialized data
+     */
+    protected function serialize()
+    {
         $serialize = $this->viewVars['_serialize'];
-        ob_start();
         $templateProcessor = new TemplateProcessor($this->_getViewFileName());
         foreach ((array)$serialize as $viewVar) {
             if (is_scalar($this->viewVars[$viewVar])) {
@@ -110,8 +141,31 @@ public function render($view = null, $layout = null)
                 $templateProcessor->setValue($key, $value);
             }
         }
+
+        ob_start();
         $templateProcessor->saveAs('php://output');
+        $output = ob_get_clean();
+
+        return $output;
+    }
+
+    /**
+     * Generates the binary word document
+     *
+     * @return string
+     * @throws CakeException If the word writer does not exist
+     */
+    protected function output()
+    {
+        $writer = IOFactory::createWriter($this->PhpWord, 'Word2007');
+        if (!isset($$writer)) {
+            throw new Exception('Word writer not found');
+        }
+
+        ob_start();
+        $writer->save('php://output');
+        $output = ob_get_clean();
 
-        return ob_get_clean();
+        return $output;
     }
 }