From c8da05d0a78e674df51a36d948f181124be62963 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Fri, 6 Feb 2015 17:17:41 +0100 Subject: [PATCH 01/57] lib: Remove NodeInterface I'll create an iterator for nodes and drop that every node is a SplDoublyLinkedList. refs #6630 --- library/Icinga/Data/Tree/NodeInterface.php | 25 ---------------------- 1 file changed, 25 deletions(-) delete mode 100644 library/Icinga/Data/Tree/NodeInterface.php diff --git a/library/Icinga/Data/Tree/NodeInterface.php b/library/Icinga/Data/Tree/NodeInterface.php deleted file mode 100644 index faec9e764..000000000 --- a/library/Icinga/Data/Tree/NodeInterface.php +++ /dev/null @@ -1,25 +0,0 @@ - Date: Fri, 6 Feb 2015 17:20:23 +0100 Subject: [PATCH 02/57] lib/tree: Save child nodes into an array instead of using SplDoublyLinkedList refs #6630 --- library/Icinga/Data/Tree/Node.php | 91 ++++++++++++++++++++++--------- 1 file changed, 66 insertions(+), 25 deletions(-) diff --git a/library/Icinga/Data/Tree/Node.php b/library/Icinga/Data/Tree/Node.php index 9402f6265..ad1db9c36 100644 --- a/library/Icinga/Data/Tree/Node.php +++ b/library/Icinga/Data/Tree/Node.php @@ -3,10 +3,18 @@ namespace Icinga\Data\Tree; -use SplDoublyLinkedList; +use Identifiable; +use IteratorAggregate; -class Node extends SplDoublyLinkedList implements NodeInterface +class Node implements Identifiable, IteratorAggregate { + /** + * The node's ID + * + * @type mixed + */ + protected $id; + /** * The node's value * @@ -15,13 +23,45 @@ class Node extends SplDoublyLinkedList implements NodeInterface protected $value; /** - * Create a new node + * The node's children * - * @param mixed $value The node's value + * @type array */ - public function __construct($value = null) + protected $children = array(); + + /** + * Set the node's ID + * + * @param mixed $id ID of the node + * + * @return $this + */ + public function setId($id) + { + $this->id = $id; + return $this; + } + + /** + * (non-PHPDoc) + * @see Identifiable::getId() For the method documentation. + */ + public function getId() + { + return $this->id; + } + + /** + * Set the node's value + * + * @param mixed $value + * + * @return $this + */ + public function setValue($value) { $this->value = $value; + return $this; } /** @@ -35,44 +75,45 @@ class Node extends SplDoublyLinkedList implements NodeInterface } /** - * Create a new node from the given value and insert the node as the last child of this node + * Append a child node as the last child of this node * - * @param mixed $value The node's value + * @param Node $child The child to append * - * @return NodeInterface The appended node + * @return $this */ - public function appendChild($value) + public function appendChild(Node $child) { - $child = new static($value); - $this->push($child); - return $child; + $this->children[] = $child; + return $this; } + /** - * Whether this node has child nodes + * Get whether the node has children * * @return bool */ public function hasChildren() { - $current = $this->current(); - if ($current === null) { - $current = $this; - } - return ! $current->isEmpty(); + return ! empty($this->children); } /** - * Get the node's child nodes + * Get the node's children * - * @return NodeInterface + * @return array */ public function getChildren() { - $current = $this->current(); - if ($current === null) { - $current = $this; - } - return $current; + return $this->children; + } + + /** + * (non-PHPDoc) + * @see IteratorAggregate::getIterator() For the method documentation. + */ + public function getIterator() + { + return new TreeNodeIterator($this); } } From 828cb8d23a906b6be934f82dac11e64f1b21dfba Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Fri, 6 Feb 2015 17:23:07 +0100 Subject: [PATCH 03/57] lib: Add iterator over a tree node's children refs #6630 --- library/Icinga/Data/Tree/TreeNodeIterator.php | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 library/Icinga/Data/Tree/TreeNodeIterator.php diff --git a/library/Icinga/Data/Tree/TreeNodeIterator.php b/library/Icinga/Data/Tree/TreeNodeIterator.php new file mode 100644 index 000000000..cdcefe8ea --- /dev/null +++ b/library/Icinga/Data/Tree/TreeNodeIterator.php @@ -0,0 +1,93 @@ +children = new ArrayIterator($node->getChildren()); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::current() For the method documentation. + */ + public function current() + { + return $this->children->current(); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::key() For the method documentation. + */ + public function key() + { + return $this->children->key(); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::next() For the method documentation. + */ + public function next() + { + $this->children->next(); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::rewind() For the method documentation. + */ + public function rewind() + { + $this->children->rewind(); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::valid() For the method documentation. + */ + public function valid() + { + return $this->children->valid(); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::hasChildren() For the method documentation. + */ + public function hasChildren() + { + return $this->current()->hasChildren(); + } + + /** + * (non-PHPDoc) + * @see \RecursiveIterator::getChildren() For the method documentation. + */ + public function getChildren() + { + return new static($this->current()); + } +} From 95c937e3fd1c93a58bd21fa45e3b991c419bba4e Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Fri, 6 Feb 2015 17:24:01 +0100 Subject: [PATCH 04/57] lib/doc: Fix code style for doc exceptions --- .../doc/library/Doc/Exception/ChapterNotFoundException.php | 4 +++- modules/doc/library/Doc/Exception/DocEmptyException.php | 4 +++- modules/doc/library/Doc/Exception/DocException.php | 4 +++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/modules/doc/library/Doc/Exception/ChapterNotFoundException.php b/modules/doc/library/Doc/Exception/ChapterNotFoundException.php index a1de9b496..5a5d41936 100644 --- a/modules/doc/library/Doc/Exception/ChapterNotFoundException.php +++ b/modules/doc/library/Doc/Exception/ChapterNotFoundException.php @@ -6,4 +6,6 @@ namespace Icinga\Module\Doc\Exception; /** * Exception thrown if a chapter was not found */ -class ChapterNotFoundException extends DocException {} +class ChapterNotFoundException extends DocException +{ +} diff --git a/modules/doc/library/Doc/Exception/DocEmptyException.php b/modules/doc/library/Doc/Exception/DocEmptyException.php index b4050e3e3..0ce563cf1 100644 --- a/modules/doc/library/Doc/Exception/DocEmptyException.php +++ b/modules/doc/library/Doc/Exception/DocEmptyException.php @@ -6,4 +6,6 @@ namespace Icinga\Module\Doc\Exception; /** * Exception thrown if a documentation directory is empty */ -class DocEmptyException extends DocException {} +class DocEmptyException extends DocException +{ +} diff --git a/modules/doc/library/Doc/Exception/DocException.php b/modules/doc/library/Doc/Exception/DocException.php index 672359591..f749fb7b3 100644 --- a/modules/doc/library/Doc/Exception/DocException.php +++ b/modules/doc/library/Doc/Exception/DocException.php @@ -8,4 +8,6 @@ use RuntimeException; /** * Exception thrown if an error in the documentation module's library occurs */ -class DocException extends RuntimeException {} +class DocException extends RuntimeException +{ +} From 0d63e14baf8184088713c3ce819741d022b45e5b Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Fri, 6 Feb 2015 17:27:14 +0100 Subject: [PATCH 05/57] lib: Rename Node to TreeNode refs #6630 --- library/Icinga/Data/Tree/{Node.php => TreeNode.php} | 6 +++--- library/Icinga/Data/Tree/TreeNodeIterator.php | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) rename library/Icinga/Data/Tree/{Node.php => TreeNode.php} (91%) diff --git a/library/Icinga/Data/Tree/Node.php b/library/Icinga/Data/Tree/TreeNode.php similarity index 91% rename from library/Icinga/Data/Tree/Node.php rename to library/Icinga/Data/Tree/TreeNode.php index ad1db9c36..fcf257e55 100644 --- a/library/Icinga/Data/Tree/Node.php +++ b/library/Icinga/Data/Tree/TreeNode.php @@ -6,7 +6,7 @@ namespace Icinga\Data\Tree; use Identifiable; use IteratorAggregate; -class Node implements Identifiable, IteratorAggregate +class TreeNode implements Identifiable, IteratorAggregate { /** * The node's ID @@ -77,11 +77,11 @@ class Node implements Identifiable, IteratorAggregate /** * Append a child node as the last child of this node * - * @param Node $child The child to append + * @param TreeNode $child The child to append * * @return $this */ - public function appendChild(Node $child) + public function appendChild(TreeNode $child) { $this->children[] = $child; return $this; diff --git a/library/Icinga/Data/Tree/TreeNodeIterator.php b/library/Icinga/Data/Tree/TreeNodeIterator.php index cdcefe8ea..b0b0b0f83 100644 --- a/library/Icinga/Data/Tree/TreeNodeIterator.php +++ b/library/Icinga/Data/Tree/TreeNodeIterator.php @@ -21,9 +21,9 @@ class TreeNodeIterator implements RecursiveIterator /** * Create a new iterator over a tree node's children * - * @param Node $node + * @param TreeNode $node */ - public function __construct(Node $node) + public function __construct(TreeNode $node) { $this->children = new ArrayIterator($node->getChildren()); } From ecfda1a6f5077b4b0494fc3af90bdfd894faf8bf Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Fri, 6 Feb 2015 17:29:04 +0100 Subject: [PATCH 06/57] lib/doc: Rename Section to DocSection and let it extend TreeNode refs #6630 --- .../Doc/{Section.php => DocSection.php} | 85 ++++++++----------- 1 file changed, 36 insertions(+), 49 deletions(-) rename modules/doc/library/Doc/{Section.php => DocSection.php} (50%) diff --git a/modules/doc/library/Doc/Section.php b/modules/doc/library/Doc/DocSection.php similarity index 50% rename from modules/doc/library/Doc/Section.php rename to modules/doc/library/Doc/DocSection.php index 32f836c33..237b487fc 100644 --- a/modules/doc/library/Doc/Section.php +++ b/modules/doc/library/Doc/DocSection.php @@ -3,81 +3,52 @@ namespace Icinga\Module\Doc; -use Icinga\Data\Identifiable; +use Icinga\Data\Tree\TreeNode; /** * A section of a documentation */ -class Section implements Identifiable +class DocSection extends TreeNode { - /** - * The ID of the section - * - * @var string - */ - protected $id; - /** * The title of the section * - * @var string + * @type string */ protected $title; /** * The header level * - * @var int + * @type int */ protected $level; /** * Whether to instruct search engines to not index the link to the section * - * @var bool + * @type bool */ protected $noFollow; - /** - * The ID of the chapter the section is part of - * - * @var string - */ - protected $chapterId; - /** * The content of the section * - * @var array + * @type array */ protected $content = array(); /** - * Create a new section + * Set the title of the section * - * @param string $id The ID of the section - * @param string $title The title of the section - * @param int $level The header level - * @param bool $noFollow Whether to instruct search engines to not index the link to the section - * @param string $chapterId The ID of the chapter the section is part of - */ - public function __construct($id, $title, $level, $noFollow, $chapterId) - { - $this->id = $id; - $this->title = $title; - $this->level = $level; - $this->noFollow = $noFollow; - $this->chapterId= $chapterId; - } - - /** - * Get the ID of the section + * @param string $title Title of the section * - * @return string + * @return $this */ - public function getId() + public function setTitle($title) { - return $this->id; + $this->title = (string) $title; + return $this; } /** @@ -90,6 +61,19 @@ class Section implements Identifiable return $this->title; } + /** + * Set the header level + * + * @param int $level Header level + * + * @return $this + */ + public function setLevel($level) + { + $this->level = (int) $level; + return $this; + } + /** * Get the header level * @@ -101,23 +85,26 @@ class Section implements Identifiable } /** - * Whether to instruct search engines to not index the link to the section + * Set whether to instruct search engines to not index the link to the section * - * @return bool + * @param bool $noFollow Whether to instruct search engines to not index the link to the section + * + * @return $this */ - public function isNoFollow() + public function setNoFollow($noFollow = true) { - return $this->noFollow; + $this->noFollow = (bool) $noFollow; + return $this; } /** - * The ID of the chapter the section is part of + * Get whether to instruct search engines to not index the link to the section * - * @return string + * @return bool */ - public function getChapterId() + public function getNoFollow() { - return $this->chapterId; + return $this->noFollow; } /** From 3a4c6e45b823f9f8ecee54600c256aa9aad14f73 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Fri, 6 Feb 2015 17:32:51 +0100 Subject: [PATCH 07/57] Fix Fatal error: Interface 'Identifiable' not found refs #6630 --- library/Icinga/Data/Tree/TreeNode.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/Icinga/Data/Tree/TreeNode.php b/library/Icinga/Data/Tree/TreeNode.php index fcf257e55..61008a66d 100644 --- a/library/Icinga/Data/Tree/TreeNode.php +++ b/library/Icinga/Data/Tree/TreeNode.php @@ -3,8 +3,8 @@ namespace Icinga\Data\Tree; -use Identifiable; use IteratorAggregate; +use Icinga\Data\Identifiable; class TreeNode implements Identifiable, IteratorAggregate { From b2ace4e209ab400a0dc8ccb2d102f18d5109260f Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 16:58:40 +0100 Subject: [PATCH 08/57] doc: Remove DocTree class It will be replaced by a class in our lib refs #6630 --- modules/doc/library/Doc/DocTree.php | 79 ----------------------------- 1 file changed, 79 deletions(-) delete mode 100644 modules/doc/library/Doc/DocTree.php diff --git a/modules/doc/library/Doc/DocTree.php b/modules/doc/library/Doc/DocTree.php deleted file mode 100644 index 66b36f1a4..000000000 --- a/modules/doc/library/Doc/DocTree.php +++ /dev/null @@ -1,79 +0,0 @@ -getId(); - if (isset($this->nodes[$rootId])) { - $rootId = uniqid($rootId); -// throw new LogicException( -// sprintf('Can\'t add root node: a root node with the id \'%s\' already exists', $rootId) -// ); - } - $this->nodes[$rootId] = $this->appendChild($root); - } - - /** - * Append a child node to a parent node - * - * @param Identifiable $child - * @param Identifiable $parent - * - * @throws LogicException If the the tree does not contain the parent node - */ - public function addChild(Identifiable $child, Identifiable $parent) - { - $childId = $child->getId(); - $parentId = $parent->getId(); - if (isset($this->nodes[$childId])) { - $childId = uniqid($childId); -// throw new LogicException( -// sprintf('Can\'t add child node: a child node with the id \'%s\' already exists', $childId) -// ); - } - if (! isset($this->nodes[$parentId])) { - throw new LogicException( - sprintf(mt('doc', 'Can\'t add child node: there\'s no parent node having the id \'%s\''), $parentId) - ); - } - $this->nodes[$childId] = $this->nodes[$parentId]->appendChild($child); - } - - /** - * Get a node - * - * @param mixed $id - * - * @return Node|null - */ - public function getNode($id) - { - if (! isset($this->nodes[$id])) { - return null; - } - return $this->nodes[$id]; - } -} From fd38e5b2e12f5b9b8efe7b2a8fed97cd238e68ae Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 16:59:43 +0100 Subject: [PATCH 09/57] lib: Use @inheritdoc in the TreeNodeIterator refs #6630 --- library/Icinga/Data/Tree/TreeNodeIterator.php | 22 +++++++------------ 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/library/Icinga/Data/Tree/TreeNodeIterator.php b/library/Icinga/Data/Tree/TreeNodeIterator.php index b0b0b0f83..753b338f6 100644 --- a/library/Icinga/Data/Tree/TreeNodeIterator.php +++ b/library/Icinga/Data/Tree/TreeNodeIterator.php @@ -29,8 +29,7 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::current() For the method documentation. + * {@inheritdoc} */ public function current() { @@ -38,8 +37,7 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::key() For the method documentation. + * {@inheritdoc} */ public function key() { @@ -47,8 +45,7 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::next() For the method documentation. + * {@inheritdoc} */ public function next() { @@ -56,8 +53,7 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::rewind() For the method documentation. + * {@inheritdoc} */ public function rewind() { @@ -65,8 +61,7 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::valid() For the method documentation. + * {@inheritdoc} */ public function valid() { @@ -74,8 +69,7 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::hasChildren() For the method documentation. + * {@inheritdoc} */ public function hasChildren() { @@ -83,8 +77,8 @@ class TreeNodeIterator implements RecursiveIterator } /** - * (non-PHPDoc) - * @see \RecursiveIterator::getChildren() For the method documentation. + * {@inheritdoc} + * @return TreeNodeIterator */ public function getChildren() { From b18405e99f5e0ee25cbd58272f7c678b8a40057e Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:00:47 +0100 Subject: [PATCH 10/57] lib: Add SimpleTree Simple tree implementation for TreeNodes. refs #6630 --- library/Icinga/Data/Tree/SimpleTree.php | 90 +++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 library/Icinga/Data/Tree/SimpleTree.php diff --git a/library/Icinga/Data/Tree/SimpleTree.php b/library/Icinga/Data/Tree/SimpleTree.php new file mode 100644 index 000000000..46a91135d --- /dev/null +++ b/library/Icinga/Data/Tree/SimpleTree.php @@ -0,0 +1,90 @@ +sentinel = new TreeNode(); + } + + /** + * Add a child node + * + * @param TreeNode $child + * @param TreeNode $parent + * + * @return $this + */ + public function addChild(TreeNode $child, TreeNode $parent = null) + { + if ($parent === null) { + $parent = $this->sentinel; + } elseif (! isset($this->nodes[$parent->getId()])) { + throw new LogicException(sprintf( + 'Can\'t append child node %s to parent node %s: Parent node does not exist', + $child->getId(), + $parent->getId() + )); + } + if (isset($this->nodes[$child->getId()])) { + throw new LogicException(sprintf( + 'Can\'t append child node %s to parent node %s: Child node does already exist', + $child->getId(), + $parent->getId() + )); + } + $this->nodes[$child->getId()] = $child; + $parent->appendChild($child); + return $this; + } + + /** + * Get a node by its ID + * + * @param mixed $id + * + * @return TreeNode|null + */ + public function getNode($id) + { + if (! isset($this->nodes[$id])) { + return null; + } + return $this->nodes[$id]; + } + + /** + * {@inheritdoc} + * @return TreeNodeIterator + */ + public function getIterator() + { + return new TreeNodeIterator($this->sentinel); + } +} From 760819f239273c46138a48f486dfb98335ab470a Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:01:32 +0100 Subject: [PATCH 11/57] lib: Remove TreeNode::getIterator() Its the tree who has the iterator. refs #6630 --- library/Icinga/Data/Tree/TreeNode.php | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/library/Icinga/Data/Tree/TreeNode.php b/library/Icinga/Data/Tree/TreeNode.php index 61008a66d..200b3b9a6 100644 --- a/library/Icinga/Data/Tree/TreeNode.php +++ b/library/Icinga/Data/Tree/TreeNode.php @@ -3,10 +3,9 @@ namespace Icinga\Data\Tree; -use IteratorAggregate; use Icinga\Data\Identifiable; -class TreeNode implements Identifiable, IteratorAggregate +class TreeNode implements Identifiable { /** * The node's ID @@ -107,13 +106,4 @@ class TreeNode implements Identifiable, IteratorAggregate { return $this->children; } - - /** - * (non-PHPDoc) - * @see IteratorAggregate::getIterator() For the method documentation. - */ - public function getIterator() - { - return new TreeNodeIterator($this); - } } From 8ad7a30cd7fe9b313ce91ced450be3cabc835b35 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:02:17 +0100 Subject: [PATCH 12/57] doc: Fix link to resources in the authentication doc --- doc/authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/authentication.md b/doc/authentication.md index 175403061..604c85a2e 100644 --- a/doc/authentication.md +++ b/doc/authentication.md @@ -40,7 +40,7 @@ or LDAP configuration method. Directive | Description ------------------------|------------ **backend** | `ldap` -**resource** | The name of the LDAP resource defined in [resources.ini](resources). +**resource** | The name of the LDAP resource defined in [resources.ini](#resources). **user_class** | LDAP user class. **user_name_attribute** | LDAP attribute which contains the username. @@ -63,7 +63,7 @@ with Icinga Web 2 (e.g. an alias) no matter what the primary user id might actua Directive | Description ------------------------|------------ **backend** | `ad` -**resource** | The name of the LDAP resource defined in [resources.ini](resources). +**resource** | The name of the LDAP resource defined in [resources.ini](#resources). **Example:** @@ -82,7 +82,7 @@ authentication method. Directive | Description ------------------------|------------ **backend** | `db` -**resource** | The name of the database resource defined in [resources.ini](resources). +**resource** | The name of the database resource defined in [resources.ini](#resources). **Example:** From 322c6b582d2dd81cf89e4aed2cc81f275493257b Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:02:37 +0100 Subject: [PATCH 13/57] lib: Prefer @type over @var in the FileExtensionFilterIterator --- library/Icinga/File/FileExtensionFilterIterator.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/Icinga/File/FileExtensionFilterIterator.php b/library/Icinga/File/FileExtensionFilterIterator.php index cb26bb214..fd1d657b4 100644 --- a/library/Icinga/File/FileExtensionFilterIterator.php +++ b/library/Icinga/File/FileExtensionFilterIterator.php @@ -58,7 +58,7 @@ class FileExtensionFilterIterator extends FilterIterator public function accept() { $current = $this->current(); - /* @var $current \SplFileInfo */ + /** @type $current \SplFileInfo */ if (! $current->isFile()) { return false; } From 07cfbe23ef8d184cb885972d3b672619562a995b Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:03:15 +0100 Subject: [PATCH 14/57] doc/lib: Use @inheritdoc in the DocIterator --- modules/doc/library/Doc/DocIterator.php | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/modules/doc/library/Doc/DocIterator.php b/modules/doc/library/Doc/DocIterator.php index c8be8e808..34358a89e 100644 --- a/modules/doc/library/Doc/DocIterator.php +++ b/modules/doc/library/Doc/DocIterator.php @@ -19,7 +19,7 @@ class DocIterator implements Countable, IteratorAggregate /** * Ordered files * - * @var array + * @type array */ protected $fileInfo; @@ -46,8 +46,7 @@ class DocIterator implements Countable, IteratorAggregate } /** - * (non-PHPDoc) - * @see Countable::count() + * {@inheritdoc} */ public function count() { @@ -55,8 +54,7 @@ class DocIterator implements Countable, IteratorAggregate } /** - * (non-PHPDoc) - * @see IteratorAggregate::getIterator() + * {@inheritdoc} */ public function getIterator() { From 9f3b95316569aae7c350e7bb1af48b2d62fe5f38 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:03:58 +0100 Subject: [PATCH 15/57] doc/lib: Support setting the chapter a section belongs to refs #6630 --- modules/doc/library/Doc/DocSection.php | 76 ++++++++++++++++++-------- 1 file changed, 53 insertions(+), 23 deletions(-) diff --git a/modules/doc/library/Doc/DocSection.php b/modules/doc/library/Doc/DocSection.php index 237b487fc..4b97db282 100644 --- a/modules/doc/library/Doc/DocSection.php +++ b/modules/doc/library/Doc/DocSection.php @@ -11,14 +11,21 @@ use Icinga\Data\Tree\TreeNode; class DocSection extends TreeNode { /** - * The title of the section + * Chapter the section belongs to * - * @type string + * @type DocSection */ - protected $title; + protected $chapter; /** - * The header level + * Content of the section + * + * @type array + */ + protected $content = array(); + + /** + * Header level * * @type int */ @@ -32,33 +39,53 @@ class DocSection extends TreeNode protected $noFollow; /** - * The content of the section + * Title of the section * - * @type array + * @type string */ - protected $content = array(); + protected $title; /** - * Set the title of the section + * Set the chapter the section belongs to * - * @param string $title Title of the section + * @param DocSection $section * * @return $this */ - public function setTitle($title) + public function setChapter(DocSection $section) { - $this->title = (string) $title; + $this->chapter = $section; return $this; } /** - * Get the title of the section + * Get the chapter the section belongs to * - * @return string + * @return DocSection */ - public function getTitle() + public function getChapter() { - return $this->title; + return $this->chapter; + } + + /** + * Append content + * + * @param string $content + */ + public function appendContent($content) + { + $this->content[] = $content; + } + + /** + * Get the content of the section + * + * @return array + */ + public function getContent() + { + return $this->content; } /** @@ -108,22 +135,25 @@ class DocSection extends TreeNode } /** - * Append content + * Set the title of the section * - * @param string $content + * @param string $title Title of the section + * + * @return $this */ - public function appendContent($content) + public function setTitle($title) { - $this->content[] = $content; + $this->title = (string) $title; + return $this; } /** - * Get the content of the section + * Get the title of the section * - * @return array + * @return string */ - public function getContent() + public function getTitle() { - return $this->content; + return $this->title; } } From c95838a33d54a44fa53ce1febc7603207cbb476b Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:04:27 +0100 Subject: [PATCH 16/57] doc/lib: Use SimpleTree in the DocParser refs #6630 --- modules/doc/library/Doc/DocParser.php | 31 ++++++++++++++++----------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/modules/doc/library/Doc/DocParser.php b/modules/doc/library/Doc/DocParser.php index 4b6ec7de9..b0384a3d4 100644 --- a/modules/doc/library/Doc/DocParser.php +++ b/modules/doc/library/Doc/DocParser.php @@ -3,7 +3,8 @@ namespace Icinga\Module\Doc; -use SplDoublyLinkedList; +use SplStack; +use Icinga\Data\Tree\SimpleTree; use Icinga\Exception\NotReadableError; use Icinga\Module\Doc\Exception\DocEmptyException; use Icinga\Module\Doc\Exception\DocException; @@ -121,16 +122,15 @@ class DocParser /** * Get the documentation tree * - * @return DocTree + * @return SimpleTree */ public function getDocTree() { - $tree = new DocTree(); - $stack = new SplDoublyLinkedList(); + $tree = new SimpleTree(); + $stack = new SplStack(); foreach ($this->docIterator as $fileInfo) { - /* @var $file \SplFileInfo */ + /** @type $fileInfo \SplFileInfo */ $file = $fileInfo->openFile(); - /* @var $file \SplFileObject */ $lastLine = null; foreach ($file as $line) { $header = $this->extractHeader($line, $lastLine); @@ -142,7 +142,7 @@ class DocParser if ($id === null) { $path = array(); foreach ($stack as $section) { - /* @var $section Section */ + /** @type $section DocSection */ $path[] = $section->getTitle(); } $path[] = $title; @@ -151,13 +151,20 @@ class DocParser } else { $noFollow = false; } + if ($tree->getNode($id) !== null) { + $id = uniqid($id); + } + $section = new DocSection(); + $section + ->setId($id) + ->setTitle($title) + ->setLevel($level) + ->setNoFollow($noFollow); if ($stack->isEmpty()) { - $chapterId = $id; - $section = new Section($id, $title, $level, $noFollow, $chapterId); - $tree->addRoot($section); + $section->setChapter($section); + $tree->addChild($section); } else { - $chapterId = $stack->bottom()->getId(); - $section = new Section($id, $title, $level, $noFollow, $chapterId); + $section->setChapter($stack->bottom()); $tree->addChild($section, $stack->top()); } $stack->push($section); From 377685d8024c8cd6e563a0eb4c79515b6f0b9053 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:04:46 +0100 Subject: [PATCH 17/57] doc/lib: Let DocException extend IcingaException --- modules/doc/library/Doc/Exception/DocException.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/doc/library/Doc/Exception/DocException.php b/modules/doc/library/Doc/Exception/DocException.php index f749fb7b3..c7d895261 100644 --- a/modules/doc/library/Doc/Exception/DocException.php +++ b/modules/doc/library/Doc/Exception/DocException.php @@ -3,11 +3,11 @@ namespace Icinga\Module\Doc\Exception; -use RuntimeException; +use Icinga\Exception\IcingaException; /** * Exception thrown if an error in the documentation module's library occurs */ -class DocException extends RuntimeException +class DocException extends IcingaException { } From 9093795f646d1b2d34f1b1d2cfb0e5de8ad7e95c Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:05:24 +0100 Subject: [PATCH 18/57] doc/lib: Add common used methods to the abstract Renderer refs #6630 --- modules/doc/library/Doc/Renderer.php | 118 +++++++++++++++++++++++++-- 1 file changed, 111 insertions(+), 7 deletions(-) diff --git a/modules/doc/library/Doc/Renderer.php b/modules/doc/library/Doc/Renderer.php index fee74048d..e2329c4dc 100644 --- a/modules/doc/library/Doc/Renderer.php +++ b/modules/doc/library/Doc/Renderer.php @@ -3,8 +3,9 @@ namespace Icinga\Module\Doc; +use Exception; use RecursiveIteratorIterator; -use Zend_View_Helper_Url; +use Icinga\Application\Icinga; use Icinga\Web\View; /** @@ -12,6 +13,99 @@ use Icinga\Web\View; */ abstract class Renderer extends RecursiveIteratorIterator { + /** + * URL to replace links with + * + * @type string + */ + protected $url; + + /** + * Additional URL parameters + * + * @type array + */ + protected $urlParams = array(); + + /** + * View + * + * @type View|null + */ + protected $view; + + /** + * Set the URL to replace links with + * + * @param string $url + * + * @return $this + */ + public function setUrl($url) + { + $this->url = (string) $url; + return $this; + } + + /** + * Get the URL to replace links with + * + * @return string + */ + public function getUrl() + { + return $this->url; + } + + /** + * Set additional URL parameters + * + * @param array $urlParams + * + * @return $this + */ + public function setUrlParams(array $urlParams) + { + $this->urlParams = array_map(array($this, 'encodeUrlParam'), $urlParams); + return $this; + } + + /** + * Get additional URL parameters + * + * @return array + */ + public function getUrlParams() + { + return $this->urlParams; + } + + /** + * Set the view + * + * @param View $view + * + * @return $this + */ + public function setView(View $view) + { + $this->view = $view; + return $this; + } + + /** + * Get the view + * + * @return View + */ + public function getView() + { + if ($this->view === null) { + $this->view = Icinga::app()->getViewRenderer()->view; + } + return $this->view; + } + /** * Encode an anchor identifier * @@ -63,12 +157,22 @@ abstract class Renderer extends RecursiveIteratorIterator /** * Render to HTML * - * Meant to be overwritten by concrete classes. - * - * @param View $view - * @param Zend_View_Helper_Url $zendUrlHelper - * * @return string */ - abstract public function render(View $view, Zend_View_Helper_Url $zendUrlHelper); + abstract public function render(); + + /** + * Render to HTML + * + * @return string + * @see \Icinga\Module\Doc\Renderer::render() For the render method. + */ + public function __toString() + { + try { + return $this->render(); + } catch (Exception $e) { + return $e->getMessage(); + } + } } From 52de56fb65fae85b5944a9165ecfaccc8e80e677 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:06:11 +0100 Subject: [PATCH 19/57] doc/lib: Use TreeNodeIterator in the SectionFilterIterator refs #6630 --- .../doc/library/Doc/SectionFilterIterator.php | 50 ++++++++++++------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/modules/doc/library/Doc/SectionFilterIterator.php b/modules/doc/library/Doc/SectionFilterIterator.php index 0db620120..77171a5c8 100644 --- a/modules/doc/library/Doc/SectionFilterIterator.php +++ b/modules/doc/library/Doc/SectionFilterIterator.php @@ -5,30 +5,34 @@ namespace Icinga\Module\Doc; use Countable; use RecursiveFilterIterator; -use Icinga\Data\Tree\NodeInterface; +use Icinga\Data\Tree\TreeNodeIterator; /** - * Recursive iterator over sections that are part of a particular chapter + * Recursive filter iterator over sections that are part of a particular chapter + * + * @method TreeNodeIterator getInnerIterator() { + * {@inheritdoc} + * } */ class SectionFilterIterator extends RecursiveFilterIterator implements Countable { /** - * The chapter ID to filter for + * Chapter to filter for * - * @var string + * @type string */ - protected $chapterId; + protected $chapter; /** - * Create a new SectionFilterIterator + * Create a new recursive filter iterator over sections that are part of a particular chapter * - * @param NodeInterface $node Node - * @param string $chapterId The chapter ID to filter for + * @param TreeNodeIterator $iterator + * @param string $chapter The chapter to filter for */ - public function __construct(NodeInterface $node, $chapterId) + public function __construct(TreeNodeIterator $iterator, $chapter) { - parent::__construct($node); - $this->chapterId = $chapterId; + parent::__construct($iterator); + $this->chapter = $chapter; } /** @@ -39,29 +43,37 @@ class SectionFilterIterator extends RecursiveFilterIterator implements Countable */ public function accept() { - $section = $this->getInnerIterator()->current()->getValue(); - /* @var $section \Icinga\Module\Doc\Section */ - if ($section->getChapterId() === $this->chapterId) { + $section = $this->current(); + /** @type \Icinga\Module\Doc\DocSection $section */ + if ($section->getChapter()->getId() === $this->chapter) { return true; } return false; } /** - * (non-PHPDoc) - * @see RecursiveFilterIterator::getChildren() + * {@inheritdoc} */ public function getChildren() { - return new static($this->getInnerIterator()->getChildren(), $this->chapterId); + return new static($this->getInnerIterator()->getChildren(), $this->chapter); } /** - * (non-PHPDoc) - * @see Countable::count() + * {@inheritdoc} */ public function count() { return iterator_count($this); } + + /** + * Whether the filter swallowed every section + * + * @return bool + */ + public function isEmpty() + { + return $this->count() === 0; + } } From 5965638e2322764258d236e27a93dd11a23e045a Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:07:24 +0100 Subject: [PATCH 20/57] doc/lib: Open toc links in the next container refs #6630 --- modules/doc/library/Doc/TocRenderer.php | 74 ++++++++++++------------- 1 file changed, 34 insertions(+), 40 deletions(-) diff --git a/modules/doc/library/Doc/TocRenderer.php b/modules/doc/library/Doc/TocRenderer.php index 69ab7ac02..cfa18fad0 100644 --- a/modules/doc/library/Doc/TocRenderer.php +++ b/modules/doc/library/Doc/TocRenderer.php @@ -3,88 +3,81 @@ namespace Icinga\Module\Doc; -use RecursiveIteratorIterator; -use Zend_View_Helper_Url; use Icinga\Web\View; +use Icinga\Data\Tree\TreeNodeIterator; +use RecursiveIteratorIterator; /** * TOC renderer + * + * @method TreeNodeIterator getInnerIterator() { + * {@inheritdoc} + * } */ class TocRenderer extends Renderer { /** - * The URL to replace links with + * Content to render * - * @var string - */ - protected $url; - - /** - * Additional URL parameters - * - * @var array - */ - protected $urlParams; - - /** - * Content - * - * @var array + * @type array */ protected $content = array(); /** * Create a new toc renderer * - * @param DocTree $docTree The documentation tree - * @param string $url The URL to replace links with - * @param array $urlParams Additional URL parameters + * @param TreeNodeIterator $iterator */ - public function __construct(DocTree $docTree, $url, array $urlParams) + public function __construct(TreeNodeIterator $iterator) { - parent::__construct($docTree, RecursiveIteratorIterator::SELF_FIRST); - $this->url = $url; - $this->urlParams = array_map(array($this, 'encodeUrlParam'), $urlParams); + parent::__construct($iterator, RecursiveIteratorIterator::SELF_FIRST); } + /** + * {@inheritdoc} + */ public function beginIteration() { $this->content[] = ''; } + /** + * {@inheritdoc} + */ public function beginChildren() { $this->content[] = '
    '; } + /** + * {@inheritdoc} + */ public function endChildren() { - $this->content[] = '
