25414441731

Committed 06 May 2026 03:12AM UTC coverage: 94.696% (-2.1%) from 96.757%

Build # 25414441731

Build Type

Pull #2874

github

Committed by

web-flow

Commit Message

Merge 3fa85d6e3 into 0ab0b4940

Pull Request Pull Request #2874: Addresses issue #12

Coverage Stats

135 of 420 new or added lines in 30 files covered. (32.14%)

1 existing line in 1 file now uncovered.

12588 of 13293 relevant lines covered (94.7%)

34.84 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

99.0

/src/PhpWord/Element/AbstractContainer.php

<?php

/**
 * This file is part of PHPWord - A pure PHP library for reading and writing
 * word processing documents.
 *
 * PHPWord is free software distributed under the terms of the GNU Lesser
 * General Public License version 3 as published by the Free Software Foundation.
 *
 * For the full copyright and license information, please read the LICENSE
 * file that was distributed with this source code. For the full list of
 * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
 *
 * @see         https://github.com/PHPOffice/PHPWord
 *
 * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
 */

namespace PhpOffice\PhpWord\Element;

use BadMethodCallException;
use PhpOffice\Math\Math;
use ReflectionClass;

/**
 * Container abstract class.
 *
 * @method Text addText(string $text, mixed $fStyle = null, mixed $pStyle = null)
 * @method TextRun addTextRun(mixed $pStyle = null)
 * @method Bookmark addBookmark(string $name)
 * @method Link addLink(string $target, string $text = null, mixed $fStyle = null, mixed $pStyle = null, boolean $internal = false)
 * @method PreserveText addPreserveText(string $text, mixed $fStyle = null, mixed $pStyle = null)
 * @method void addTextBreak(int $count = 1, mixed $fStyle = null, mixed $pStyle = null)
 * @method ListItem addListItem(string $txt, int $depth = 0, mixed $font = null, mixed $list = null, mixed $para = null)
 * @method ListItemRun addListItemRun(int $depth = 0, mixed $listStyle = null, mixed $pStyle = null)
 * @method Footnote addFootnote(mixed $pStyle = null)
 * @method Endnote addEndnote(mixed $pStyle = null)
 * @method CheckBox addCheckBox(string $name, $text, mixed $fStyle = null, mixed $pStyle = null)
 * @method Title addTitle(mixed $text, int $depth = 1, int $pageNumber = null, string $style = '')
 * @method TOC addTOC(mixed $fontStyle = null, mixed $tocStyle = null, int $minDepth = 1, int $maxDepth = 9, string $switchString = '\h \z \u', string $tField = '')
 * @method TOF addTOF(string $captionLabel = 'Figure', mixed $tofStyle = null, mixed $fontStyle = null, mixed $paragraphStyle = null)
 * @method PageBreak addPageBreak()
 * @method Table addTable(mixed $style = null)
 * @method Image addImage(string $source, mixed $style = null, string $altText = null, bool $isWatermark = false, $name = null)
 * @method OLEObject addOLEObject(string $source, mixed $style = null)
 * @method TextBox addTextBox(mixed $style = null)
 * @method Field addField(string $type = null, array $properties = array(), array $options = array(), mixed $text = null)
 * @method Line addLine(mixed $lineStyle = null)
 * @method Shape addShape(string $type, mixed $style = null)
 * @method Chart addChart(string $type, array $categories, array $values, array $style = null, $seriesName = null)
 * @method FormField addFormField(string $type, mixed $fStyle = null, mixed $pStyle = null)
 * @method SDT addSDT(string $type)
 * @method Formula addFormula(Math $math)
 * @method Ruby addRuby(TextRun $baseText, TextRun $rubyText, \PhpOffice\PhpWord\ComplexType\RubyProperties $properties)
 * @method \PhpOffice\PhpWord\Element\OLEObject addObject(string $source, mixed $style = null) deprecated, use addOLEObject instead
 *
 * @since 0.10.0
 */
