Issues in Toctree.php - New Issues - Inspection of "Merge pull request #1924 from mbed67/marieke-featu..." - phpDocumentor/phpDocumentor - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Push — develop ( 4b49c4...89d32a )

by Jaap

created 2017-12-30 14:07 UTC

Converter/RestructuredText/Directives/Toctree.php (1 issue)

Labels

Severity

Major 1

Upgrade to new PHP Analysis Engine

These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more

<?php
/**
 * phpDocumentor
 *
 * PHP Version 5.3
 *
 * @copyright 2010-2014 Mike van Riel / Naenius (http://www.naenius.com)
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
 * @link      http://phpdoc.org
 */

namespace phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Directives;

use phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Visitors\Creator;
use phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Visitors\Discover;

/**
 * Directive used to process `.. toctree::` and insert entries from the table of contents.
 *
 * This directive tries to match the file with an entry in the table of contents during the creation phase. If a
 * document is found it will generate a mini-table of contents at that location with the depth given using the
 * `:maxdepth:` parameter.
 *
 * Another option is :hidden: that will hide the toc from view while still making connections.
 *
 * This directive is inspired by {@link http://sphinx.pocoo.org/concepts.html#the-toc-tree Sphinx' toctree} directive.
 */
class Toctree extends \ezcDocumentRstDirective implements \ezcDocumentRstXhtmlDirective
{
    protected $links = array();

    public function __construct(\ezcDocumentRstDocumentNode $ast, $path, \ezcDocumentRstDirectiveNode $node)
    {
        parent::__construct($ast, $path, $node);

        $this->parseLinks();
    }

    protected function parseLinks()
    {
        $line = '';

        /** @var \ezcDocumentRstToken $token */
        foreach ($this->node->tokens as $token) {
            if ($token->type === 2) {
                $line = trim($line);
                if ($line) {
                    $this->links[] = $line;
                    $line = '';
                }
            }

            if ($token->type !== 5 && $token->type !== 4) {
                continue;
            }

            $line .= $token->content;
        }
    }

    /**
     * Transform directive to docbook
     *
     * Create a docbook XML structure at the directives position in the document.
     *
     * @param \DOMDocument $document
     * @param \DOMElement  $root
     *
     * @return void
     */
    public function toDocbook(\DOMDocument $document, \DOMElement $root)
    {
    }

    /**
     * Transform directive to HTML
     *
     * Create a XHTML structure at the directives position in the document.
     *
     * @param \DOMDocument $document
     * @param \DOMElement $root
     *
     * @todo use the TableofContents collection to extract a sublisting up to the given depth or 2 if none is provided
     *
     * @return void
     */
    public function toXhtml(\DOMDocument $document, \DOMElement $root)
    {
        $this->addLinksToTableOfContents();

        // if the hidden flag is set then this item should not be rendered but still processed (see above)
        if (isset($this->node->options['hidden'])) {
            return;
        }

        $list = $document->createElement('ol');
        $root->appendChild($list);

        foreach ($this->links as $link) {
            $list_item = $document->createElement('li');
            $list->appendChild($list_item);

            $link_element = $document->createElement('a');
            $list_item->appendChild($link_element);
            $link_element->appendChild($document->createTextNode($this->getCaption($link)));
            $link_element->setAttribute('href', str_replace('\\', '/', $link) . '.html');
        }
    }

    protected function addLinksToTableOfContents()
    {
        foreach ($this->links as $file_name) {
            /** @var Discover $visitor */
            $visitor = $this->visitor;
            if ($visitor instanceof Discover) {
                $toc = $visitor->getTableOfContents();
                $file = $toc[$file_name];

                $visitor->addFileToLastHeading($file);
            }
        }
    }

    /**
     * Retrieves the caption for the given $token.
     *
     * The caption is retrieved by converting the filename to a human-readable format.
     *
     * @param \ezcDocumentRstToken $file_name
     *
     * @return string
     */
    protected function getCaption($file_name)
    {
        if ($this->visitor instanceof Creator) {
            $toc = $this->visitor->getTableOfContents();
            $name = $toc[$file_name]->getName();
            return $name ? $name : $file_name;
        }

        return $file_name;
class Author {
    private $name;

    public function __construct($name) {
        $this->name = $name;
    }

    public function getName() {
        return $this->name;
    }
}

abstract class Post {
    public function getAuthor() {
        return 'Johannes';
    }
}

class BlogPost extends Post {
    public function getAuthor() {
        return new Author('Johannes');
    }
}

class ForumPost extends Post { /* ... */ }

function my_function(Post $post) {
    echo strtoupper($post->getAuthor());
}
    }
}