'; + $this->content[] = ''; } /** - * Render the toc - * - * @param View $view - * @param Zend_View_Helper_Url $zendUrlHelper - * - * @return string + * {@inheritdoc} */ - public function render(View $view, Zend_View_Helper_Url $zendUrlHelper) + public function render() { - foreach ($this as $node) { - $section = $node->getValue(); - /* @var $section \Icinga\Module\Doc\Section */ + $view = $this->getView(); + $zendUrlHelper = $view->getHelper('Url'); + foreach ($this as $section) { $path = $zendUrlHelper->url( array_merge( $this->urlParams, array( - 'chapterId' => $this->encodeUrlParam($section->getChapterId()) + 'chapter' => $this->encodeUrlParam($section->getChapter()->getId()) ) ), $this->url, @@ -92,14 +85,15 @@ class TocRenderer extends Renderer false ); $url = $view->url($path); + /** @type \Icinga\Web\Url $url */ $url->setAnchor($this->encodeAnchor($section->getId())); $this->content[] = sprintf( - '
  • %s', - $section->isNoFollow() ? 'rel="nofollow" ' : '', + '
  • %s', + $section->getNoFollow() ? 'rel="nofollow" ' : '', $url->getAbsoluteUrl(), $view->escape($section->getTitle()) ); - if (! $this->getInnerIterator()->current()->hasChildren()) { + if (! $section->hasChildren()) { $this->content[] = '
    • '; } } From 41355fe0e24b417ecb1953aa63f3564d868d3b14 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:08:48 +0100 Subject: [PATCH 21/57] doc/lib: Drop navigation added to each section refs #6630 --- modules/doc/library/Doc/SectionRenderer.php | 296 ++++++-------------- 1 file changed, 89 insertions(+), 207 deletions(-) diff --git a/modules/doc/library/Doc/SectionRenderer.php b/modules/doc/library/Doc/SectionRenderer.php index b4d19f9fb..825754ad7 100644 --- a/modules/doc/library/Doc/SectionRenderer.php +++ b/modules/doc/library/Doc/SectionRenderer.php @@ -7,133 +7,54 @@ require_once 'Parsedown/Parsedown.php'; use DOMDocument; use DOMXPath; -use RecursiveIteratorIterator; use Parsedown; -use Zend_View_Helper_Url; +use RecursiveIteratorIterator; +use Icinga\Data\Tree\SimpleTree; use Icinga\Module\Doc\Exception\ChapterNotFoundException; use Icinga\Web\Url; use Icinga\Web\View; -/** - * preg_replace_callback helper to replace links - */ -class Callback -{ - protected $docTree; - - protected $view; - - protected $zendUrlHelper; - - protected $url; - - protected $urlParams; - - public function __construct( - DocTree $docTree, - View $view, - Zend_View_Helper_Url $zendUrlHelper, - $url, - array $urlParams) - { - $this->docTree = $docTree; - $this->view = $view; - $this->zendUrlHelper = $zendUrlHelper; - $this->url = $url; - $this->urlParams = $urlParams; - } - - public function render($match) - { - $node = $this->docTree->getNode(Renderer::decodeAnchor($match['fragment'])); - /* @var $node \Icinga\Data\Tree\Node */ - if ($node === null) { - return $match[0]; - } - $section = $node->getValue(); - /* @var $section \Icinga\Module\Doc\Section */ - $path = $this->zendUrlHelper->url( - array_merge( - $this->urlParams, - array( - 'chapterId' => SectionRenderer::encodeUrlParam($section->getChapterId()) - ) - ), - $this->url, - false, - false - ); - $url = $this->view->url($path); - $url->setAnchor(SectionRenderer::encodeAnchor($section->getId())); - return sprintf( - 'isNoFollow() ? 'rel="nofollow" ' : '', - $url->getAbsoluteUrl() - ); - } -} - /** * Section renderer */ class SectionRenderer extends Renderer { /** - * The documentation tree + * Content to render * - * @var DocTree - */ - protected $docTree; - - protected $tocUrl; - - /** - * The URL to replace links with - * - * @var string - */ - protected $url; - - /** - * Additional URL parameters - * - * @var array - */ - protected $urlParams; - - /** - * Parsedown instance - * - * @var Parsedown - */ - protected $parsedown; - - /** - * Content - * - * @var array + * @type array */ protected $content = array(); + /** + * Parsedown instance + * + * @type Parsedown + */ + protected $parsedown; + + /** + * Documentation tree + * + * @type SimpleTree + */ + protected $tree; + /** * Create a new section renderer * - * @param DocTree $docTree The documentation tree - * @param string|null $chapterId If not null, the chapter ID to filter for - * @param string $tocUrl - * @param string $url The URL to replace links with - * @param array $urlParams Additional URL parameters + * @param SimpleTree $tree The documentation tree + * @param string|null $chapter If not null, the chapter to filter for * * @throws ChapterNotFoundException If the chapter to filter for was not found */ - public function __construct(DocTree $docTree, $chapterId, $tocUrl, $url, array $urlParams) + public function __construct(SimpleTree $tree, $chapter = null) { - if ($chapterId !== null) { - $filter = new SectionFilterIterator($docTree, $chapterId); - if ($filter->count() === 0) { + if ($chapter !== null) { + $filter = new SectionFilterIterator($tree->getIterator(), $chapter); + if ($filter->isEmpty()) { throw new ChapterNotFoundException( - sprintf(mt('doc', 'Chapter \'%s\' not found'), $chapterId) + mt('doc', 'Chapter %s not found'), $chapter ); } parent::__construct( @@ -141,19 +62,16 @@ class SectionRenderer extends Renderer RecursiveIteratorIterator::SELF_FIRST ); } else { - parent::__construct($docTree, RecursiveIteratorIterator::SELF_FIRST); + parent::__construct($tree->getIterator(), RecursiveIteratorIterator::SELF_FIRST); } - $this->docTree = $docTree; - $this->tocUrl = $tocUrl; - $this->url = $url; - $this->urlParams = array_map(array($this, 'encodeUrlParam'), $urlParams); + $this->tree = $tree; $this->parsedown = Parsedown::instance(); } /** * Syntax highlighting for PHP code * - * @param $match + * @param array $match * * @return string */ @@ -162,6 +80,26 @@ class SectionRenderer extends Renderer return '
    ' . highlight_string(htmlspecialchars_decode($match[1]), true) . '
    '; } + /** + * Markup notes + * + * @param array $match + * + * @return string + */ + protected function markupNotes($match) + { + $doc = new DOMDocument(); + $doc->loadHTML($match[0]); + $xpath = new DOMXPath($doc); + $blockquote = $xpath->query('//blockquote[1]')->item(0); + /* @var $blockquote \DOMElement */ + if (strtolower(substr(trim($blockquote->nodeValue), 0, 5)) === 'note:') { + $blockquote->setAttribute('class', 'note'); + } + return $doc->saveXML($blockquote); + } + /** * Replace img src tags * @@ -180,40 +118,52 @@ class SectionRenderer extends Renderer return substr_replace($doc->saveXML($img), '', -2, 1); // Replace '/>' with '>' } - protected function blubb($match) - { - $doc = new DOMDocument(); - $doc->loadHTML($match[0]); - $xpath = new DOMXPath($doc); - $blockquote = $xpath->query('//blockquote[1]')->item(0); - /* @var $blockquote \DOMElement */ - if (strtolower(substr(trim($blockquote->nodeValue), 0, 5)) === 'note:') { - $blockquote->setAttribute('class', 'note'); - } - return $doc->saveXML($blockquote); - } - /** - * Render the section + * Replace link * - * @param View $view - * @param Zend_View_Helper_Url $zendUrlHelper - * @param bool $renderNavigation + * @param array $match * * @return string */ - public function render(View $view, Zend_View_Helper_Url $zendUrlHelper, $renderNavigation = true) + protected function replaceLink($match) { - $callback = new Callback($this->docTree, $view, $zendUrlHelper, $this->url, $this->urlParams); - $content = array(); - foreach ($this as $node) { - $section = $node->getValue(); - /* @var $section \Icinga\Module\Doc\Section */ - $content[] = sprintf( + if (($section = $this->tree->getNode($this->decodeAnchor($match['fragment']))) === null) { + return $match[0]; + } + /** @type $section \Icinga\Module\Doc\DocSection */ + $path = $this->getView()->getHelper('Url')->url( + array_merge( + $this->urlParams, + array( + 'chapter' => $this->encodeUrlParam($section->getChapter()->getId()) + ) + ), + $this->url, + false, + false + ); + $url = $this->getView()->url($path); + /** @type \Icinga\Web\Url $url */ + $url->setAnchor($this->encodeAnchor($section->getId())); + return sprintf( + '    getNoFollow() ? 'rel="nofollow" ' : '', + $url->getAbsoluteUrl() + ); + } + + /** + * {@inheritdoc} + */ + public function render() + { + foreach ($this as $section) { + $this->content[] = sprintf( '%3$s', Renderer::encodeAnchor($section->getId()), $section->getLevel(), - $view->escape($section->getTitle()) + $this->getView()->escape($section->getTitle()) ); $html = preg_replace_callback( '#
    (.*?)
    #s', @@ -227,83 +177,15 @@ class SectionRenderer extends Renderer ); $html = preg_replace_callback( '#
    .+
    #ms', - array($this, 'blubb'), + array($this, 'markupNotes'), $html ); - $content[] = preg_replace_callback( + $this->content[] = preg_replace_callback( '/[^>]*?\s+)?href="(?:(?!http:\/\/)[^#]*)#(?P[^"]+)"/', - array($callback, 'render'), + array($this, 'replaceLink'), $html ); } - if ($renderNavigation) { - foreach ($this->docTree as $chapter) { - if ($chapter->getValue()->getId() === $section->getChapterId()) { - $navigation = array('
      '); - $this->docTree->prev(); - $prev = $this->docTree->current(); - if ($prev !== null) { - $prev = $prev->getValue(); - $path = $zendUrlHelper->url( - array_merge( - $this->urlParams, - array( - 'chapterId' => $this->encodeUrlParam($prev->getChapterId()) - ) - ), - $this->url, - false, - false - ); - $url = $view->url($path); - $url->setAnchor($this->encodeAnchor($prev->getId())); - $navigation[] = sprintf( - '', - $prev->isNoFollow() ? 'rel="nofollow" ' : '', - $url->getAbsoluteUrl(), - $view->escape($prev->getTitle()) - ); - $this->docTree->next(); - $this->docTree->next(); - } else { - $this->docTree->rewind(); - $this->docTree->next(); - } - $url = $view->url($this->tocUrl); - $navigation[] = sprintf( - '
    • %s
      • ', - $url->getAbsoluteUrl(), - mt('doc', 'Index') - ); - $next = $this->docTree->current(); - if ($next !== null) { - $next = $next->getValue(); - $path = $zendUrlHelper->url( - array_merge( - $this->urlParams, - array( - 'chapterId' => $this->encodeUrlParam($next->getChapterId()) - ) - ), - $this->url, - false, - false - ); - $url = $view->url($path); - $url->setAnchor($this->encodeAnchor($next->getId())); - $navigation[] = sprintf( - '', - $next->isNoFollow() ? 'rel="nofollow" ' : '', - $url->getAbsoluteUrl(), - $view->escape($next->getTitle()) - ); - } - $navigation[] = '
    '; - $content = array_merge($navigation, $content, $navigation); - break; - } - } - } - return implode("\n", $content); + return implode("\n", $this->content); } } From 005ef8c92f0a00b10cdfb70e4589debf582c0533 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:09:56 +0100 Subject: [PATCH 22/57] doc/lib: Update controllers and views according to the recent changes refs #6630 --- .../controllers/IcingawebController.php | 9 ++--- .../controllers/ModuleController.php | 9 ++--- .../application/views/scripts/chapter.phtml | 2 +- .../views/scripts/module/chapter.phtml | 2 +- .../views/scripts/module/toc.phtml | 4 +- .../doc/application/views/scripts/toc.phtml | 4 +- modules/doc/configuration.php | 2 + modules/doc/library/Doc/DocController.php | 37 +++++++++---------- modules/doc/run.php | 4 +- 9 files changed, 36 insertions(+), 37 deletions(-) diff --git a/modules/doc/application/controllers/IcingawebController.php b/modules/doc/application/controllers/IcingawebController.php index 89afc0e59..31819239a 100644 --- a/modules/doc/application/controllers/IcingawebController.php +++ b/modules/doc/application/controllers/IcingawebController.php @@ -46,17 +46,16 @@ class Doc_IcingawebController extends DocController */ public function chapterAction() { - $chapterId = $this->getParam('chapterId'); - if ($chapterId === null) { + $chapter = $this->getParam('chapter'); + if ($chapter === null) { throw new Zend_Controller_Action_Exception( - sprintf($this->translate('Missing parameter \'%s\''), 'chapterId'), + sprintf($this->translate('Missing parameter %s'), 'chapter'), 404 ); } $this->renderChapter( $this->getPath(), - $chapterId, - 'doc/icingaweb/toc', + $chapter, 'doc/icingaweb/chapter' ); } diff --git a/modules/doc/application/controllers/ModuleController.php b/modules/doc/application/controllers/ModuleController.php index d0c760444..3b8e5e201 100644 --- a/modules/doc/application/controllers/ModuleController.php +++ b/modules/doc/application/controllers/ModuleController.php @@ -122,10 +122,10 @@ class Doc_ModuleController extends DocController { $module = $this->getParam('moduleName'); $this->assertModuleEnabled($module); - $chapterId = $this->getParam('chapterId'); - if ($chapterId === null) { + $chapter = $this->getParam('chapter'); + if ($chapter === null) { throw new Zend_Controller_Action_Exception( - sprintf($this->translate('Missing parameter \'%s\''), 'chapterId'), + sprintf($this->translate('Missing parameter %s'), 'chapter'), 404 ); } @@ -133,8 +133,7 @@ class Doc_ModuleController extends DocController try { $this->renderChapter( $this->getPath($module, Icinga::app()->getModuleManager()->getModuleDir($module, '/doc')), - $chapterId, - $this->_helper->url->url(array('moduleName' => $module), 'doc/module/toc'), + $chapter, 'doc/module/chapter', array('moduleName' => $module) ); diff --git a/modules/doc/application/views/scripts/chapter.phtml b/modules/doc/application/views/scripts/chapter.phtml index 7657d69fb..6fe0d8d27 100644 --- a/modules/doc/application/views/scripts/chapter.phtml +++ b/modules/doc/application/views/scripts/chapter.phtml @@ -1,3 +1,3 @@
    - render($this, $this->getHelper('Url')); ?> +
    diff --git a/modules/doc/application/views/scripts/module/chapter.phtml b/modules/doc/application/views/scripts/module/chapter.phtml index 7657d69fb..6fe0d8d27 100644 --- a/modules/doc/application/views/scripts/module/chapter.phtml +++ b/modules/doc/application/views/scripts/module/chapter.phtml @@ -1,3 +1,3 @@
    - render($this, $this->getHelper('Url')); ?> +
    diff --git a/modules/doc/application/views/scripts/module/toc.phtml b/modules/doc/application/views/scripts/module/toc.phtml index ca6283d67..ce1b3da29 100644 --- a/modules/doc/application/views/scripts/module/toc.phtml +++ b/modules/doc/application/views/scripts/module/toc.phtml @@ -1,6 +1,6 @@
    -

    +

    - render($this, $this->getHelper('Url')); ?> +
    diff --git a/modules/doc/application/views/scripts/toc.phtml b/modules/doc/application/views/scripts/toc.phtml index ca6283d67..ce1b3da29 100644 --- a/modules/doc/application/views/scripts/toc.phtml +++ b/modules/doc/application/views/scripts/toc.phtml @@ -1,6 +1,6 @@
    -

    +

    - render($this, $this->getHelper('Url')); ?> +
    diff --git a/modules/doc/configuration.php b/modules/doc/configuration.php index f9bed3887..fdbada7af 100644 --- a/modules/doc/configuration.php +++ b/modules/doc/configuration.php @@ -20,3 +20,5 @@ $section->add($this->translate('Developer - Style'), array( 'url' => 'doc/style/guide', 'priority' => 200, )); + +$this->provideSearchUrl($this->translate('Doc'), 'doc/search'); diff --git a/modules/doc/library/Doc/DocController.php b/modules/doc/library/Doc/DocController.php index 9e29d99c7..70d2639bf 100644 --- a/modules/doc/library/Doc/DocController.php +++ b/modules/doc/library/Doc/DocController.php @@ -10,38 +10,37 @@ class DocController extends ModuleActionController /** * Render a chapter * - * @param string $path Path to the documentation - * @param string $chapterId ID of the chapter - * @param string $tocUrl - * @param string $url - * @param array $urlParams + * @param string $path Path to the documentation + * @param string $chapter ID of the chapter + * @param string $url URL to replace links with + * @param array $urlParams Additional URL parameters */ - protected function renderChapter($path, $chapterId, $tocUrl, $url, array $urlParams = array()) + protected function renderChapter($path, $chapter, $url, array $urlParams = array()) { $parser = new DocParser($path); - $this->view->sectionRenderer = new SectionRenderer( - $parser->getDocTree(), - SectionRenderer::decodeUrlParam($chapterId), - $tocUrl, - $url, - $urlParams - ); - $this->view->title = $chapterId; + $section = new SectionRenderer($parser->getDocTree(), SectionRenderer::decodeUrlParam($chapter)); + $this->view->section = $section + ->setUrl($url) + ->setUrlParams($urlParams); + $this->view->title = $chapter; $this->render('chapter', null, true); } /** * Render a toc * - * @param string $path Path to the documentation - * @param string $name Name of the documentation - * @param string $url - * @param array $urlParams + * @param string $path Path to the documentation + * @param string $name Name of the documentation + * @param string $url URL to replace links with + * @param array $urlParams Additional URL parameters */ protected function renderToc($path, $name, $url, array $urlParams = array()) { $parser = new DocParser($path); - $this->view->tocRenderer = new TocRenderer($parser->getDocTree(), $url, $urlParams); + $toc = new TocRenderer($parser->getDocTree()->getIterator()); + $this->view->toc = $toc + ->setUrl($url) + ->setUrlParams($urlParams); $name = ucfirst($name); $this->view->docName = $name; $this->view->title = sprintf($this->translate('%s Documentation'), $name); diff --git a/modules/doc/run.php b/modules/doc/run.php index cdeb95195..95abbf9df 100644 --- a/modules/doc/run.php +++ b/modules/doc/run.php @@ -9,7 +9,7 @@ if (Icinga::app()->isCli()) { } $docModuleChapter = new Zend_Controller_Router_Route( - 'doc/module/:moduleName/chapter/:chapterId', + 'doc/module/:moduleName/chapter/:chapter', array( 'controller' => 'module', 'action' => 'chapter', @@ -18,7 +18,7 @@ $docModuleChapter = new Zend_Controller_Router_Route( ); $docIcingaWebChapter = new Zend_Controller_Router_Route( - 'doc/icingaweb/chapter/:chapterId', + 'doc/icingaweb/chapter/:chapter', array( 'controller' => 'icingaweb', 'action' => 'chapter', From 312d18d14aea68c93c4bbff31f67f2d80918b7ba Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:11:00 +0100 Subject: [PATCH 23/57] doc/lib: Add DocSearch class for creating search criteria refs #6630 --- modules/doc/library/Doc/Search/DocSearch.php | 91 ++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 modules/doc/library/Doc/Search/DocSearch.php diff --git a/modules/doc/library/Doc/Search/DocSearch.php b/modules/doc/library/Doc/Search/DocSearch.php new file mode 100644 index 000000000..ab3a7cf64 --- /dev/null +++ b/modules/doc/library/Doc/Search/DocSearch.php @@ -0,0 +1,91 @@ +input = $search = (string) $search; + $criteria = array(); + if (preg_match_all('/"(?P[^"]*)"/', $search, $matches, PREG_SET_ORDER | PREG_OFFSET_CAPTURE)) { + $unquoted = ''; + $offset = 0; + foreach ($matches as $match) { + $fullMatch = $match[0]; + $searchMatch = $match['search']; + $unquoted .= substr($search, $offset, $fullMatch[1] - $offset); + $offset += $fullMatch[1] + strlen($fullMatch[0]); + if (strlen($searchMatch[0]) > 0) { + $criteria[] = $searchMatch[0]; + } + } + $search = $unquoted . substr($search, $offset); + } + $this->search = array_unique(array_merge($criteria, array_filter(explode(' ', trim($search))))); + } + + /** + * Get the search criteria + * + * @return array + */ + public function getCriteria() + { + return $this->search; + } + + /** + * Get the search string + * + * @return string + */ + public function getInput() + { + return $this->input; + } + + /** + * Search in the given line + * + * @param string $line + * + * @return DocSearchMatch|null + */ + public function search($line) + { + $match = new DocSearchMatch(); + $match->setLine($line); + foreach ($this->search as $criteria) { + $offset = 0; + while (($position = stripos($line, $criteria, $offset)) !== false) { + $match->appendMatch(substr($line, $position, strlen($criteria)), $position); + $offset = $position + 1; + } + } + return $match->isEmpty() ? null : $match; + } +} From 267c36d8d16d0c7a262b36beb36c85c298ae87af Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:11:48 +0100 Subject: [PATCH 24/57] doc/lib: Add class DocSearchMatch represeting a search match refs #6630 --- .../doc/library/Doc/Search/DocSearchMatch.php | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 modules/doc/library/Doc/Search/DocSearchMatch.php diff --git a/modules/doc/library/Doc/Search/DocSearchMatch.php b/modules/doc/library/Doc/Search/DocSearchMatch.php new file mode 100644 index 000000000..c5c7b4b7f --- /dev/null +++ b/modules/doc/library/Doc/Search/DocSearchMatch.php @@ -0,0 +1,151 @@ +line = (string) $line; + return $this; + } + + /** + * Get the line + * + * @return string + */ + public function getLine() + { + return $this->line; + } + + /** + * Set the line number + * + * @param int $lineno + * + * @return $this + */ + public function setLineno($lineno) + { + $this->lineno = (int) $lineno; + return $this; + } + + /** + * Set the match type + * + * @param int $matchType + * + * @return $this + */ + public function setMatchType($matchType) + { + $matchType = (int) $matchType; + if ($matchType !== static::MATCH_HEADER && $matchType !== static::MATCH_CONTENT) { + throw new UnexpectedValueException(); + } + $this->matchType = $matchType; + return $this; + } + + /** + * Get the match type + * + * @return int + */ + public function getMatchType() + { + return $this->matchType; + } + + /** + * Append a match + * + * @param string $match + * @param int $position + * + * @return $this + */ + public function appendMatch($match, $position) + { + $this->matches[(int) $position] = (string) $match; + return $this; + } + + /** + * Get the matches + * + * @return array + */ + public function getMatches() + { + return $this->matches; + } + + /** + * Whether the match is empty + * + * @return bool + */ + public function isEmpty() + { + return empty($this->matches); + } +} From e7b0f8d30f5548cb6ea3098938419ad697a5b2e4 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:12:43 +0100 Subject: [PATCH 25/57] doc/lib: Add iterator over doc sections that match a given search criteria refs #6630 --- .../library/Doc/Search/DocSearchIterator.php | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 modules/doc/library/Doc/Search/DocSearchIterator.php diff --git a/modules/doc/library/Doc/Search/DocSearchIterator.php b/modules/doc/library/Doc/Search/DocSearchIterator.php new file mode 100644 index 000000000..a3a4d8504 --- /dev/null +++ b/modules/doc/library/Doc/Search/DocSearchIterator.php @@ -0,0 +1,122 @@ +search = $search; + parent::__construct($iterator); + } + + /** + * Accept sections that match the search + * + * @return bool Whether the current element of the iterator is acceptable + * through this filter + */ + public function accept() + { + $section = $this->getInnerIterator()->current(); + /** @type $section \Icinga\Module\Doc\DocSection */ + $matches = array(); + if (($match = $this->search->search($section->getTitle())) !== null) { + $matches[] = $match->setMatchType(DocSearchMatch::MATCH_HEADER); + } + foreach ($section->getContent() as $lineno => $line) { + if (($match = $this->search->search($line)) !== null) { + $matches[] = $match + ->setMatchType(DocSearchMatch::MATCH_CONTENT) + ->setLineno($lineno); + } + } + if (! empty($matches)) { + $this->matches = $matches; + return $this; + } + if ($section->hasChildren()) { + $this->matches = null; + return true; + } + return false; + } + + /** + * Get the search criteria + * + * @return DocSearch + */ + public function getSearch() + { + return $this->search; + } + + /** + * {@inheritdoc} + */ + public function getChildren() + { + return new static($this->getInnerIterator()->getChildren(), $this->search); + } + + /** + * {@inheritdoc} + */ + public function count() + { + return iterator_count($this); + } + + /** + * Whether the search did not yield any match + * + * @return bool + */ + public function isEmpty() + { + return $this->count() === 0; + } + + /** + * Get matches + * + * @return DocSearchMatch[]|null + */ + public function getMatches() + { + return $this->matches; + } +} From 3b20e499404d6b451a385522e91341b652197a21 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:13:17 +0100 Subject: [PATCH 26/57] doc/lib: Add renderer for doc searches refs #6630 --- .../library/Doc/Search/DocSearchRenderer.php | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 modules/doc/library/Doc/Search/DocSearchRenderer.php diff --git a/modules/doc/library/Doc/Search/DocSearchRenderer.php b/modules/doc/library/Doc/Search/DocSearchRenderer.php new file mode 100644 index 000000000..97f830a93 --- /dev/null +++ b/modules/doc/library/Doc/Search/DocSearchRenderer.php @@ -0,0 +1,147 @@ +content[] = ''; + } + + /** + * {@inheritdoc} + */ + public function beginChildren() + { + if ($this->getInnerIterator()->getMatches()) { + $this->content[] = '
      '; + } + } + + /** + * {@inheritdoc} + */ + public function endChildren() + { + if ($this->getInnerIterator()->getMatches()) { + $this->content[] = '
    '; + } + } + + public function highlight($line, array $matches) + { + $highlighted = ''; + $offset = 0; + ksort($matches); + foreach ($matches as $position => $match) { + $highlighted .= $this->getView()->escape(substr($line, $offset, $position - $offset)) + . '' + . $this->getView()->escape($match) + . ''; + $offset = $position + strlen($match); + } + $highlighted .= $this->getView()->escape(substr($line, $offset)); + return $highlighted; + } + + /** + * {@inheritdoc} + */ + public function render() + { + foreach ($this as $section) { + if (($matches = $this->getInnerIterator()->getMatches()) === null) { + continue; + } + $title = $this->getView()->escape($section->getTitle()); + $contentMatches = array(); + foreach ($matches as $match) { + if ($match->getMatchType() === DocSearchMatch::MATCH_HEADER) { + $title = $this->highlight($match->getLine(), $match->getMatches()); + } else { + $contentMatches[] = sprintf( + '

    %s

    ', + $this->highlight($match->getLine(), $match->getMatches()) + ); + } + } + $path = $this->getView()->getHelper('Url')->url( + array_merge( + $this->urlParams, + array( + 'chapter' => $this->encodeUrlParam($section->getChapter()->getId()) + ) + ), + $this->url, + false, + false + ); + $url = $this->getView()->url( + $path, + array('highlight' => $this->getInnerIterator()->getSearch()->getInput()) + ); + /** @type \Icinga\Web\Url $url */ + $url->setAnchor($this->encodeAnchor($section->getId())); + $this->content[] = sprintf( + '
  • %s', + $section->getNoFollow() ? 'rel="nofollow" ' : '', + $url->getAbsoluteUrl(), + $title + ); + if (! empty($contentMatches)) { + $this->content = array_merge($this->content, $contentMatches); + } + if (! $section->hasChildren()) { + $this->content[] = '
    • '; + } + } + return implode("\n", $this->content); + } +} From e2b34023cd4736327a04c74e341e49493e08dacc Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 10 Feb 2015 17:14:16 +0100 Subject: [PATCH 27/57] doc/lib: Add SearchController At the moment only Icinga Web 2's documentation is available for searching. refs #6630 --- .../controllers/SearchController.php | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 modules/doc/application/controllers/SearchController.php diff --git a/modules/doc/application/controllers/SearchController.php b/modules/doc/application/controllers/SearchController.php new file mode 100644 index 000000000..5ba223d00 --- /dev/null +++ b/modules/doc/application/controllers/SearchController.php @@ -0,0 +1,49 @@ +getPath()); + $search = new DocSearchRenderer( + new DocSearchIterator( + $parser->getDocTree()->getIterator(), + new DocSearch($this->params->get('q')) + ) + ); + $this->view->search = $search->setUrl('doc/icingaweb/chapter'); + } + + /** + * Get the path to Icinga Web 2's documentation + * + * @return string + * + * @throws Zend_Controller_Action_Exception If Icinga Web 2's documentation is not available + */ + protected function getPath() + { + $path = Icinga::app()->getBaseDir('doc'); + if (is_dir($path)) { + return $path; + } + if (($path = $this->Config()->get('documentation', 'icingaweb2')) !== null) { + if (is_dir($path)) { + return $path; + } + } + throw new Zend_Controller_Action_Exception( + $this->translate('Documentation for Icinga Web 2 is not available'), + 404 + ); + } +} From 0b1a9c16596b7b819c34db3014c54812869c1db3 Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Wed, 11 Feb 2015 12:58:31 +0100 Subject: [PATCH 28/57] doc/lib: Apply role and css class toc to the toc refs #6630 --- modules/doc/library/Doc/TocRenderer.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/doc/library/Doc/TocRenderer.php b/modules/doc/library/Doc/TocRenderer.php index cfa18fad0..019ca2d9f 100644 --- a/modules/doc/library/Doc/TocRenderer.php +++ b/modules/doc/library/Doc/TocRenderer.php @@ -38,7 +38,7 @@ class TocRenderer extends Renderer */ public function beginIteration() { - $this->content[] = '