abstract class AbstractContainer extends AbstractElement
{
    /**
     * Elements collection.
     *
     * @var AbstractElement[]
     */
    protected $elements = [];

    /**
     * Container type Section|Header|Footer|Footnote|Endnote|Cell|TextRun|TextBox|ListItemRun|TrackChange.
     *
     * @var string
     */
    protected $container;

    /**
     * Magic method to catch all 'addElement' variation.
     *
     * This removes addText, addTextRun, etc. When adding new element, we have to
     * add the model in the class docblock with `@method`.
     *
     * Warning: This makes capitalization matters, e.g. addCheckbox or addcheckbox won't work.
     *
     * @param mixed $function
     * @param mixed $args
     *
     * @return AbstractElement
     */
    public function __call($function, $args)
    {
        $elements = [
            'Text', 'TextRun', 'Bookmark', 'Link', 'PreserveText', 'TextBreak',
            'ListItem', 'ListItemRun', 'Table', 'Image', 'Object', 'OLEObject',
            'Footnote', 'Endnote', 'CheckBox', 'TextBox', 'Field',
            'Line', 'Shape', 'Title', 'TOC', 'TOF', 'PageBreak',
            'Chart', 'FormField', 'SDT', 'Comment',
            'Formula', 'Caption', 'Ruby',
        ];
        $functions = [];
        foreach ($elements as $element) {
            $functions['add' . strtolower($element)] = $element == 'Object' ? 'OLEObject' : $element;
        }

        // Run valid `add` command
        $function = strtolower($function);
        if (isset($functions[$function])) {
            $element = $functions[$function];

            // Special case for TextBreak
            // @todo Remove the `$count` parameter in 1.0.0 to make this element similiar to other elements?
            if ($element == 'TextBreak') {
                [$count, $fontStyle, $paragraphStyle] = array_pad($args, 3, null);
                if ($count === null) {
                    $count = 1;
                }
                for ($i = 1; $i <= $count; ++$i) {
                    $this->addElement($element, $fontStyle, $paragraphStyle);
                }
            } else {
                // All other elements
                array_unshift($args, $element); // Prepend element name to the beginning of args array

                return call_user_func_array([$this, 'addElement'], $args);
            }
        }

        return null;
    }

    /**
     * Add element.
     *
     * Each element has different number of parameters passed
     *
     * @param string $elementName
     *
     * @return AbstractElement
     */
    protected function addElement($elementName)
    {
        $elementClass = __NAMESPACE__ . '\\' . $elementName;
        $this->checkValidity($elementName);

        // Get arguments
        $args = func_get_args();
        $withoutP = in_array($this->container, ['TextRun', 'Footnote', 'Endnote', 'ListItemRun', 'Field']);
        if ($withoutP && ($elementName == 'Text' || $elementName == 'PreserveText')) {
            $args[3] = null; // Remove paragraph style for texts in textrun
        }
        if ($withoutP && ($elementName == 'Caption')) {
            $args[4] = null; // Remove paragraph style for captions in textrun
        }

        // Create element using reflection
        $reflection = new ReflectionClass($elementClass);
        $elementArgs = $args;
        array_shift($elementArgs); // Shift the $elementName off the beginning of array

        /** @var AbstractElement $element Type hint */
        $element = $reflection->newInstanceArgs($elementArgs);

        // Set parent container
        $element->setParentContainer($this);
        $element->setElementIndex($this->countElements() + 1);
        $element->setElementId();

        $this->elements[] = $element;

        return $element;
    }

    /**
     * Get all elements.
     *
     * @return AbstractElement[]
     */
    public function getElements()
    {
        return $this->elements;
    }

    /**
     * Returns the element at the requested position.
     *
     * @param int $index
     *
     * @return null|AbstractElement
     */
    public function getElement($index)
    {
        if (array_key_exists($index, $this->elements)) {
            return $this->elements[$index];
        }

        return null;
    }

