Completed
Push — develop ( 8eb671...133594 )
by Mike
19:30 queued 09:24
created

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

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

1
<?php
2
declare(strict_types=1);
3
4
/**
5
 * This file is part of phpDocumentor.
6
 *
7
 * For the full copyright and license information, please view the LICENSE
8
 * file that was distributed with this source code.
9
 *
10
 * @author    Mike van Riel <[email protected]>
11
 * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
12
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
13
 * @link      http://phpdoc.org
14
 */
15
16
namespace phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Directives;
17
18
use \phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Visitors\Discover;
19
use phpDocumentor\Plugin\Scrybe\Converter\Metadata\Assets;
20
21
/**
22
 * Directive used to process `.. figure::` and collect images as assets to be copied.
23
 *
24
 * The filenames of the images are taken from the directive and added onto the assets collection during the
25
 * discovery phase. These assets may then be copied to the destination location by the invoker.
26
 *
27
 * @see \phpDocumentor\Plugin\Scrybe\Converter\Metadata\Assets
28
 */
29
class Figure extends \ezcDocumentRstFigureDirective
30
{
31
    /** @var Discover */
32
    protected $visitor;
33
34
    /**
35
     * Converts the Image directive to aDocBook image tag.
36
     *
37
     * This method takes an image directive and converts it into its DocBook representation and stores a reference in
38
     * the Asset manager of the Converter.
39
     *
40
     * @see ConverterInterface::getAssets() for the asset manager
41
     */
42
    public function toDocbook(\DOMDocument $document, \DOMElement $root)
43
    {
44
        $this->storeAsset();
45
        parent::toDocbook($document, $root);
46
    }
47
48
    /**
49
     * Converts the Image directive to an <img/> tag.
50
     *
51
     * This method takes an image directive and converts it into its HTML representation and stores a reference in the
52
     * Asset manager of the Converter.
53
     *
54
     * @see ConverterInterface::getAssets() for the asset manager
55
     */
56
    public function toXhtml(\DOMDocument $document, \DOMElement $root)
57
    {
58
        $this->storeAsset();
59
        parent::toXhtml($document, $root);
60
    }
61
62
    /**
63
     * Stores the asset in the asset manager.
64
     *
65
     * This method takes an asset defined in the directive and stores that in the asset manager.
66
     *
67
     * The following rules apply:
68
     *
69
     * 1. The source of the asset is the relative path of the asset prefixed
70
     *    with a path based on the following rules:
71
     *
72
     *    1. If the asset starts with a slash then the path is calculated from the project's root or
73
     *    2. if the asset does not start with a slash then the path is calculated from the file's directory.
74
     *
75
     * 2. the destination of the asset is the path relative to the project root.
76
     *
77
     *    1. When the asset starts with a slash then this equals that path without the leading slash.
78
     *    2. If not, the destination must be calculated by subtracting the project root from the current file's path
79
     *       and prepending that to the asset path (resolving `../` patterns in the mean time).
80
     */
81
    protected function storeAsset()
82
    {
83
        if (!$this->visitor instanceof Discover) {
84
            return;
85
        }
86
87
        $assets = $this->getAssetManager();
88
        $project_root = $assets->getProjectRoot();
89
        $asset_path = trim($this->node->parameters);
90
        $file_path = $this->visitor->getDocument()->getFile()->getRealPath();
91
92
        // get source path
93
        $source = ($asset_path[0] !== '/')
94
            ? dirname($file_path) . '/' . $asset_path
95
            : $project_root . $asset_path;
96
97
        // get destination path
98
        $destination = ($asset_path[0] !== '/')
99
            ? substr(dirname($file_path) . '/' . $asset_path, strlen($project_root))
100
            : substr($asset_path, 1);
101
102
        // set asset
103
        $assets->set($source, $destination);
0 ignored issues
show
The call to the method phpDocumentor\Plugin\Scr...\Metadata\Assets::set() seems un-needed as the method has no side-effects.

PHP Analyzer performs a side-effects analysis of your code. A side-effect is basically anything that might be visible after the scope of the method is left.

Let’s take a look at an example:

class User
{
    private $email;

    public function getEmail()
    {
        return $this->email;
    }

    public function setEmail($email)
    {
        $this->email = $email;
    }
}

If we look at the getEmail() method, we can see that it has no side-effect. Whether you call this method or not, no future calls to other methods are affected by this. As such code as the following is useless:

$user = new User();
$user->getEmail(); // This line could safely be removed as it has no effect.

On the hand, if we look at the setEmail(), this method _has_ side-effects. In the following case, we could not remove the method call:

$user = new User();
$user->setEmail('[email protected]'); // This line has a side-effect (it changes an
                                 // instance variable).
Loading history...
104
    }
105
106
    /**
107
     * Returns the asset manager.
108
     *
109
     * @return Assets
110
     */
111
    protected function getAssetManager()
112
    {
113
        return $this->visitor->getDocument()->getConverter()->getAssets();
114
    }
115
}
116