Type hinting and docblock update

src/PhpWord/Element/AbstractContainer.php

@@ -62,7 +62,9 @@ abstract class AbstractContainer extends AbstractElement
             $args[3] = null;
         }
 
-        // Create element
+        // Create element dynamically
+
+        /** @var \PhpOffice\PhpWord\Element\AbstractElement $element Type hint */
         if ($argsCount == 2) {       // TextRun, TextBox, Table, Footnote, Endnote
             $element = new $elementClass($args[1]);
         } elseif ($argsCount == 3) { // Object, TextBreak, Title
@@ -88,6 +90,7 @@ abstract class AbstractContainer extends AbstractElement
             $element->setRelationId($rId);
         }
         if ($elementName == 'Object') {
+            /** @var \PhpOffice\PhpWord\Element\Object $element Type hint */
             $rIdIcon = Media::addElement($mediaContainer, 'image', $element->getIcon(), new Image($element->getIcon()));
             $element->setImageRelationId($rIdIcon);
         }

src/PhpWord/Element/Row.php

@@ -43,7 +43,7 @@ class Row extends AbstractElement
     /**
      * Row cells
      *
-     * @var array
+     * @var \PhpOffice\PhpWord\Element\Cell[]
      */
     private $cells = array();
 
@@ -79,7 +79,7 @@ class Row extends AbstractElement
     /**
      * Get all cells
      *
-     * @return array
+     * @return \PhpOffice\PhpWord\Element\Cell[]
      */
     public function getCells()
     {

src/PhpWord/Element/Section.php

@@ -206,6 +206,7 @@ class Section extends AbstractContainer
 
         if (in_array($type, array(Header::AUTO, Header::FIRST, Header::EVEN))) {
             $index = count($collection);
+            /** @var \PhpOffice\PhpWord\Element\AbstractContainer $container Type hint */
             $container = new $containerClass($this->sectionId, ++$index, $type);
             $container->setPhpWord($this->phpWord);
 

src/PhpWord/Element/TOC.php

@@ -95,6 +95,7 @@ class TOC extends AbstractElement
 
         $titles = $this->phpWord->getTitles()->getItems();
         foreach ($titles as $i => $title) {
+            /** @var \PhpOffice\PhpWord\Element\Title $title Type hint */
             $depth = $title->getDepth();
             if ($this->minDepth > $depth) {
                 unset($titles[$i]);

src/PhpWord/Element/Table.php

@@ -34,7 +34,7 @@ class Table extends AbstractElement
     /**
      * Table rows
      *
-     * @var array
+     * @var \PhpOffice\PhpWord\Element\Row[]
      */
     private $rows = array();
 
@@ -83,7 +83,8 @@ class Table extends AbstractElement
     public function addCell($width = null, $style = null)
     {
         $index = count($this->rows) - 1;
-        $cell = $this->rows[$index]->addCell($width, $style);
+        $row = $this->rows[$index];
+        $cell = $row->addCell($width, $style);
 
         return $cell;
     }
@@ -91,7 +92,7 @@ class Table extends AbstractElement
     /**
      * Get all rows
      *
-     * @return array
+     * @return \PhpOffice\PhpWord\Element\Row[]
      */
     public function getRows()
     {
@@ -139,7 +140,9 @@ class Table extends AbstractElement
         if (is_array($this->rows)) {
             $rowCount = count($this->rows);
             for ($i = 0; $i < $rowCount; $i++) {
-                $cellCount = count($this->rows[$i]->getCells());
+                /** @var \PhpOffice\PhpWord\Element\Row $row Type hint */
+                $row = $this->rows[$i];
+                $cellCount = count($row->getCells());
                 if ($columnCount < $cellCount) {
                     $columnCount = $cellCount;
                 }

src/PhpWord/Reader/ODText.php

@@ -62,6 +62,7 @@ class ODText extends AbstractReader implements ReaderInterface
     {
         $partClass = "PhpOffice\\PhpWord\\Reader\\ODText\\{$partName}";
         if (class_exists($partClass)) {
+            /** @var \PhpOffice\PhpWord\Reader\ODText\AbstractPart $part Type hint */
             $part = new $partClass($docFile, $xmlFile);
             $part->setRels($relationships);
             $part->read($phpWord);

src/PhpWord/Reader/Word2007.php

@@ -18,8 +18,8 @@
 namespace PhpOffice\PhpWord\Reader;
 
 use PhpOffice\PhpWord\PhpWord;
-use PhpOffice\PhpWord\Shared\ZipArchive;
 use PhpOffice\PhpWord\Shared\XMLReader;
+use PhpOffice\PhpWord\Shared\ZipArchive;
 
 /**
  * Reader for Word2007
@@ -87,6 +87,7 @@ class Word2007 extends AbstractReader implements ReaderInterface
     {
         $partClass = "PhpOffice\\PhpWord\\Reader\\Word2007\\{$partName}";
         if (class_exists($partClass)) {
+            /** @var \PhpOffice\PhpWord\Reader\Word2007\AbstractPart $part Type hint */
             $part = new $partClass($docFile, $xmlFile);
             $part->setRels($relationships);
             $part->read($phpWord);

src/PhpWord/Reader/Word2007/Document.php

@@ -224,6 +224,7 @@ class Document extends AbstractPart
             $tblStyle = $this->readTableStyle($xmlReader, $domNode);
         }
 
+        /** @var \PhpOffice\PhpWord\Element\Table $table Type hint */
         $table = $parent->addTable($tblStyle);
         $tblNodes = $xmlReader->getElements('*', $domNode);
         foreach ($tblNodes as $tblNode) {

src/PhpWord/Shared/XMLReader.php

@@ -18,7 +18,6 @@
 namespace PhpOffice\PhpWord\Shared;
 
 use PhpOffice\PhpWord\Exception\Exception;
-use PhpOffice\PhpWord\Shared\ZipArchive;
 
 /**
  * XML Reader wrapper
@@ -47,6 +46,7 @@ class XMLReader
      * @param string $zipFile
      * @param string $xmlFile
      * @return \DOMDocument|false
+     * @throws \PhpOffice\PhpWord\Exception\Exception
      */
     public function getDomFromZip($zipFile, $xmlFile)
     {
@@ -118,7 +118,9 @@ class XMLReader
         if ($path !== null) {
             $elements = $this->getElements($path, $contextNode);
             if ($elements->length > 0) {
-                $return = $elements->item(0)->getAttribute($attribute);
+                /** @var \DOMElement $node Type hint */
+                $node = $elements->item(0);
+                $return = $node->getAttribute($attribute);
             }
         } else {
             if ($contextNode !== null) {

src/PhpWord/Shared/XMLWriter.php

@@ -26,7 +26,7 @@ use PhpOffice\PhpWord\Settings;
  * @method bool startDocument(string $version = 1.0, string $encoding = null, string $standalone = null)
  * @method bool startElement(string $name)
  * @method bool text(string $content)
- * @method bool writeAttribute(string $name, string $value)
+ * @method bool writeAttribute(string $name, mixed $value)
  * @method bool writeElement(string $name, string $content = null)
  * @method bool writeRaw(string $content)
  */
@@ -138,10 +138,10 @@ class XMLWriter
     /**
      * Write element if ...
      *
-     * @param bool|null $condition
+     * @param bool $condition
      * @param string $element
      * @param string $attribute
-     * @param string $value
+     * @param mixed $value
      */
     public function writeElementIf($condition, $element, $attribute = null, $value = null)
     {
@@ -159,9 +159,9 @@ class XMLWriter
     /**
      * Write attribute if ...
      *
-     * @param bool|null $condition
+     * @param bool $condition
      * @param string $attribute
-     * @param string $value
+     * @param mixed $value
      */
     public function writeAttributeIf($condition, $attribute, $value)
     {

src/PhpWord/Shared/ZipArchive.php

@@ -29,12 +29,9 @@ use PhpOffice\PhpWord\Settings;
  *
  * @method  bool addFile(string $filename, string $localname = null)
  * @method  bool addFromString(string $localname, string $contents)
- * @method  bool close()
- * @method  bool extractTo(string $destination, mixed $entries = null)
- * @method  string getFromName(string $name)
  * @method  string getNameIndex(int $index)
  * @method  int locateName(string $name)
- * @method  bool open(string $filename, int $flags = null)
+ *
  * @since   0.10.0
  */
 class ZipArchive
@@ -113,7 +110,10 @@ class ZipArchive
         }
 
         // Run function
-        $result = @call_user_func_array(array($zipObject, $zipFunction), $args);
+        $result = false;
+        if (method_exists($zipObject, $zipFunction)) {
+            $result = @call_user_func_array(array($zipObject, $zipFunction), $args);
+        }
 
         return $result;
     }
@@ -131,14 +131,18 @@ class ZipArchive
         $this->filename = $filename;
 
         if (!$this->usePclzip) {
-            $this->zip = new \ZipArchive();
+            $zip = new \ZipArchive();
-            $result = $this->zip->open($this->filename, $flags);
+            $result = $zip->open($this->filename, $flags);
-            $this->numFiles = $this->zip->numFiles;
+
+            // Scrutizer will report the property numFiles does not exist
+            // See https://github.com/scrutinizer-ci/php-analyzer/issues/190
+            $this->numFiles = $zip->numFiles;
         } else {
-            $this->zip = new \PclZip($this->filename);
+            $zip = new \PclZip($this->filename);
             $this->tempDir = sys_get_temp_dir();
-            $this->numFiles = count($this->zip->listContent());
+            $this->numFiles = count($zip->listContent());
         }
+        $this->zip = $zip;
 
         return $result;
     }
@@ -185,7 +189,7 @@ class ZipArchive
      * Extract file from archive by given file name (emulate \ZipArchive)
      *
      * @param  string $filename Filename for the file in zip archive
-     * @return string|false $contents File string contents
+     * @return string $contents File string contents
      */
     public function getFromName($filename)
     {
@@ -211,6 +215,8 @@ class ZipArchive
      */
     public function pclzipAddFile($filename, $localname = null)
     {
+        /** @var \PclZip $zip Type hint */
+        $zip = $this->zip;
         $filename = realpath($filename);
         $filenameParts = pathinfo($filename);
         $localnameParts = pathinfo($localname);
@@ -226,7 +232,8 @@ class ZipArchive
 
         $pathRemoved = $filenameParts['dirname'];
         $pathAdded = $localnameParts['dirname'];
-        $res = $this->zip->add($filename, PCLZIP_OPT_REMOVE_PATH, $pathRemoved, PCLZIP_OPT_ADD_PATH, $pathAdded);
+
+        $res = $zip->add($filename, PCLZIP_OPT_REMOVE_PATH, $pathRemoved, PCLZIP_OPT_ADD_PATH, $pathAdded);
 
         return ($res == 0) ? false : true;
     }
@@ -240,7 +247,8 @@ class ZipArchive
      */
     public function pclzipAddFromString($localname, $contents)
     {
-        // PCLZip emulation
+        /** @var \PclZip $zip Type hint */
+        $zip = $this->zip;
         $filenameParts = pathinfo($localname);
 
         // Write $contents to a temp file
@@ -252,7 +260,8 @@ class ZipArchive
         $filename = $this->tempDir . '/' . $filenameParts["basename"];
         $pathRemoved = $this->tempDir;
         $pathAdded = $filenameParts['dirname'];
-        $res = $this->zip->add($filename, PCLZIP_OPT_REMOVE_PATH, $pathRemoved, PCLZIP_OPT_ADD_PATH, $pathAdded);
+
+        $res = $zip->add($filename, PCLZIP_OPT_REMOVE_PATH, $pathRemoved, PCLZIP_OPT_ADD_PATH, $pathAdded);
 
         // Remove temp file
         @unlink($this->tempDir . '/' . $filenameParts["basename"]);
@@ -270,9 +279,12 @@ class ZipArchive
      */
     public function pclzipExtractTo($destination, $entries = null)
     {
+        /** @var \PclZip $zip Type hint */
+        $zip = $this->zip;
+
         // Extract all files
         if (is_null($entries)) {
-            $result = $this->zip->extract(PCLZIP_OPT_PATH, $destination);
+            $result = $zip->extract(PCLZIP_OPT_PATH, $destination);
             return ($result > 0) ? true : false;
         }
 
@@ -282,7 +294,7 @@ class ZipArchive
         }
         foreach ($entries as $entry) {
             $entryIndex = $this->locateName($entry);
-            $result = $this->zip->extractByIndex($entryIndex, PCLZIP_OPT_PATH, $destination);
+            $result = $zip->extractByIndex($entryIndex, PCLZIP_OPT_PATH, $destination);
             if ($result <= 0) {
                 return false;
             }
@@ -295,19 +307,21 @@ class ZipArchive
      * Extract file from archive by given file name (emulate \ZipArchive)
      *
      * @param  string $filename Filename for the file in zip archive
-     * @return string|false $contents File string contents
+     * @return string $contents File string contents
      */
     public function pclzipGetFromName($filename)
     {
-        $listIndex = $this->locateName($filename);
+        /** @var \PclZip $zip Type hint */
+        $zip = $this->zip;
+        $listIndex = $this->pclzipLocateName($filename);
         $contents = false;
 
         if ($listIndex !== false) {
-            $extracted = $this->zip->extractByIndex($listIndex, PCLZIP_OPT_EXTRACT_AS_STRING);
+            $extracted = $zip->extractByIndex($listIndex, PCLZIP_OPT_EXTRACT_AS_STRING);
         } else {
             $filename = substr($filename, 1);
-            $listIndex = $this->locateName($filename);
+            $listIndex = $this->pclzipLocateName($filename);
-            $extracted = $this->zip->extractByIndex($listIndex, PCLZIP_OPT_EXTRACT_AS_STRING);
+            $extracted = $zip->extractByIndex($listIndex, PCLZIP_OPT_EXTRACT_AS_STRING);
         }
         if ((is_array($extracted)) && ($extracted != 0)) {
             $contents = $extracted[0]["content"];
@@ -320,12 +334,14 @@ class ZipArchive
      * Returns the name of an entry using its index (emulate \ZipArchive)
      *
      * @param int $index
-     * @return string|false
+     * @return string
      * @since 0.10.0
      */
     public function pclzipGetNameIndex($index)
     {
-        $list = $this->zip->listContent();
+        /** @var \PclZip $zip Type hint */
+        $zip = $this->zip;
+        $list = $zip->listContent();
         if (isset($list[$index])) {
             return $list[$index]['filename'];
         } else {
@@ -337,11 +353,13 @@ class ZipArchive
      * Returns the index of the entry in the archive (emulate \ZipArchive)
      *
      * @param string $filename Filename for the file in zip archive
-     * @return int|false
+     * @return int
      */
     public function pclzipLocateName($filename)
     {
-        $list = $this->zip->listContent();
+        /** @var \PclZip $zip Type hint */
+        $zip = $this->zip;
+        $list = $zip->listContent();
         $listCount = count($list);
         $listIndex = -1;
         for ($i = 0; $i < $listCount; ++$i) {

src/PhpWord/Style/AbstractStyle.php

@@ -169,13 +169,13 @@ abstract class AbstractStyle
     /**
      * Set default for null and empty value
      *
-     * @param string $value
+     * @param string $value (was: mixed)
-     * @param mixed $default
+     * @param string $default (was: mixed)
-     * @return mixed
+     * @return string (was: mixed)
      */
     protected function setNonEmptyVal($value, $default)
     {
-        if (is_null($value) || $value == '') {
+        if ($value === null || $value == '') {
             $value = $default;
         }
 

src/PhpWord/Style/Section.php

@@ -181,15 +181,19 @@ class Section extends Border
     {
         $enum = array(self::ORIENTATION_PORTRAIT, self::ORIENTATION_LANDSCAPE);
         $this->orientation = $this->setEnumVal($value, $enum, $this->orientation);
-        $longSize = $this->pageSizeW >= $this->pageSizeH ? $this->pageSizeW : $this->pageSizeH;
+
-        $shortSize = $this->pageSizeW < $this->pageSizeH ? $this->pageSizeW : $this->pageSizeH;
+        /** @var int|float $longSide Type hint */
+        $longSide = $this->pageSizeW >= $this->pageSizeH ? $this->pageSizeW : $this->pageSizeH;
+
+        /** @var int|float $shortSide Type hint */
+        $shortSide = $this->pageSizeW < $this->pageSizeH ? $this->pageSizeW : $this->pageSizeH;
 
         if ($this->orientation == self::ORIENTATION_PORTRAIT) {
-            $this->pageSizeW = $shortSize;
+            $this->pageSizeW = $shortSide;
-            $this->pageSizeH = $longSize;
+            $this->pageSizeH = $longSide;
         } else {
-            $this->pageSizeW = $longSize;
+            $this->pageSizeW = $longSide;
-            $this->pageSizeH = $shortSize;
+            $this->pageSizeH = $shortSide;
         }
 
         return $this;

src/PhpWord/Writer/HTML.php

@@ -20,9 +20,9 @@ namespace PhpOffice\PhpWord\Writer;
 use PhpOffice\PhpWord\Exception\Exception;
 use PhpOffice\PhpWord\PhpWord;
 use PhpOffice\PhpWord\Settings;
+use PhpOffice\PhpWord\Style;
 use PhpOffice\PhpWord\Style\Font;
 use PhpOffice\PhpWord\Style\Paragraph;
-use PhpOffice\PhpWord\Style;
 use PhpOffice\PhpWord\Writer\HTML\Element\Container;
 use PhpOffice\PhpWord\Writer\HTML\Element\TextRun as TextRunWriter;
 use PhpOffice\PhpWord\Writer\HTML\Style\Font as FontStyleWriter;

src/PhpWord/Writer/HTML/Element/AbstractElement.php

@@ -48,6 +48,11 @@ abstract class AbstractElement
      */
     protected $withoutP = false;
 
+    /**
+     * Write element
+     */
+    abstract public function write();
+
     /**
      * Create new instance
      *

src/PhpWord/Writer/HTML/Element/Container.php

@@ -53,6 +53,7 @@ class Container extends AbstractElement
             $elementClass = get_class($element);
             $writerClass = str_replace('PhpOffice\\PhpWord\\Element', $this->namespace, $elementClass);
             if (class_exists($writerClass)) {
+                /** @var \PhpOffice\PhpWord\Writer\HTML\Element\AbstractElement $writer Type hint */
                 $writer = new $writerClass($this->parentWriter, $element, $withoutP);
                 $content .= $writer->write();
             }

src/PhpWord/Writer/ODText/Part/Content.php

@@ -138,6 +138,7 @@ class Content extends AbstractPart
                 if ($style->isAuto() === true) {
                     $styleClass = str_replace('\\Style\\', '\\Writer\\ODText\\Style\\', get_class($style));
                     if (class_exists($styleClass)) {
+                        /** @var \PhpOffice\PhpWord\Writer\ODText\Style\AbstractStyle $styleWriter Type hint */
                         $styleWriter = new $styleClass($xmlWriter, $style);
                         $styleWriter->write();
                     }

src/PhpWord/Writer/RTF/Element/AbstractElement.php

@@ -30,7 +30,7 @@ use PhpOffice\PhpWord\Writer\RTF\Style\Paragraph as ParagraphStyleWriter;
  *
  * @since 0.11.0
  */
-class AbstractElement extends HTMLAbstractElement
+abstract class AbstractElement extends HTMLAbstractElement
 {
     /**
      * Font style

src/PhpWord/Writer/Word2007.php

@@ -74,9 +74,10 @@ class Word2007 extends AbstractWriter implements WriterInterface
         foreach (array_keys($this->parts) as $partName) {
             $partClass = get_class($this) . '\\Part\\' . $partName;
             if (class_exists($partClass)) {
-                $partObject = new $partClass();
+                /** @var \PhpOffice\PhpWord\Writer\Word2007\Part\AbstractPart $part Type hint */
-                $partObject->setParentWriter($this);
+                $part = new $partClass();
-                $this->writerParts[strtolower($partName)] = $partObject;
+                $part->setParentWriter($this);
+                $this->writerParts[strtolower($partName)] = $part;
             }
         }
 
@@ -175,6 +176,7 @@ class Word2007 extends AbstractWriter implements WriterInterface
                         $this->registerContentTypes($media);
                     }
 
+                    /** @var \PhpOffice\PhpWord\Writer\Word2007\Part\AbstractPart $writerPart Type hint */
                     $writerPart = $this->getWriterPart('relspart')->setMedia($media);
                     $zip->addFromString("word/_rels/{$file}.xml.rels", $writerPart->write());
                 }
@@ -196,12 +198,14 @@ class Word2007 extends AbstractWriter implements WriterInterface
         $elmCount = ($section->getSectionId() - 1) * 3;
         $elements = $section->$getFunction();
         foreach ($elements as &$element) {
+            /** @var \PhpOffice\PhpWord\Element\AbstractElement $element Type hint */
             $elmCount++;
             $element->setRelationId(++$rId);
             $elmFile = "{$elmType}{$elmCount}.xml"; // e.g. footer1.xml
             $this->contentTypes['override']["/word/$elmFile"] = $elmType;
             $this->relationships[] = array('target' => $elmFile, 'type' => $elmType, 'rID' => $rId);
 
+            /** @var \PhpOffice\PhpWord\Writer\Word2007\Part\AbstractPart $writerPart Type hint */
             $writerPart = $this->getWriterPart($elmType)->setElement($element);
             $zip->addFromString("word/$elmFile", $writerPart->write());
         }
@@ -223,6 +227,7 @@ class Word2007 extends AbstractWriter implements WriterInterface
         $collection = $phpWord->$method();
 
         // Add footnotes media files, relations, and contents
+        /** @var \PhpOffice\PhpWord\Collection\AbstractCollection $collection Type hint */
         if ($collection->countItems() > 0) {
             $media = Media::getElements($noteType);
             $this->addFilesToPackage($zip, $media);
@@ -232,6 +237,7 @@ class Word2007 extends AbstractWriter implements WriterInterface
 
             // Write relationships file, e.g. word/_rels/footnotes.xml
             if (!empty($media)) {
+                /** @var \PhpOffice\PhpWord\Writer\Word2007\Part\AbstractPart $writerPart Type hint */
                 $writerPart = $this->getWriterPart('relspart')->setMedia($media);
                 $zip->addFromString("word/_rels/{$partName}.xml.rels", $writerPart->write());
             }

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

@@ -33,6 +33,13 @@ abstract class AbstractPart
      */
     protected $parentWriter;
 
+    /**
+     * Write part
+     *
+     * @return string
+     */
+    abstract public function write();
+
     /**
      * Set parent writer
      *

src/PhpWord/Writer/Word2007/Style/AbstractStyle.php

@@ -82,12 +82,12 @@ abstract class AbstractStyle
      * Convert twip value
      *
      * @param int|float $value
-     * @param int|float $default
+     * @param int $default (int|float)
      * @return int|float
      */
     protected function convertTwip($value, $default = 0)
     {
-        $conversions = array(
+        $factors = array(
             Settings::UNIT_CM => 567,
             Settings::UNIT_MM => 56.7,
             Settings::UNIT_INCH => 1440,
@@ -95,10 +95,11 @@ abstract class AbstractStyle
             Settings::UNIT_PICA => 240,
         );
         $unit = Settings::getMeasurementUnit();
-        if (in_array($unit, $conversions) && $value != $default) {
+        $factor = 1;
-            return $value * $conversions[$unit];
+        if (in_array($unit, $factors) && $value != $default) {
-        } else {
+            $factor = $factors[$unit];
-            return $value;
         }
+
+        return $value * $factor;
     }
 }