1			<?php
2			/**
3			* phpDocumentor
4			*
5			* PHP Version 5.3
6			*
7			* @copyright 2010-2014 Mike van Riel / Naenius (http://www.naenius.com)
8			* @license http://www.opensource.org/licenses/mit-license.php MIT
9			* @link http://phpdoc.org
10			*/
11
12			namespace phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Directives;
13
14			use phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Visitors\Creator;
15			use phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Visitors\Discover;
16
17			/**
18			* Directive used to process `.. toctree::` and insert entries from the table of contents.
19			*
20			* This directive tries to match the file with an entry in the table of contents during the creation phase. If a
21			* document is found it will generate a mini-table of contents at that location with the depth given using the
22			* `:maxdepth:` parameter.
23			*
24			* Another option is :hidden: that will hide the toc from view while still making connections.
25			*
26			* This directive is inspired by {@link http://sphinx.pocoo.org/concepts.html#the-toc-tree Sphinx' toctree} directive.
27			*/
28			class Toctree extends \ezcDocumentRstDirective implements \ezcDocumentRstXhtmlDirective
29			{
30			protected $links = array();
31
32			public function __construct(\ezcDocumentRstDocumentNode $ast, $path, \ezcDocumentRstDirectiveNode $node)
33			{
34			parent::__construct($ast, $path, $node);
35
36			$this->parseLinks();
37			}
38
39			protected function parseLinks()
40			{
41			$line = '';
42
43			/** @var \ezcDocumentRstToken $token */
44			foreach ($this->node->tokens as $token) {
45			if ($token->type === 2) {
46			$line = trim($line);
47			if ($line) {
48			$this->links[] = $line;
49			$line = '';
50			}
51			}
52
53			if ($token->type !== 5 && $token->type !== 4) {
54			continue;
55			}
56
57			$line .= $token->content;
58			}
59			}
60
61			/**
62			* Transform directive to docbook
63			*
64			* Create a docbook XML structure at the directives position in the document.
65			*
66			* @param \DOMDocument $document
67			* @param \DOMElement $root
68			*
69			* @return void
70			*/
71			public function toDocbook(\DOMDocument $document, \DOMElement $root)
72			{
73			}
74
75			/**
76			* Transform directive to HTML
77			*
78			* Create a XHTML structure at the directives position in the document.
79			*
80			* @param \DOMDocument $document
81			* @param \DOMElement $root
82			*
83			* @todo use the TableofContents collection to extract a sublisting up to the given depth or 2 if none is provided
84			*
85			* @return void
86			*/
87			public function toXhtml(\DOMDocument $document, \DOMElement $root)
88			{
89			$this->addLinksToTableOfContents();
90
91			// if the hidden flag is set then this item should not be rendered but still processed (see above)
92			if (isset($this->node->options['hidden'])) {
93			return;
94			}
95
96			$list = $document->createElement('ol');
97			$root->appendChild($list);
98
99			foreach ($this->links as $link) {
100			$list_item = $document->createElement('li');
101			$list->appendChild($list_item);
102
103			$link_element = $document->createElement('a');
104			$list_item->appendChild($link_element);
105			$link_element->appendChild($document->createTextNode($this->getCaption($link)));
106			$link_element->setAttribute('href', str_replace('\\', '/', $link) . '.html');
107			}
108			}
109
110			protected function addLinksToTableOfContents()
111			{
112			foreach ($this->links as $file_name) {
113			/** @var Discover $visitor */
114			$visitor = $this->visitor;
115			if ($visitor instanceof Discover) {
116			$toc = $visitor->getTableOfContents();
117			$file = $toc[$file_name];
118
119			$visitor->addFileToLastHeading($file);
120			}
121			}
122			}
123
124			/**
125			* Retrieves the caption for the given $token.
126			*
127			* The caption is retrieved by converting the filename to a human-readable format.
128			*
129			* @param \ezcDocumentRstToken $file_name
130			*
131			* @return string
132			*/
133			protected function getCaption($file_name)
134			{
135			if ($this->visitor instanceof Creator) {
136			$toc = $this->visitor->getTableOfContents();
137			$name = $toc[$file_name]->getName();
138			return $name ? $name : $file_name;
139			}
140
141			return $file_name;
			0 ignored issues – show Bug Best Practice introduced 2017-12-26 19:20 UTC by Report Bug Copy Issue Report Show Similar Issues like this The return type of `return $file_name;` (`ezcDocumentRstToken`) is incompatible with the return type documented by `phpDocumentor\Plugin\Scr...ves\Toctree::getCaption` of type `string`. If you return a value from a function or method, it should be a sub-type of the type that is given by the parent type f.e. an interface, or abstract method. This is more formally defined by the Lizkov substitution principle, and guarantees that classes that depend on the parent type can use any instance of a child type interchangably. This principle also belongs to the SOLID principles for object oriented design. Let’s take a look at an example: class Author { private $name; public function __construct($name) { $this->name = $name; } public function getName() { return $this->name; } } abstract class Post { public function getAuthor() { return 'Johannes'; } } class BlogPost extends Post { public function getAuthor() { return new Author('Johannes'); } } class ForumPost extends Post { /* ... */ } function my_function(Post $post) { echo strtoupper($post->getAuthor()); } Our function `my_function` expects a `Post` object, and outputs the author of the post. The base class `Post` returns a simple string and outputting a simple string will work just fine. However, the child class `BlogPost` which is a sub-type of `Post` instead decided to return an `object`, and is therefore violating the SOLID principles. If a `BlogPost` were passed to `my_function`, PHP would not complain, but ultimately fail when executing the `strtoupper` call in its body. Loading history...
142			}
143			}
144

phpDocumentor / phpDocumentor

Push — develop ( 4b49c4...89d32a )

Converter/RestructuredText/Directives/Toctree.php (1 issue)

Labels

Severity

Introduced By

Upgrade to new PHP Analysis Engine

Duplication Side-by-Side

Filter issues like