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

Plugin/Scrybe/Converter/BaseConverter.php (6 issues)

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());
0 ignored issues
show
The method getProjectRoot() does not seem to exist on object<phpDocumentor\Plu...rter\Format\Collection>.

This check looks for calls to methods that do not seem to exist on a given type. It looks for the method on the type itself as well as in inherited classes or implemented interfaces.

This is most likely a typographical error or the method has been renamed.

Loading history...
173
174
        $template->setExtension(current($this->definition->getOutputFormat()->getExtensions()));
0 ignored issues
show
It seems like current($this->definitio...mat()->getExtensions()) targeting current() can also be of type false; however, phpDocumentor\Plugin\Scr...terface::setExtension() does only seem to accept string, did you maybe forget to handle an error condition?
Loading history...
175
176
        $this->configure();
177
        $this->discover();
178
179
        $this->addTemplateAssets($template);
180
        $this->setOption('toc', $this->toc);
0 ignored issues
show
$this->toc is of type object<phpDocumentor\Plu...tadata\TableOfContents>, but the function expects a string.

It seems like the type of the argument is not accepted by the function/method which you are calling.

In some cases, in particular if PHP’s automatic type-juggling kicks in this might be fine. In other cases, however this might be a bug.

We suggest to add an explicit type cast like in the following example:

function acceptsInteger($int) { }

$x = '123'; // string "123"

// Instead of
acceptsInteger($x);

// we recommend to use
acceptsInteger((integer) $x);
Loading history...
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());
0 ignored issues
show
The method getRealPath() does not seem to exist on object<phpDocumentor\Plu...a\TableOfContents\File>.

This check looks for calls to methods that do not seem to exist on a given type. It looks for the method on the type itself as well as in inherited classes or implemented interfaces.

This is most likely a typographical error or the method has been renamed.

Loading history...
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()));
0 ignored issues
show
The method getProjectRoot() does not seem to exist on object<phpDocumentor\Plu...rter\Format\Collection>.

This check looks for calls to methods that do not seem to exist on a given type. It looks for the method on the type itself as well as in inherited classes or implemented interfaces.

This is most likely a typographical error or the method has been renamed.

Loading history...
210
    }
211
212
    /**
213
     * Returns the logger for this converter.
214
     */
215
    protected function getLogger(): Logger
216
    {
217
        return $this->logger;
218
    }
219
}
220