    /**
     * Removes the element at requested index.
     *
     * @param AbstractElement|int $toRemove
     */
    public function removeElement($toRemove): void
    {
        if (is_int($toRemove) && array_key_exists($toRemove, $this->elements)) {
            unset($this->elements[$toRemove]);
        } elseif ($toRemove instanceof AbstractElement) {
            foreach ($this->elements as $key => $element) {
                if ($element->getElementId() === $toRemove->getElementId()) {
                    unset($this->elements[$key]);

                    return;
                }
            }
        }
    }

    /**
     * Count elements.
     *
     * @return int
     */
    public function countElements()
    {
        return count($this->elements);
    }

    /**
     * Check if a method is allowed for the current container.
     *
     * @param string $method
     *
     * @return bool
     */
    private function checkValidity($method)
    {
        $generalContainers = [
            'Section', 'Header', 'Footer', 'Footnote', 'Endnote', 'Cell', 'TextRun', 'TextBox', 'ListItemRun', 'TrackChange',
        ];

        $validContainers = [
            'Text' => $generalContainers,
            'Bookmark' => $generalContainers,
            'Link' => $generalContainers,
            'TextBreak' => $generalContainers,
            'Image' => $generalContainers,
            'Caption' => $generalContainers,
            'OLEObject' => $generalContainers,
            'Field' => $generalContainers,
            'Line' => $generalContainers,
            'Shape' => $generalContainers,
            'FormField' => $generalContainers,
            'SDT' => $generalContainers,
            'TrackChange' => $generalContainers,
            'TextRun' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox', 'TrackChange', 'ListItemRun'],
            'ListItem' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox'],
            'ListItemRun' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox'],
            'Table' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox'],
            'CheckBox' => ['Section', 'Header', 'Footer', 'Cell', 'TextRun'],
            'TextBox' => ['Section', 'Header', 'Footer', 'Cell'],
            'Footnote' => ['Section', 'TextRun', 'Cell', 'ListItemRun'],
            'Endnote' => ['Section', 'TextRun', 'Cell'],
            'PreserveText' => ['Section', 'Header', 'Footer', 'Cell'],
            'Title' => ['Section', 'Cell', 'Header'],
            'TOC' => ['Section'],
            'TOF' => ['Section'],
            'PageBreak' => ['Section'],
            'Chart' => ['Section', 'Cell'],
        ];

        // Special condition, e.g. preservetext can only exists in cell when
        // the cell is located in header or footer
        $validSubcontainers = [
            'PreserveText' => [['Cell'], ['Header', 'Footer', 'Section']],
            'Footnote' => [['Cell', 'TextRun'], ['Section']],
            'Endnote' => [['Cell', 'TextRun'], ['Section']],
        ];

        // Check if a method is valid for current container
        if (isset($validContainers[$method])) {
            if (!in_array($this->container, $validContainers[$method])) {
                throw new BadMethodCallException("Cannot add {$method} in {$this->container}.");
            }
        }

        // Check if a method is valid for current container, located in other container
        if (isset($validSubcontainers[$method])) {
            $rules = $validSubcontainers[$method];
            $containers = $rules[0];
            $allowedDocParts = $rules[1];
            foreach ($containers as $container) {
                if ($this->container == $container && !in_array($this->getDocPart(), $allowedDocParts)) {
                    throw new BadMethodCallException("Cannot add {$method} in {$this->container}.");
                }
            }
        }

        return true;
    }
}

