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

Plugin/Scrybe/Converter/BaseConverter.php (1 issue)

useless, side-effect free code.

Unused Code Minor

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;
17
18
use Monolog\Logger;
19
use phpDocumentor\Plugin\Scrybe\Converter\Format\Collection;
20
use phpDocumentor\Plugin\Scrybe\Template\TemplateInterface;
21
use SplFileInfo;
22
23
abstract class BaseConverter implements ConverterInterface
24
{
25
    /** @var Definition\Definition */
26
    protected $definition = null;
27
28
    /** @var string[] */
29
    protected $options = [];
30
31
    /** @var Collection */
32
    protected $fileset;
33
34
    /** @var Metadata\Assets */
35
    protected $assets;
36
37
    /** @var Metadata\TableOfContents */
38
    protected $toc;
39
40
    /** @var Metadata\Glossary */
41
    protected $glossary;
42
43
    /** @var Logger */
44
    protected $logger;
45
46
    /**
47
     * Initializes this converter and sets the definition.
48
     */
49
    public function __construct(
50
        Definition\Definition $definition,
51
        Metadata\Assets $assets,
52
        Metadata\TableOfContents $tableOfContents,
53
        Metadata\Glossary $glossary
54
    ) {
55
        $this->definition = $definition;
56
        $this->assets = $assets;
57
        $this->toc = $tableOfContents;
58
        $this->glossary = $glossary;
59
    }
60
61
    /**
62
     * Set a logger for this converter.
63
     */
64
    public function setLogger(Logger $logger): void
65
    {
66
        $this->logger = $logger;
67
    }
68
69
    /**
70
     * Returns the AssetManager that keep track of which assets are used.
71
     */
72
    public function getAssets(): Metadata\Assets
73
    {
74
        return $this->assets;
75
    }
76
77
    /**
78
     * Returns the table of contents object that keeps track of all
79
     * headings and their titles.
80
     */
81
    public function getTableOfContents(): Metadata\TableOfContents
82
    {
83
        return $this->toc;
84
    }
85
86
    /**
87
     * Returns the glossary object that keeps track of all the glossary terms
88
     * that have been provided.
89
     */
90
    public function getGlossary(): Metadata\Glossary
91
    {
92
        return $this->glossary;
93
    }
94
95
    /**
96
     * Returns the definition for this Converter.
97
     */
98
    public function getDefinition(): Definition\Definition
99
    {
100
        return $this->definition;
101
    }
102
103
    /**
104
     * Sets an option with the given name.
105
     */
106
    public function setOption(string $name, string $value): void
107
    {
108
        $this->options[$name] = $value;
109
    }
110
111
    /**
112
     * Returns the option with the given name or null if the option does not
113
     * exist.
114
     */
115
    public function getOption(string $name): ?string
116
    {
117
        return $this->options[$name] ?? null;
118
    }
119
120
    /**
121
     * Configures and initializes the subcomponents specific to this converter.
122
     */
123
    public function configure(): void
124
    {
125
    }
126
127
    /**
128
     * Discovers the data that is spanning all files.
129
     *
130
     * This method tries to find any data that needs to be collected before
131
     * the actual creation and substitution phase begins.
132
     *
133
     * Examples of data that needs to be collected during an initial phase is
134
     * a table of contents, list of document titles for references, assets
135
     * and more.
136
     *
137
     * @see manual://extending#build_cycle for more information regarding the
138
     *     build process.
139
     */
140
    abstract protected function discover(): void;
141
142
    /**
143
     * Converts the input files into one or more output files in the intended
144
     * format.
145
     *
146
     * This method reads the files, converts them into the correct format and
147
     * returns the contents of the conversion.
148
     *
149
     * The template is used to decorate the individual files and can be obtained
150
     * using the `\phpDocumentor\Plugin\Scrybe\Template\Factory` class.
151
     *
152
     * @see manual://extending#build_cycle for more information regarding the
153
     * build process.
154
     * @return string[]|null The contents of the resulting file(s) or null if
155
     * the files are written directly to file.
156
     */
157
    abstract protected function create(TemplateInterface $template): ?string;
158
159
    /**
160
     * Converts the given $source using the formats that belong to this
161
     * converter.
162
     *
163
     * This method will return null unless the 'scrybe://result' is used.
164
     *
165
     * @param Collection        $source      Collection of input files.
166
     * @param TemplateInterface $template Template used to decorate the
167
     *     output with.
168
     */
169
    public function convert(Collection $source, TemplateInterface $template): ?string
170
    {
171
        $this->fileset = $source;
172
        $this->assets->setProjectRoot($this->fileset->getProjectRoot());
173
174
        $template->setExtension(current($this->definition->getOutputFormat()->getExtensions()));
175
176
        $this->configure();
177
        $this->discover();
178
179
        $this->addTemplateAssets($template);
180
        $this->setOption('toc', $this->toc);
181
182
        return $this->create($template);
183
    }
184
185
    /**
186
     * Adds the assets of the template to the Assets manager.
187
     */
188
    protected function addTemplateAssets(TemplateInterface $template): void
189
    {
190
        /** @var SplFileInfo $file_info */
191
        foreach ($template->getAssets() as $filename => $file_info) {
192
            $this->assets->set($filename, $file_info->getRelativePathname());
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...
193
        }
194
    }
195
196
    /**
197
     * Returns the filename used for the output path.
198
     */
199
    protected function getDestinationFilename(Metadata\TableOfContents\File $file): string
200
    {
201
        return $this->definition->getOutputFormat()->convertFilename($file->getRealPath());
202
    }
203
204
    /**
205
     * Returns the filename relative to the Project Root of the fileset.
206
     */
207
    public function getDestinationFilenameRelativeToProjectRoot(Metadata\TableOfContents\File $file): string
208
    {
209
        return substr($this->getDestinationFilename($file), strlen($this->fileset->getProjectRoot()));
210
    }
211
212
    /**
213
     * Returns the logger for this converter.
214
     */
215
    protected function getLogger(): Logger
216
    {
217
        return $this->logger;
218
    }
219
}
220