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

Converter/RestructuredText/Directives/Image.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 `.. image::` 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 discovery
25
 * 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 Image extends \ezcDocumentRstImageDirective
30
{
31
    /** @var Discover The visitor used to discover the images */
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
46
        parent::toDocbook($document, $root);
47
    }
48
49
    /**
50
     * Converts the Image directive to an <img/> tag.
51
     *
52
     * This method takes an image directive and converts it into its HTML representation and stores a reference in the
53
     * Asset manager of the Converter.
54
     *
55
     * @see ConverterInterface::getAssets() for the asset manager
56
     */
57
    public function toXhtml(\DOMDocument $document, \DOMElement $root)
58
    {
59
        $this->storeAsset();
60
61
        parent::toXhtml($document, $root);
62
    }
63
64
    /**
65
     * Stores the asset in the asset manager.
66
     *
67
     * This method takes an asset defined in the directive and stores that in the asset manager.
68
     *
69
     * The following rules apply:
70
     *
71
     * 1. The source of the asset is the relative path of the asset prefixed with a path based on the following rules:
72
     *
73
     *    1. If the asset starts with a slash then the path is calculated from the project's root or
74
     *    2. if the asset does not start with a slash then the path is calculated from the file's directory.
75
     *
76
     * 2. the destination of the asset is the path relative to the project root.
77
     *
78
     *    1. When the asset starts with a slash then this equals that path without the leading slash.
79
     *    2. If not, the destination must be calculated by subtracting the project root from the current file's path
80
     *       and prepending that to the asset path (resolving `../` patterns in the mean time).
81
     */
82
    protected function storeAsset()
83
    {
84
        if (!$this->visitor instanceof Discover) {
85
            return;
86
        }
87
88
        $assets = $this->getAssetManager();
89
        $project_root = $assets->getProjectRoot();
90
        $asset_path = trim($this->node->parameters);
91
        $file_path = $this->visitor->getDocument()->getFile()->getRealPath();
92
93
        // get source path
94
        $source = ($asset_path[0] !== '/')
95
            ? dirname($file_path) . '/' . $asset_path
96
            : $project_root . $asset_path;
97
98
        // get destination path
99
        $destination = ($asset_path[0] !== '/')
100
            ? substr(dirname($file_path) . '/' . $asset_path, strlen($project_root))
101
            : substr($asset_path, 1);
102
103
        // set asset
104
        $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@domain'); // This line has a side-effect (it changes an
                                 // instance variable).
Loading history...
105
    }
106
107
    /**
108
     * Returns the asset manager.
109
     *
110
     * @return Assets
111
     */
112
    protected function getAssetManager()
113
    {
114
        return $this->visitor->getDocument()->getConverter()->getAssets();
115
    }
116
}
117