1	<?php
2
3	/**
4	* This file is part of PHPWord - A pure PHP library for reading and writing
5	* word processing documents.
6	*
7	* PHPWord is free software distributed under the terms of the GNU Lesser
8	* General Public License version 3 as published by the Free Software Foundation.
9	*
10	* For the full copyright and license information, please read the LICENSE
11	* file that was distributed with this source code. For the full list of
12	* contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
13	*
14	* @see https://github.com/PHPOffice/PHPWord
15	*
16	* @license http://www.gnu.org/licenses/lgpl.txt LGPL version 3
17	*/
18
19	namespace PhpOffice\PhpWord\Element;
20
21	use BadMethodCallException;
22	use PhpOffice\Math\Math;
23	use ReflectionClass;
24
25	/**
26	* Container abstract class.
27	*
28	* @method Text addText(string $text, mixed $fStyle = null, mixed $pStyle = null)
29	* @method TextRun addTextRun(mixed $pStyle = null)
30	* @method Bookmark addBookmark(string $name)
31	* @method Link addLink(string $target, string $text = null, mixed $fStyle = null, mixed $pStyle = null, boolean $internal = false)
32	* @method PreserveText addPreserveText(string $text, mixed $fStyle = null, mixed $pStyle = null)
33	* @method void addTextBreak(int $count = 1, mixed $fStyle = null, mixed $pStyle = null)
34	* @method ListItem addListItem(string $txt, int $depth = 0, mixed $font = null, mixed $list = null, mixed $para = null)
35	* @method ListItemRun addListItemRun(int $depth = 0, mixed $listStyle = null, mixed $pStyle = null)
36	* @method Footnote addFootnote(mixed $pStyle = null)
37	* @method Endnote addEndnote(mixed $pStyle = null)
38	* @method CheckBox addCheckBox(string $name, $text, mixed $fStyle = null, mixed $pStyle = null)
39	* @method Title addTitle(mixed $text, int $depth = 1, int $pageNumber = null, string $style = '')
40	* @method TOC addTOC(mixed $fontStyle = null, mixed $tocStyle = null, int $minDepth = 1, int $maxDepth = 9, string $switchString = '\h \z \u', string $tField = '')
41	* @method TOF addTOF(string $captionLabel = 'Figure', mixed $tofStyle = null, mixed $fontStyle = null, mixed $paragraphStyle = null)
42	* @method PageBreak addPageBreak()
43	* @method Table addTable(mixed $style = null)
44	* @method Image addImage(string $source, mixed $style = null, string $altText = null, bool $isWatermark = false, $name = null)
45	* @method OLEObject addOLEObject(string $source, mixed $style = null)
46	* @method TextBox addTextBox(mixed $style = null)
47	* @method Field addField(string $type = null, array $properties = array(), array $options = array(), mixed $text = null)
48	* @method Line addLine(mixed $lineStyle = null)
49	* @method Shape addShape(string $type, mixed $style = null)
50	* @method Chart addChart(string $type, array $categories, array $values, array $style = null, $seriesName = null)
51	* @method FormField addFormField(string $type, mixed $fStyle = null, mixed $pStyle = null)
52	* @method SDT addSDT(string $type)
53	* @method Formula addFormula(Math $math)
54	* @method Ruby addRuby(TextRun $baseText, TextRun $rubyText, \PhpOffice\PhpWord\ComplexType\RubyProperties $properties)
55	* @method \PhpOffice\PhpWord\Element\OLEObject addObject(string $source, mixed $style = null) deprecated, use addOLEObject instead
56	*
57	* @since 0.10.0
58	*/
59	abstract class AbstractContainer extends AbstractElement
60	{
61	/**
62	* Elements collection.
63	*
64	* @var AbstractElement[]
65	*/
66	protected $elements = [];
67
68	/**
69	* Container type Section\|Header\|Footer\|Footnote\|Endnote\|Cell\|TextRun\|TextBox\|ListItemRun\|TrackChange.
70	*
71	* @var string
72	*/
73	protected $container;
74
75	/**
76	* Magic method to catch all 'addElement' variation.
77	*
78	* This removes addText, addTextRun, etc. When adding new element, we have to
79	* add the model in the class docblock with `@method`.
80	*
81	* Warning: This makes capitalization matters, e.g. addCheckbox or addcheckbox won't work.
82	*
83	* @param mixed $function
84	* @param mixed $args
85	*
86	* @return AbstractElement
87	*/
88	public function __call($function, $args)
89	{
90	$elements = [	379✔
91	'Text', 'TextRun', 'Bookmark', 'Link', 'PreserveText', 'TextBreak',	379✔
92	'ListItem', 'ListItemRun', 'Table', 'Image', 'Object', 'OLEObject',	379✔
93	'Footnote', 'Endnote', 'CheckBox', 'TextBox', 'Field',	379✔
94	'Line', 'Shape', 'Title', 'TOC', 'TOF', 'PageBreak',	379✔
95	'Chart', 'FormField', 'SDT', 'Comment',	379✔
96	'Formula', 'Caption', 'Ruby',	379✔
97	];	379✔
98	$functions = [];	379✔
99	foreach ($elements as $element) {	379✔
100	$functions['add' . strtolower($element)] = $element == 'Object' ? 'OLEObject' : $element;	379✔
101	}
102
103	// Run valid `add` command
104	$function = strtolower($function);	379✔
105	if (isset($functions[$function])) {	379✔
106	$element = $functions[$function];	379✔
107
108	// Special case for TextBreak
109	// @todo Remove the `$count` parameter in 1.0.0 to make this element similiar to other elements?
110	if ($element == 'TextBreak') {	379✔
111	[$count, $fontStyle, $paragraphStyle] = array_pad($args, 3, null);	31✔
112	if ($count === null) {	31✔
113	$count = 1;	21✔
114	}
115	for ($i = 1; $i <= $count; ++$i) {	31✔
116	$this->addElement($element, $fontStyle, $paragraphStyle);	31✔
117	}
118	} else {
119	// All other elements
120	array_unshift($args, $element); // Prepend element name to the beginning of args array	371✔
121
122	return call_user_func_array([$this, 'addElement'], $args);	371✔
123	}
124	}
125
126	return null;	31✔
127	}
128
129	/**
130	* Add element.
131	*
132	* Each element has different number of parameters passed
133	*
134	* @param string $elementName
135	*
136	* @return AbstractElement
137	*/
138	protected function addElement($elementName)
139	{
140	$elementClass = __NAMESPACE__ . '\\' . $elementName;	379✔
141	$this->checkValidity($elementName);	379✔
142
143	// Get arguments
144	$args = func_get_args();	377✔
145	$withoutP = in_array($this->container, ['TextRun', 'Footnote', 'Endnote', 'ListItemRun', 'Field']);	377✔
146	if ($withoutP && ($elementName == 'Text' \|\| $elementName == 'PreserveText')) {	377✔
147	$args[3] = null; // Remove paragraph style for texts in textrun	118✔
148	}
149	if ($withoutP && ($elementName == 'Caption')) {	377✔
NEW 150	$args[4] = null; // Remove paragraph style for captions in textrun	×
151	}
152
153	// Create element using reflection
154	$reflection = new ReflectionClass($elementClass);	377✔
155	$elementArgs = $args;	377✔
156	array_shift($elementArgs); // Shift the $elementName off the beginning of array	377✔
157
158	/** @var AbstractElement $element Type hint */
159	$element = $reflection->newInstanceArgs($elementArgs);	377✔
160
161	// Set parent container
162	$element->setParentContainer($this);	376✔
163	$element->setElementIndex($this->countElements() + 1);	376✔
164	$element->setElementId();	376✔
165
166	$this->elements[] = $element;	376✔
167
168	return $element;	376✔
169	}
170
171	/**
172	* Get all elements.
173	*
174	* @return AbstractElement[]
175	*/
176	public function getElements()
177	{
178	return $this->elements;	387✔
179	}
180
181	/**
182	* Returns the element at the requested position.
183	*
184	* @param int $index
185	*
186	* @return null\|AbstractElement
187	*/
188	public function getElement($index)
189	{
190	if (array_key_exists($index, $this->elements)) {	16✔
191	return $this->elements[$index];	16✔
192	}
193
194	return null;	1✔
195	}
196
197	/**
198	* Removes the element at requested index.
199	*
200	* @param AbstractElement\|int $toRemove
201	*/
202	public function removeElement($toRemove): void
203	{
204	if (is_int($toRemove) && array_key_exists($toRemove, $this->elements)) {	2✔
205	unset($this->elements[$toRemove]);	1✔
206	} elseif ($toRemove instanceof AbstractElement) {	1✔
207	foreach ($this->elements as $key => $element) {	1✔
208	if ($element->getElementId() === $toRemove->getElementId()) {	1✔
209	unset($this->elements[$key]);	1✔
210
211	return;	1✔
212	}
213	}
214	}
215	}
216
217	/**
218	* Count elements.
219	*
220	* @return int
221	*/
222	public function countElements()
223	{
224	return count($this->elements);	376✔
225	}
226
227	/**
228	* Check if a method is allowed for the current container.
229	*
230	* @param string $method
231	*
232	* @return bool
233	*/
234	private function checkValidity($method)
235	{
236	$generalContainers = [	379✔
237	'Section', 'Header', 'Footer', 'Footnote', 'Endnote', 'Cell', 'TextRun', 'TextBox', 'ListItemRun', 'TrackChange',	379✔
238	];	379✔
239
240	$validContainers = [	379✔
241	'Text' => $generalContainers,	379✔
242	'Bookmark' => $generalContainers,	379✔
243	'Link' => $generalContainers,	379✔
244	'TextBreak' => $generalContainers,	379✔
245	'Image' => $generalContainers,	379✔
246	'Caption' => $generalContainers,	379✔
247	'OLEObject' => $generalContainers,	379✔
248	'Field' => $generalContainers,	379✔
249	'Line' => $generalContainers,	379✔
250	'Shape' => $generalContainers,	379✔
251	'FormField' => $generalContainers,	379✔
252	'SDT' => $generalContainers,	379✔
253	'TrackChange' => $generalContainers,	379✔
254	'TextRun' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox', 'TrackChange', 'ListItemRun'],	379✔
255	'ListItem' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox'],	379✔
256	'ListItemRun' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox'],	379✔
257	'Table' => ['Section', 'Header', 'Footer', 'Cell', 'TextBox'],	379✔
258	'CheckBox' => ['Section', 'Header', 'Footer', 'Cell', 'TextRun'],	379✔
259	'TextBox' => ['Section', 'Header', 'Footer', 'Cell'],	379✔
260	'Footnote' => ['Section', 'TextRun', 'Cell', 'ListItemRun'],	379✔
261	'Endnote' => ['Section', 'TextRun', 'Cell'],	379✔
262	'PreserveText' => ['Section', 'Header', 'Footer', 'Cell'],	379✔
263	'Title' => ['Section', 'Cell', 'Header'],	379✔
264	'TOC' => ['Section'],	379✔
265	'TOF' => ['Section'],	379✔
266	'PageBreak' => ['Section'],	379✔
267	'Chart' => ['Section', 'Cell'],	379✔
268	];	379✔
269
270	// Special condition, e.g. preservetext can only exists in cell when
271	// the cell is located in header or footer
272	$validSubcontainers = [	379✔
273	'PreserveText' => [['Cell'], ['Header', 'Footer', 'Section']],	379✔
274	'Footnote' => [['Cell', 'TextRun'], ['Section']],	379✔
275	'Endnote' => [['Cell', 'TextRun'], ['Section']],	379✔
276	];	379✔
277
278	// Check if a method is valid for current container
279	if (isset($validContainers[$method])) {	379✔
280	if (!in_array($this->container, $validContainers[$method])) {	374✔
281	throw new BadMethodCallException("Cannot add {$method} in {$this->container}.");	1✔
282	}
283	}
284
285	// Check if a method is valid for current container, located in other container
286	if (isset($validSubcontainers[$method])) {	378✔
287	$rules = $validSubcontainers[$method];	19✔
288	$containers = $rules[0];	19✔
289	$allowedDocParts = $rules[1];	19✔
290	foreach ($containers as $container) {	19✔
291	if ($this->container == $container && !in_array($this->getDocPart(), $allowedDocParts)) {	19✔
292	throw new BadMethodCallException("Cannot add {$method} in {$this->container}.");	1✔
293	}
294	}
295	}
296
297	return true;	377✔
298	}
299	}

PHPOffice / PHPWord / 25414441731

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous