Merge pull request #187 from ivanlanin/#160-element-container

#160 Refactor folders: Element, Container, and Exception

Author: ivanlanin

CHANGELOG.md

@@ -4,6 +4,8 @@ This is the changelog between releases of PHPWord. Releases are listed in revers
 
 ## 0.9.2 - Not yet released
 
+This release marked heavy refactorings on internal code structure with the creation of some abstract classes to reduce code duplication. `Element` subnamespace is introduced in this release to replace `Section`.
+
 ### Features
 
 - Image: Get image dimensions without EXIF extension - @andrew-kzoo GH-184
@@ -17,16 +19,47 @@ This is the changelog between releases of PHPWord. Releases are listed in revers
 - Template: Ability to find & replace variables in headers & footers - @dgudgeon GH-190
 - Template: Ability to clone & delete block of text using `cloneBlock` and `deleteBlock` - @diego-vieira GH-191
 - TOC: Ability to have two or more TOC in one document and to set min and max depth for TOC - @Pyreweb GH-189
+- Table: Ability to add footnote in table cell - @ivanlanin GH-187
+- Footnote: Ability to add image in footnote - @ivanlanin GH-187
+- ListItem: Ability to add list item in header/footer - @ivanlanin GH-187
+- CheckBox: Ability to add checkbox in header/footer - @ivanlanin GH-187
+- Link: Ability to add link in header/footer - @ivanlanin GH-187
+- Object: Ability to add object in header, footer, textrun, and footnote - @ivanlanin GH-187
+- Media: Add `Media::reset()` to reset all media data - @juzi GH-19
+- Style: Add `Style::reset()` to reset all styles
+- Footnote: Add `Footnote::reset()` to reset all footnotes
+- TOC: Add `TOC::reset()` to reset all TOC
 
 ### Bugfixes
 
 - Footnote: Footnote content doesn't show footnote reference number - @ivanlanin GH-170
 
+### Deprecated
+
+- `createTextRun` replaced by `addTextRun`
+- `createFootnote` replaced by `addFootnote`
+- `createHeader` replaced by `addHeader`
+- `createFooter` replaced by `addFooter`
+- `createSection` replaced by `addSection`
+- `Element\Footnote::getReferenceId` replaced by `Element\AbstractElement::getRelationId`
+- `Element\Footnote::setReferenceId` replaced by `Element\AbstractElement::setRelationId`
+- `Footnote::addFootnoteLinkElement` replaced by `Media::addElement`
+- `Footnote::getFootnoteLinkElements` replaced by `Media::getElements`
+- All current methods on `Media`
+
 ### Miscellaneous
 
 - Documentation: Simplify page level docblock - @ivanlanin GH-179
-- Writer: Refactor writer classes and make a new Writer abstract class - @ivanlanin GH-160
-- Reader: Rename AbstractReader > Reader - @ivanlanin
+- Writer: Refactor writer classes and create a new `Write\AbstractWriter` abstract class - @ivanlanin GH-160
+- General: Refactor folders: `Element` and `Exception` - @ivanlanin GH-187
+- General: Remove legacy `HashTable` and `Shared\ZipStreamWrapper` and all related properties/methods - @ivanlanin GH-187
+- Element: New `AbstractElement` abstract class - @ivanlanin GH-187
+- Media: Refactor media class to use one method for all docPart (section, header, footer, footnote) - @ivanlanin GH-187
+- General: Remove underscore prefix from all private properties name - @ivanlanin GH-187
+- General: Move Section `Settings` to `Style\Section` - @ivanlanin GH-187
+- General: Give `Abstract` prefix and `Interface` suffix for all abstract classes and interfaces as per [PHP-FIG recommendation](https://github.com/php-fig/fig-standards/blob/master/bylaws/002-psr-naming-conventions.md) - @ivanlanin GH-187
+- Style: New `Style\AbstractStyle` abstract class - @ivanlanin GH-187
+- Writer: New 'ODText\Base` class - @ivanlanin GH-187
 
 ## 0.9.1 - 27 Mar 2014
 

README.md

@@ -71,7 +71,7 @@ $phpWord = new \PhpOffice\PhpWord\PhpWord();
 
 // Every element you want to append to the word document is placed in a section.
 // To create a basic section:
-$section = $phpWord->createSection();
+$section = $phpWord->addSection();
 
 // After creating a section, you can append elements:
 $section->addText('Hello world!');

docs/containers.rst

@@ -16,7 +16,7 @@ section, use the following code:
 
 .. code-block:: php
 
-    $section = $phpWord->createSection($sectionSettings);
+    $section = $phpWord->addSection($sectionSettings);
 
 The ``$sectionSettings`` is an optional associative array that sets the
 section. Example:
@@ -70,10 +70,10 @@ property of the section.
 .. code-block:: php
 
     // Method 1
-    $section = $phpWord->createSection(array('pageNumberingStart' => 1));
+    $section = $phpWord->addSection(array('pageNumberingStart' => 1));
 
     // Method 2
-    $section = $phpWord->createSection();
+    $section = $phpWord->addSection();
     $section->getSettings()->setPageNumberingStart(1);
 
 Multicolumn
@@ -85,22 +85,22 @@ using the ``breakType`` and ``colsNum`` property of the section.
 .. code-block:: php
 
     // Method 1
-    $section = $phpWord->createSection(array('breakType' => 'continuous', 'colsNum' => 2));
+    $section = $phpWord->addSection(array('breakType' => 'continuous', 'colsNum' => 2));
 
     // Method 2
-    $section = $phpWord->createSection();
+    $section = $phpWord->addSection();
     $section->getSettings()->setBreakType('continuous');
     $section->getSettings()->setColsNum(2);
 
 Headers
 -------
 
 Each section can have its own header reference. To create a header use
-the ``createHeader`` method:
+the ``addHeader`` method:
 
 .. code-block:: php
 
-    $header = $section->createHeader();
+    $header = $section->addHeader();
 
 Be sure to save the result in a local object. You can use all elements
 that are available for the footer. See "Footer" section for detail.
@@ -111,11 +111,11 @@ Footers
 -------
 
 Each section can have its own footer reference. To create a footer, use
-the ``createFooter`` method:
+the ``addFooter`` method:
 
 .. code-block:: php
 
-    $footer = $section->createFooter();
+    $footer = $section->addFooter();
 
 Be sure to save the result in a local object to add elements to a
 footer. You can add the following elements to footers:

docs/elements.rst

@@ -3,20 +3,65 @@
 Elements
 ========
 
+Below are the matrix of element availability in each container. The column shows
+the containers while the rows lists the elements.
+
++-----+---------------+---------+--------+--------+------+----------+----------+
+| Num | Element       | Section | Header | Footer | Cell | Text Run | Footnote |
++=====+===============+=========+========+========+======+==========+==========+
+| 1   | Text          |   v     |   v    |   v    |  v   |   v      |   v      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 2   | Text Run      |   v     |   v    |   v    |  v   |   \-     |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 3   | Link          |   v     |   v    |   v    |  v   |   v      |   v      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 4   | Title         |   v     |   ?    |   ?    |  ?   |   ?      |   ?      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 5   | Preserve Text |   ?     |   v    |   v    |  v\* |   ?      |   ?      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 6   | Text Break    |   v     |   v    |   v    |  v   |   v      |   v      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 7   | Page Break    |   v     |   \-   |   \-   |  \-  |   \-     |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 8   | List          |   v     |   v    |   v    |  v   |   \-     |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 9   | Table         |   v     |   v    |   v    |  ?   |   \-     |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 10  | Image         |   v     |   v    |   v    |  v   |   v      |   v      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 11  | Watermark     |   \-    |   v    |   \-   |  \-  |   \-     |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 12  | Object        |   v     |   v    |   v    |  v   |   v      |   v      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 13  | TOC           |   v     |   \-   |   \-   |  \-  |   \-     |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 14  | Footnote      |   v     |   \-   |   \-   | v\*\*|   v\*\*  |   \-     |
++-----+---------------+---------+--------+--------+------+----------+----------+
+| 15  | CheckBox      |   v     |   v    |   v    |  v   |   ?      |   ?      |
++-----+---------------+---------+--------+--------+------+----------+----------+
+
+Legend:
+
+- ``v`` Available
+- ``v*`` Available only when inside header/footer
+- ``v**`` Available only when inside section
+- ``-`` Not available
+- ``?`` Should be available
+
 Texts
 -----
 
-Text can be added by using ``addText`` and ``createTextRun`` method.
+Text can be added by using ``addText`` and ``addTextRun`` method.
 ``addText`` is used for creating simple paragraphs that only contain
-texts with the same style. ``createTextRun`` is used for creating
+texts with the same style. ``addTextRun`` is used for creating
 complex paragraphs that contain text with different style (some bold,
 other italics, etc) or other elements, e.g. images or links. The
 syntaxes are as follow:
 
 .. code-block:: php
 
     $section->addText($text, [$fontStyle], [$paragraphStyle]);
-    $textrun = $section->createTextRun([$paragraphStyle]);
+    $textrun = $section->addTextRun([$paragraphStyle]);
 
 Text styles
 ~~~~~~~~~~~
@@ -34,7 +79,7 @@ Inline style examples:
     $paragraphStyle = array('align' => 'both');
     $section->addText('I am simple paragraph', $fontStyle, $paragraphStyle);
 
-    $textrun = $section->createTextRun();
+    $textrun = $section->addTextRun();
     $textrun->addText('I am bold', array('bold' => true));
     $textrun->addText('I am italic', array('italic' => true));
     $textrun->addText('I am colored, array('color' => 'AACC00'));
@@ -255,7 +300,7 @@ Examples:
 
 .. code-block:: php
 
-    $section = $phpWord->createSection();
+    $section = $phpWord->addSection();
     $section->addImage(
         'mars.jpg',
         array(
@@ -266,9 +311,9 @@ Examples:
             'wrappingStyle' => 'behind'
         )
     );
-    $footer = $section->createFooter();
+    $footer = $section->addFooter();
     $footer->addImage('http://example.com/image.php');
-    $textrun = $section->createTextRun();
+    $textrun = $section->addTextRun();
     $textrun->addImage('http://php.net/logo.jpg');
 
 Image styles
@@ -293,8 +338,8 @@ header reference. After creating a header, you can use the
 
 .. code-block:: php
 
-    $section = $phpWord->createSection();
-    $header = $section->createHeader();
+    $section = $phpWord->addSection();
+    $header = $section->addHeader();
     $header->addWatermark('resources/_earth.jpg', array('marginTop' => 200, 'marginLeft' => 55));
 
 Objects
@@ -342,9 +387,9 @@ On textrun:
 
 .. code-block:: php
 
-    $textrun = $section->createTextRun();
+    $textrun = $section->addTextRun();
     $textrun->addText('Lead text.');
-    $footnote = $textrun->createFootnote();
+    $footnote = $textrun->addFootnote();
     $footnote->addText('Footnote text can have ');
     $footnote->addLink('http://test.com', 'links');
     $footnote->addText('.');
@@ -357,7 +402,7 @@ On text:
 .. code-block:: php
 
     $section->addText('Lead text.');
-    $footnote = $section->createFootnote();
+    $footnote = $section->addFootnote();
     $footnote->addText('Footnote text.');
 
 The footnote reference number will be displayed with decimal number starting

docs/general.rst

@@ -19,7 +19,7 @@ folder <https://github.com/PHPOffice/PHPWord/tree/master/samples/>`__.
 
     // Every element you want to append to the word document is placed in a section.
     // To create a basic section:
-    $section = $phpWord->createSection();
+    $section = $phpWord->addSection();
 
     // After creating a section, you can append elements:
     $section->addText('Hello world!');
@@ -136,7 +136,7 @@ points to twips.
         'spaceAfter' => \PhpOffice\PhpWord\Shared\Font::pointSizeToTwips(6))
     );
 
-    $section = $phpWord->createSection();
+    $section = $phpWord->addSection();
     $sectionStyle = $section->getSettings();
     // half inch left margin
     $sectionStyle->setMarginLeft(\PhpOffice\PhpWord\Shared\Font::inchSizeToTwips(.5));

samples/Sample_01_SimpleText.php

@@ -9,7 +9,7 @@
 $phpWord->addTitleStyle(1, array('bold' => true), array('spaceAfter' => 240));
 
 // New portrait section
-$section = $phpWord->createSection();
+$section = $phpWord->addSection();
 
 // Simple text
 $section->addTitle('Welcome to PhpWord', 1);

samples/Sample_02_TabStops.php

@@ -25,7 +25,7 @@
 ));
 
 // New portrait section
-$section = $phpWord->createSection();
+$section = $phpWord->addSection();
 
 // Add listitem elements
 $section->addText("Multiple Tabs:\tOne\tTwo\tThree", NULL, 'multipleTab');

samples/Sample_03_Sections.php

@@ -6,24 +6,24 @@
 $phpWord = new \PhpOffice\PhpWord\PhpWord();
 
 // New portrait section
-$section = $phpWord->createSection(array('borderColor' => '00FF00', 'borderSize' => 12));
+$section = $phpWord->addSection(array('borderColor' => '00FF00', 'borderSize' => 12));
 $section->addText('I am placed on a default section.');
 
 // New landscape section
-$section = $phpWord->createSection(array('orientation' => 'landscape'));
+$section = $phpWord->addSection(array('orientation' => 'landscape'));
 $section->addText('I am placed on a landscape section. Every page starting from this section will be landscape style.');
 $section->addPageBreak();
 $section->addPageBreak();
 
 // New portrait section
-$section = $phpWord->createSection(array('marginLeft' => 600, 'marginRight' => 600, 'marginTop' => 600, 'marginBottom' => 600));
+$section = $phpWord->addSection(array('marginLeft' => 600, 'marginRight' => 600, 'marginTop' => 600, 'marginBottom' => 600));
 $section->addText('This section uses other margins.');
 
 // New portrait section with Header & Footer
-$section = $phpWord->createSection(array('marginLeft' => 200, 'marginRight' => 200, 'marginTop' => 200, 'marginBottom' => 200, 'headerHeight' => 50, 'footerHeight' => 50,));
+$section = $phpWord->addSection(array('marginLeft' => 200, 'marginRight' => 200, 'marginTop' => 200, 'marginBottom' => 200, 'headerHeight' => 50, 'footerHeight' => 50,));
 $section->addText('This section and we play with header/footer height.');
-$section->createHeader()->addText('Header');
-$section->createFooter()->addText('Footer');
+$section->addHeader()->addText('Header');
+$section->addFooter()->addText('Footer');
 
 // Save file
 $name = basename(__FILE__, '.php');

samples/Sample_04_Textrun.php

@@ -12,10 +12,10 @@
 $phpWord->addLinkStyle('NLink', array('color'=>'0000FF', 'underline' => \PhpOffice\PhpWord\Style\Font::UNDERLINE_SINGLE));
 
 // New portrait section
-$section = $phpWord->createSection();
+$section = $phpWord->addSection();
 
 // Add text run
-$textrun = $section->createTextRun('pStyle');
+$textrun = $section->addTextRun('pStyle');
 
 $textrun->addText('Each textrun can contain native text, link elements or an image.');
 $textrun->addText(' No break is placed after adding an element.', 'BoldText');
@@ -28,7 +28,9 @@
 $textrun->addText(' Sample Link: ');
 $textrun->addLink('http://www.google.com', null, 'NLink');
 $textrun->addText(' Sample Image: ');
-$textrun->addImage('resources/_earth.jpg', array('width'=>18, 'height'=>18));
+$textrun->addImage('resources/_earth.jpg', array('width' => 18, 'height' => 18));
+$textrun->addText(' Sample Object: ');
+$textrun->addObject('resources/_sheet.xls');
 $textrun->addText(' Here is some more text. ');
 
 // Save file

samples/Sample_05_Multicolumn.php

@@ -10,29 +10,29 @@
     'Suspendisse congue congue leo sed pellentesque.';
 
 // Normal
-$section = $phpWord->createSection();
+$section = $phpWord->addSection();
 $section->addText('Normal paragraph. ' . $filler);
 
 // Two columns
-$section = $phpWord->createSection(array(
+$section = $phpWord->addSection(array(
     'colsNum' => 2,
     'colsSpace' => 1440,
     'breakType' => 'continuous'));
 $section->addText('Three columns, one inch (1440 twips) spacing. ' . $filler);
 
 // Normal
-$section = $phpWord->createSection(array('breakType' => 'continuous'));
+$section = $phpWord->addSection(array('breakType' => 'continuous'));
 $section->addText('Normal paragraph again. ' . $filler);
 
 // Three columns
-$section = $phpWord->createSection(array(
+$section = $phpWord->addSection(array(
     'colsNum' => 3,
     'colsSpace' => 720,
     'breakType' => 'continuous'));
 $section->addText('Three columns, half inch (720 twips) spacing. ' . $filler);
 
 // Normal
-$section = $phpWord->createSection(array('breakType' => 'continuous'));
+$section = $phpWord->addSection(array('breakType' => 'continuous'));
 $section->addText('Normal paragraph again.');
 
 // Save file