AbstractJsonRepository::contains() - Code Metrics - Inspection of "Refactored JsonRepository" - puli/repository - Measure and Improve Code Quality continuously with Scrutinizer

Failed Conditions

Pull Request — 1.0 (#79)

by Bernhard

created 2015-12-31 12:07 UTC

AbstractJsonRepository::contains() A

↳ Parent: AbstractJsonRepository

Complexity

Conditions	2
Paths	2

Size

Total Lines	14
Code Lines	7

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	8
CRAP Score	2

Importance

Changes	1
Bugs	0	Features	0

Metric	Value
c	1
b	0
f	0
dl	0
loc	14
ccs	8
cts	8
cp	1
rs	9.4286
cc	2
eloc	7
nc	2
nop	2
crap	2

<?php

/*
 * This file is part of the puli/repository package.
 *
 * (c) Bernhard Schussek <[email protected]>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Puli\Repository;

use Puli\Repository\Api\ChangeStream\ChangeStream;
use Puli\Repository\Api\Resource\FilesystemResource;
use Puli\Repository\Api\Resource\PuliResource;
use Puli\Repository\Api\ResourceCollection;
use Puli\Repository\Api\ResourceNotFoundException;
use Puli\Repository\Api\UnsupportedResourceException;
use Puli\Repository\Resource\Collection\ArrayResourceCollection;
use Puli\Repository\Resource\DirectoryResource;
use Puli\Repository\Resource\FileResource;
use Puli\Repository\Resource\GenericResource;
use Puli\Repository\Resource\LinkResource;
use RuntimeException;
use Webmozart\Assert\Assert;
use Webmozart\Json\JsonDecoder;
use Webmozart\Json\JsonEncoder;
use Webmozart\PathUtil\Path;

/**
 * Abstract base for Path mapping repositories.
 *
 * @since  1.0
 *
 * @author Bernhard Schussek <[email protected]>
 * @author Titouan Galopin <[email protected]>
 */
abstract class AbstractJsonRepository extends AbstractEditableRepository
{
    /**
     * @var array
     */
    protected $json;

    /**
     * @var string
     */
    protected $baseDirectory;

    /**
     * @var string
     */
    private $path;

    /**
     * @var string
     */
    private $schemaPath;

    /**
     * @var JsonEncoder
     */
    private $encoder;

    /**
     * Creates a new repository.
     *
     * @param string            $path          The path to the JSON file. If
     *                                         relative, it must be relative to
     *                                         the base directory.
     * @param string            $baseDirectory The base directory of the store.
     *                                         Paths inside that directory are
     *                                         stored as relative paths. Paths
     *                                         outside that directory are stored
     *                                         as absolute paths.
     * @param bool              $validateJson  Whether to validate the JSON file
     *                                         against the schema. Slow but
     *                                         spots problems.
     * @param ChangeStream|null $changeStream  If provided, the repository will
     *                                         append resource changes to this
     *                                         change stream.
     */
    public function __construct($path, $baseDirectory, $validateJson = false, ChangeStream $changeStream = null)
    {
        parent::__construct($changeStream);

        $this->baseDirectory = $baseDirectory;
        $this->path = Path::makeAbsolute($path, $baseDirectory);
        $this->encoder = new JsonEncoder();

        if ($validateJson) {
            $this->schemaPath = realpath(__DIR__.'/../res/schema/path-mappings-schema-1.0.json');
        }
    }

    /**
     * {@inheritdoc}
     */
    public function add($path, $resource)
    {
        if (null === $this->json) {
            $this->load();
        }

        $path = $this->sanitizePath($path);

        if ($resource instanceof ResourceCollection) {

            $this->ensureDirectoryExists($path);

            foreach ($resource as $child) {
                $this->addResource($path.'/'.$child->getName(), $child);
            }

            $this->flush();

            return;
        }

        $this->ensureDirectoryExists(Path::getDirectory($path));

        $this->addResource($path, $resource);
function acceptsInteger($int) { }

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

// Instead of
acceptsInteger($x);

// we recommend to use
acceptsInteger((integer) $x);

        $this->flush();
    }

    /**
     * {@inheritdoc}
     */
    public function get($path)
    {
        if (null === $this->json) {
            $this->load();
        }

        $path = $this->sanitizePath($path);
        $references = $this->getReferencesForPath($path);

        // Might be null, don't use isset()
        if (array_key_exists($path, $references)) {
            return $this->createResource($path, $references[$path]);
        }

        throw ResourceNotFoundException::forPath($path);
    }

    /**
     * {@inheritdoc}
     */
    public function find($query, $language = 'glob')
    {
        if (null === $this->json) {
            $this->load();
        }

        $this->validateSearchLanguage($language);
        $query = $this->sanitizePath($query);
        $results = $this->createResources($this->getReferencesForGlob($query));

        ksort($results);

        return new ArrayResourceCollection(array_values($results));
    }

    /**
     * {@inheritdoc}
     */
    public function contains($query, $language = 'glob')
    {
        if (null === $this->json) {
            $this->load();
        }

        $this->validateSearchLanguage($language);
        $query = $this->sanitizePath($query);

        // Stop on the first result
        $results = $this->getReferencesForGlob($query, true);

        return !empty($results);
    }

    /**
     * {@inheritdoc}
     */
    public function remove($query, $language = 'glob')
    {
        if (null === $this->json) {
            $this->load();
        }

        $this->validateSearchLanguage($language);
        $query = $this->sanitizePath($query);

        Assert::notEmpty(trim($query, '/'), 'The root directory cannot be removed.');

        $removed = $this->removeReferences($query);

        $this->flush();

        return $removed;
    }

    /**
     * {@inheritdoc}
     */
    public function clear()
    {
        if (null === $this->json) {
            $this->load();
        }

        // Subtract root which is not deleted
        $removed = count($this->getReferencesForRegex('/', '~.~')) - 1;

        $this->json = array();

        $this->flush();

        return $removed;
    }

    /**
     * {@inheritdoc}
     */
    public function listChildren($path)
    {
        if (null === $this->json) {
            $this->load();
        }

        $path = $this->sanitizePath($path);
        $results = $this->createResources($this->getReferencesInDirectory($path));

        if (empty($results)) {
            $pathResults = $this->getReferencesForPath($path);

            if (empty($pathResults)) {
                throw ResourceNotFoundException::forPath($path);
            }
        }

        ksort($results);

        return new ArrayResourceCollection(array_values($results));
    }

    /**
     * {@inheritdoc}
     */
    public function hasChildren($path)
    {
        if (null === $this->json) {
            $this->load();
        }

        $path = $this->sanitizePath($path);

        // Stop on the first result
        $results = $this->getReferencesInDirectory($path, true);

        if (empty($results)) {
            $pathResults = $this->getReferencesForPath($path);

            if (empty($pathResults)) {
                throw ResourceNotFoundException::forPath($path);
            }

            return false;
        }

        return true;
    }

    /**
     * Inserts a path reference into the JSON file.
     *
     * The path reference can be:
     *
     *  * a link starting with `@`
     *  * an absolute filesystem path
     *
     * @param string      $path      The Puli path.
     * @param string|null $reference The path reference.
     */
    abstract protected function insertReference($path, $reference);


    /**
     * Removes all path references matching the given glob from the JSON file.
     *
     * @param string $glob The glob for a list of Puli paths.
     */
    abstract protected function removeReferences($glob);


    /**
     * Returns the references for a given Puli path.
     *
     * Each reference returned by this method can be:
     *
     *  * `null`
     *  * a link starting with `@`
     *  * an absolute filesystem path
     *
     * The result has either one entry or none, if no path was found. The key
     * of the single entry is the path passed to this method.
     *
     * @param string $path The Puli path.
     *
     * @return string[]|null[] A one-level array of references with Puli paths
     *                         as keys. The array has at most one entry.
     */
    abstract protected function getReferencesForPath($path);

    /**
     * Returns the references matching a given Puli path glob.
     *
     * Each reference returned by this method can be:
     *
     *  * `null`
     *  * a link starting with `@`
     *  * an absolute filesystem path
     *
     * The keys of the returned array are Puli paths. Their order is undefined.
     *
     * @param string $glob        The glob.
     * @param bool   $stopOnFirst Whether to stop after finding a first result.
     *
     * @return string[]|null[] A one-level array of references with Puli paths
     *                         as keys.
     */
    abstract protected function getReferencesForGlob($glob, $stopOnFirst = false);

    /**
     * Returns the references matching a given Puli path regular expression.
     *
     * Each reference returned by this method can be:
     *
     *  * `null`
     *  * a link starting with `@`
     *  * an absolute filesystem path
     *
     * The keys of the returned array are Puli paths. Their order is undefined.
     *
     * @param string $staticPrefix The static prefix of all Puli paths matching
     *                             the regular expression.
     * @param string $regex        The regular expression.
     * @param bool   $stopOnFirst  Whether to stop after finding a first result.
     *
     * @return string[]|null[] A one-level array of references with Puli paths
     *                         as keys.
     */
    abstract protected function getReferencesForRegex($staticPrefix, $regex, $stopOnFirst = false);

    /**
     * Returns the references in a given Puli path.
     *
     * Each reference returned by this method can be:
     *
     *  * `null`
     *  * a link starting with `@`
     *  * an absolute filesystem path
     *
     * The keys of the returned array are Puli paths. Their order is undefined.
     *
     * @param string $path        The Puli path.
     * @param bool   $stopOnFirst Whether to stop after finding a first result.
     *
     * @return string[]|null[] A one-level array of references with Puli paths
     *                         as keys.
     */
    abstract protected function getReferencesInDirectory($path, $stopOnFirst = false);

    /**
     * Adds a filesystem resource to the JSON file.
     *
     * @param string             $path     The Puli path.
     * @param FilesystemResource $resource The resource to add.
     */
    protected function addFilesystemResource($path, FilesystemResource $resource)
    {
        $resource->attachTo($this, $path);

        $this->insertReference($path, $resource->getFilesystemPath());

        $this->appendToChangeStream($resource);
    }

    /**
     * Loads the JSON file.
     */
    protected function load()
    {
        $decoder = new JsonDecoder();

        $this->json = file_exists($this->path)
            ? (array) $decoder->decodeFile($this->path, $this->schemaPath)
            : array();

        if (isset($this->json['_order'])) {
            $this->json['_order'] = (array) $this->json['_order'];

            foreach ($this->json['_order'] as $path => $entries) {
                foreach ($entries as $key => $entry) {
                    $this->json['_order'][$path][$key] = (array) $entry;
                }
            }
        }

        // The root node always exists
        if (!isset($this->json['/'])) {
            $this->json['/'] = null;
        }

        // Make sure the JSON is sorted in reverse order
        krsort($this->json);
    }

    /**
     * Writes the JSON file.
     */
    protected function flush()
    {
        // The root node always exists
        if (!isset($this->json['/'])) {
            $this->json['/'] = null;
        }

        // Always save in reverse order
        krsort($this->json);

        // Comply to schema
        $json = (object) $this->json;

        if (isset($json->{'_order'})) {
            foreach ($json->{'_order'} as $path => $entries) {
                foreach ($entries as $key => $entry) {
                    $json->{'_order'}[$path][$key] = (object) $entry;
                }
            }

            $json->{'_order'} = (object) $json->{'_order'};
        }

        $this->encoder->encodeFile($json, $this->path, $this->schemaPath);
    }

    /**
     * Returns whether a reference contains a link.
     *
     * @param string $reference The reference.
     *
     * @return bool Whether the reference contains a link.
     */
    protected function isLinkReference($reference)
    {
        return isset($reference{0}) && '@' === $reference{0};
    }

    /**
     * Returns whether a reference contains an absolute or relative filesystem
     * path.
     *
     * @param string $reference The reference.
     *
     * @return bool Whether the reference contains a filesystem path.
     */
    protected function isFilesystemReference($reference)
    {
        return null !== $reference && !$this->isLinkReference($reference);
    }

    /**
     * Turns a reference into a resource.
     *
     * @param string      $path      The Puli path.
     * @param string|null $reference The reference.
     *
     * @return PuliResource The resource.

     */
    protected function createResource($path, $reference)
    {
        if (null === $reference) {
            $resource = new GenericResource();
        } elseif (isset($reference{0}) && '@' === $reference{0}) {
            $resource = new LinkResource(substr($reference, 1));
        } elseif (is_dir($reference)) {
            $resource = new DirectoryResource($reference);
        } elseif (is_file($reference)) {
            $resource = new FileResource($reference);
        } else {
            throw new RuntimeException(sprintf(
                'Trying to create a FilesystemResource on a non-existing file or directory "%s"',
                $reference
            ));
        }

        $resource->attachTo($this, $path);

        return $resource;
    }

    /**
     * Turns a list of references into a list of resources.
     *
     * The references are expected to be in the format returned by
     * {@link getReferencesForPath()}, {@link getReferencesForGlob()} and
     * {@link getReferencesInDirectory()}.
     *
     * The result contains Puli paths as keys and {@link PuliResource}
     * implementations as values. The order of the results is undefined.
     *
     * @param string[]|null[] $references The references indexed by Puli paths.
     *
     * @return array

     */
    private function createResources(array $references)
    {
        foreach ($references as $path => $reference) {
            $references[$path] = $this->createResource($path, $reference);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

$x = returnsDifferentValues($y);
if (is_array($x)) {
    // $x is an array.
}
        }

        return $references;
    }

    /**
     * Adds all ancestor directories of a path to the repository.
     *
     * @param string $path A Puli path.
     */
    private function ensureDirectoryExists($path)
    {
        if (array_key_exists($path, $this->json)) {
            return;
        }

        // Recursively initialize parent directories
        if ('/' !== $path) {
            $this->ensureDirectoryExists(Path::getDirectory($path));
        }

        $this->json[$path] = null;
    }

    /**
     * Adds a resource to the repository.
     *
     * @param string                          $path     The Puli path to add the
     *                                                  resource at.
     * @param FilesystemResource|LinkResource $resource The resource to add.
     */
    private function addResource($path, $resource)
    {
        if (!$resource instanceof FilesystemResource && !$resource instanceof LinkResource) {
            throw new UnsupportedResourceException(sprintf(
                'The %s only supports adding FilesystemResource and '.
                'LinkedResource instances. Got: %s',
                // Get the short class name
                $this->getShortClassName(get_class($this)),
                $this->getShortClassName(get_class($resource))
            ));
        }

        // Don't modify resources attached to other repositories
        if ($resource->isAttached()) {
            $resource = clone $resource;
        }

        if ($resource instanceof LinkResource) {
            $resource->attachTo($this, $path);

            $this->insertReference($path, '@'.$resource->getTargetPath());

            $this->appendToChangeStream($resource);
        } else {
            // Extension point for the optimized repository
            $this->addFilesystemResource($path, $resource);
        }
    }

    /**
     * Returns the short name of a fully-qualified class name.
     *
     * @param string $className The fully-qualified class name.
     *
     * @return string The short class name.
     */
    private function getShortClassName($className)
    {
        if (false !== ($pos = strrpos($className, '\\'))) {
            return substr($className, $pos + 1);
        }

        return $className;
    }
}


1			<?php
2
3			/*
4			* This file is part of the puli/repository package.
5			*
6			* (c) Bernhard Schussek <[email protected]>
7			*
8			* For the full copyright and license information, please view the LICENSE
9			* file that was distributed with this source code.
10			*/
11
12			namespace Puli\Repository;
13
14			use Puli\Repository\Api\ChangeStream\ChangeStream;
15			use Puli\Repository\Api\Resource\FilesystemResource;
16			use Puli\Repository\Api\Resource\PuliResource;
17			use Puli\Repository\Api\ResourceCollection;
18			use Puli\Repository\Api\ResourceNotFoundException;
19			use Puli\Repository\Api\UnsupportedResourceException;
20			use Puli\Repository\Resource\Collection\ArrayResourceCollection;
21			use Puli\Repository\Resource\DirectoryResource;
22			use Puli\Repository\Resource\FileResource;
23			use Puli\Repository\Resource\GenericResource;
24			use Puli\Repository\Resource\LinkResource;
25			use RuntimeException;
26			use Webmozart\Assert\Assert;
27			use Webmozart\Json\JsonDecoder;
28			use Webmozart\Json\JsonEncoder;
29			use Webmozart\PathUtil\Path;
30
31			/**
32			* Abstract base for Path mapping repositories.
33			*
34			* @since 1.0
35			*
36			* @author Bernhard Schussek <[email protected]>
37			* @author Titouan Galopin <[email protected]>
38			*/
39			abstract class AbstractJsonRepository extends AbstractEditableRepository
40			{
41			/**
42			* @var array
43			*/
44			protected $json;
45
46			/**
47			* @var string
48			*/
49			protected $baseDirectory;
50
51			/**
52			* @var string
53			*/
54			private $path;
55
56			/**
57			* @var string
58			*/
59			private $schemaPath;
60
61			/**
62			* @var JsonEncoder
63			*/
64			private $encoder;
65
66			/**
67			* Creates a new repository.
68			*
69			* @param string $path The path to the JSON file. If
70			* relative, it must be relative to
71			* the base directory.
72			* @param string $baseDirectory The base directory of the store.
73			* Paths inside that directory are
74			* stored as relative paths. Paths
75			* outside that directory are stored
76			* as absolute paths.
77			* @param bool $validateJson Whether to validate the JSON file
78			* against the schema. Slow but
79			* spots problems.
80			* @param ChangeStream\|null $changeStream If provided, the repository will
81			* append resource changes to this
82			* change stream.
83			*/
84	187		public function __construct($path, $baseDirectory, $validateJson = false, ChangeStream $changeStream = null)
85			{
86	187		parent::__construct($changeStream);
87
88	187		$this->baseDirectory = $baseDirectory;
89	187		$this->path = Path::makeAbsolute($path, $baseDirectory);
90	187		$this->encoder = new JsonEncoder();
91
92	187		if ($validateJson) {
93	187		$this->schemaPath = realpath(__DIR__.'/../res/schema/path-mappings-schema-1.0.json');
94	187		}
95	187		}
96
97			/**
98			* {@inheritdoc}
99			*/
100	162		public function add($path, $resource)
101			{
102	162		if (null === $this->json) {
103	162		$this->load();
104	162		}
105
106	162		$path = $this->sanitizePath($path);
107
108	156	View Code Duplication	if ($resource instanceof ResourceCollection) {
			0 ignored issues – show Duplication introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report This code seems to be duplicated across your project. Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation. You can also find more detailed suggestions in the “Code” section of your repository. Loading history...
109	2		$this->ensureDirectoryExists($path);
110
111	2		foreach ($resource as $child) {
112	2		$this->addResource($path.'/'.$child->getName(), $child);
113	2		}
114
115	2		$this->flush();
116
117	2		return;
118			}
119
120	154		$this->ensureDirectoryExists(Path::getDirectory($path));
121
122	154		$this->addResource($path, $resource);
			0 ignored issues – show Documentation introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report `$resource` is of type `object<Puli\Repository\Api\Resource\PuliResource>`, but the function expects a `object<Puli\Repository\A...\Resource\LinkResource>`. 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...
123
124	152		$this->flush();
125	152		}
126
127			/**
128			* {@inheritdoc}
129			*/
130	80		public function get($path)
131			{
132	80		if (null === $this->json) {
133	21		$this->load();
134	21		}
135
136	80		$path = $this->sanitizePath($path);
137	74		$references = $this->getReferencesForPath($path);
138
139			// Might be null, don't use isset()
140	74		if (array_key_exists($path, $references)) {
141	70		return $this->createResource($path, $references[$path]);
142			}
143
144	4		throw ResourceNotFoundException::forPath($path);
145			}
146
147			/**
148			* {@inheritdoc}
149			*/
150	24		public function find($query, $language = 'glob')
151			{
152	24		if (null === $this->json) {
153	2		$this->load();
154	2		}
155
156	24		$this->validateSearchLanguage($language);
157	22		$query = $this->sanitizePath($query);
158	16		$results = $this->createResources($this->getReferencesForGlob($query));
159
160	16		ksort($results);
161
162	16		return new ArrayResourceCollection(array_values($results));
163			}
164
165			/**
166			* {@inheritdoc}
167			*/
168	40		public function contains($query, $language = 'glob')
169			{
170	40		if (null === $this->json) {
171	21		$this->load();
172	21		}
173
174	40		$this->validateSearchLanguage($language);
175	38		$query = $this->sanitizePath($query);
176
177			// Stop on the first result
178	32		$results = $this->getReferencesForGlob($query, true);
179
180	32		return !empty($results);
181			}
182
183			/**
184			* {@inheritdoc}
185			*/
186	75		public function remove($query, $language = 'glob')
187	75		{
188	25		if (null === $this->json) {
189	11		$this->load();
190	11		}
191
192	25		$this->validateSearchLanguage($language);
193	24		$query = $this->sanitizePath($query);
194
195	18		Assert::notEmpty(trim($query, '/'), 'The root directory cannot be removed.');
196
197	14		$removed = $this->removeReferences($query);
198
199	14		$this->flush();
200
201	14		return $removed;
202			}
203
204			/**
205			* {@inheritdoc}
206			*/
207	2		public function clear()
208			{
209	2		if (null === $this->json) {
210			$this->load();
211			}
212
213			// Subtract root which is not deleted
214	2		$removed = count($this->getReferencesForRegex('/', '~.~')) - 1;
215
216	2		$this->json = array();
217
218	2		$this->flush();
219
220	2		return $removed;
221			}
222
223			/**
224			* {@inheritdoc}
225			*/
226	27		public function listChildren($path)
227			{
228	27		if (null === $this->json) {
229	3		$this->load();
230	3		}
231
232	27		$path = $this->sanitizePath($path);
233	21		$results = $this->createResources($this->getReferencesInDirectory($path));
234
235	21		if (empty($results)) {
236	6		$pathResults = $this->getReferencesForPath($path);
237
238	6		if (empty($pathResults)) {
239	2		throw ResourceNotFoundException::forPath($path);
240			}
241	4		}
242
243	19		ksort($results);
244
245	19		return new ArrayResourceCollection(array_values($results));
246			}
247
248			/**
249			* {@inheritdoc}
250			*/
251	14		public function hasChildren($path)
252			{
253	14		if (null === $this->json) {
254			$this->load();
255			}
256
257	14		$path = $this->sanitizePath($path);
258
259			// Stop on the first result
260	8		$results = $this->getReferencesInDirectory($path, true);
261
262	8		if (empty($results)) {
263	4		$pathResults = $this->getReferencesForPath($path);
264
265	4		if (empty($pathResults)) {
266	2		throw ResourceNotFoundException::forPath($path);
267			}
268
269	2		return false;
270			}
271
272	6		return true;
273			}
274
275			/**
276			* Inserts a path reference into the JSON file.
277			*
278			* The path reference can be:
279			*
280			* * a link starting with `@`
281			* * an absolute filesystem path
282			*
283			* @param string $path The Puli path.
284			* @param string\|null $reference The path reference.
285			*/
286			abstract protected function insertReference($path, $reference);
			1 ignored issue – show Documentation introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report For interfaces and abstract methods it is generally a good practice to add a `@return` annotation even if it is just `@return void` or `@return null`, so that implementors know what to do in the overridden method. For interface and abstract methods, it is impossible to infer the return type from the immediate code. In these cases, it is generally advisible to explicitly annotate these methods with a `@return` doc comment to communicate to implementors of these methods what they are expected to return. Loading history...
287
288			/**
289			* Removes all path references matching the given glob from the JSON file.
290			*
291			* @param string $glob The glob for a list of Puli paths.
292			*/
293			abstract protected function removeReferences($glob);
			1 ignored issue – show Documentation introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report For interfaces and abstract methods it is generally a good practice to add a `@return` annotation even if it is just `@return void` or `@return null`, so that implementors know what to do in the overridden method. For interface and abstract methods, it is impossible to infer the return type from the immediate code. In these cases, it is generally advisible to explicitly annotate these methods with a `@return` doc comment to communicate to implementors of these methods what they are expected to return. Loading history...
294
295			/**
296			* Returns the references for a given Puli path.
297			*
298			* Each reference returned by this method can be:
299			*
300			* * `null`
301			* * a link starting with `@`
302			* * an absolute filesystem path
303			*
304			* The result has either one entry or none, if no path was found. The key
305			* of the single entry is the path passed to this method.
306			*
307			* @param string $path The Puli path.
308			*
309			* @return string[]\|null[] A one-level array of references with Puli paths
310			* as keys. The array has at most one entry.
311			*/
312			abstract protected function getReferencesForPath($path);
313
314			/**
315			* Returns the references matching a given Puli path glob.
316			*
317			* Each reference returned by this method can be:
318			*
319			* * `null`
320			* * a link starting with `@`
321			* * an absolute filesystem path
322			*
323			* The keys of the returned array are Puli paths. Their order is undefined.
324			*
325			* @param string $glob The glob.
326			* @param bool $stopOnFirst Whether to stop after finding a first result.
327			*
328			* @return string[]\|null[] A one-level array of references with Puli paths
329			* as keys.
330			*/
331			abstract protected function getReferencesForGlob($glob, $stopOnFirst = false);
332
333			/**
334			* Returns the references matching a given Puli path regular expression.
335			*
336			* Each reference returned by this method can be:
337			*
338			* * `null`
339			* * a link starting with `@`
340			* * an absolute filesystem path
341			*
342			* The keys of the returned array are Puli paths. Their order is undefined.
343			*
344			* @param string $staticPrefix The static prefix of all Puli paths matching
345			* the regular expression.
346			* @param string $regex The regular expression.
347			* @param bool $stopOnFirst Whether to stop after finding a first result.
348			*
349			* @return string[]\|null[] A one-level array of references with Puli paths
350			* as keys.
351			*/
352			abstract protected function getReferencesForRegex($staticPrefix, $regex, $stopOnFirst = false);
353
354			/**
355			* Returns the references in a given Puli path.
356			*
357			* Each reference returned by this method can be:
358			*
359			* * `null`
360			* * a link starting with `@`
361			* * an absolute filesystem path
362			*
363			* The keys of the returned array are Puli paths. Their order is undefined.
364			*
365			* @param string $path The Puli path.
366			* @param bool $stopOnFirst Whether to stop after finding a first result.
367			*
368			* @return string[]\|null[] A one-level array of references with Puli paths
369			* as keys.
370			*/
371			abstract protected function getReferencesInDirectory($path, $stopOnFirst = false);
372
373			/**
374			* Adds a filesystem resource to the JSON file.
375			*
376			* @param string $path The Puli path.
377			* @param FilesystemResource $resource The resource to add.
378			*/
379	154		protected function addFilesystemResource($path, FilesystemResource $resource)
380			{
381	154		$resource->attachTo($this, $path);
382
383	154		$this->insertReference($path, $resource->getFilesystemPath());
384
385	154		$this->appendToChangeStream($resource);
386	154		}
387
388			/**
389			* Loads the JSON file.
390			*/
391	185		protected function load()
392			{
393	185		$decoder = new JsonDecoder();
394
395	185		$this->json = file_exists($this->path)
396	185		? (array) $decoder->decodeFile($this->path, $this->schemaPath)
397	185		: array();
398
399	185		if (isset($this->json['_order'])) {
400	4		$this->json['_order'] = (array) $this->json['_order'];
401
402	4		foreach ($this->json['_order'] as $path => $entries) {
403	4		foreach ($entries as $key => $entry) {
404	4		$this->json['_order'][$path][$key] = (array) $entry;
405	4		}
406	4		}
407	4		}
408
409			// The root node always exists
410	185		if (!isset($this->json['/'])) {
411	185		$this->json['/'] = null;
412	185		}
413
414			// Make sure the JSON is sorted in reverse order
415	185		krsort($this->json);
416	185		}
417
418			/**
419			* Writes the JSON file.
420			*/
421	154		protected function flush()
422			{
423			// The root node always exists
424	154		if (!isset($this->json['/'])) {
425	58		$this->json['/'] = null;
426	58		}
427
428			// Always save in reverse order
429	154		krsort($this->json);
430
431			// Comply to schema
432	154		$json = (object) $this->json;
433
434	154		if (isset($json->{'_order'})) {
435	5		foreach ($json->{'_order'} as $path => $entries) {
436	5		foreach ($entries as $key => $entry) {
437	5		$json->{'_order'}[$path][$key] = (object) $entry;
438	5		}
439	5		}
440
441	5		$json->{'_order'} = (object) $json->{'_order'};
442	5		}
443
444	154		$this->encoder->encodeFile($json, $this->path, $this->schemaPath);
445	154		}
446
447			/**
448			* Returns whether a reference contains a link.
449			*
450			* @param string $reference The reference.
451			*
452			* @return bool Whether the reference contains a link.
453			*/
454	133		protected function isLinkReference($reference)
455			{
456	133		return isset($reference{0}) && '@' === $reference{0};
457			}
458
459			/**
460			* Returns whether a reference contains an absolute or relative filesystem
461			* path.
462			*
463			* @param string $reference The reference.
464			*
465			* @return bool Whether the reference contains a filesystem path.
466			*/
467	134		protected function isFilesystemReference($reference)
468			{
469	134		return null !== $reference && !$this->isLinkReference($reference);
470			}
471
472			/**
473			* Turns a reference into a resource.
474			*
475			* @param string $path The Puli path.
476			* @param string\|null $reference The reference.
477			*
478			* @return PuliResource The resource.
			0 ignored issues – show Documentation introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report Consider making the return type a bit more specific; maybe use `GenericResource`. This check looks for the generic type `array` as a return type and suggests a more specific type. This type is inferred from the actual code. Loading history...
479			*/
480	81		protected function createResource($path, $reference)
481			{
482	81		if (null === $reference) {
483	3		$resource = new GenericResource();
484	81		} elseif (isset($reference{0}) && '@' === $reference{0}) {
485	4		$resource = new LinkResource(substr($reference, 1));
486	79		} elseif (is_dir($reference)) {
487	43		$resource = new DirectoryResource($reference);
488	79		} elseif (is_file($reference)) {
489	56		$resource = new FileResource($reference);
490	56		} else {
491			throw new RuntimeException(sprintf(
492			'Trying to create a FilesystemResource on a non-existing file or directory "%s"',
493			$reference
494			));
495			}
496
497	81		$resource->attachTo($this, $path);
498
499	81		return $resource;
500			}
501
502			/**
503			* Turns a list of references into a list of resources.
504			*
505			* The references are expected to be in the format returned by
506			* {@link getReferencesForPath()}, {@link getReferencesForGlob()} and
507			* {@link getReferencesInDirectory()}.
508			*
509			* The result contains Puli paths as keys and {@link PuliResource}
510			* implementations as values. The order of the results is undefined.
511			*
512			* @param string[]\|null[] $references The references indexed by Puli paths.
513			*
514			* @return array
			0 ignored issues – show Documentation introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report Consider making the return type a bit more specific; maybe use `array<string\|null\|GenericResource>`. This check looks for the generic type `array` as a return type and suggests a more specific type. This type is inferred from the actual code. Loading history...
515			*/
516	37		private function createResources(array $references)
517			{
518	37		foreach ($references as $path => $reference) {
519	29		$references[$path] = $this->createResource($path, $reference);
			0 ignored issues – show Bug introduced 2015-12-31 10:06 UTC by Report Bug Copy Issue Report It seems like `$reference` defined by `$reference` on line `518` can also be of type `object<Puli\Repository\Resource\GenericResource>`; however, `Puli\Repository\Abstract...itory::createResource()` does only seem to accept `string\|null`, maybe add an additional type check? If a method or function can return multiple different values and unless you are sure that you only can receive a single value in this context, we recommend to add an additional type check: /** * @return array\|string */ function returnsDifferentValues($x) { if ($x) { return 'foo'; } return array(); } $x = returnsDifferentValues($y); if (is_array($x)) { // $x is an array. } If this a common case that PHP Analyzer should handle natively, please let us know by opening an issue. Loading history...
520	37		}
521
522	37		return $references;
523			}
524
525			/**
526			* Adds all ancestor directories of a path to the repository.
527			*
528			* @param string $path A Puli path.
529			*/
530	156		private function ensureDirectoryExists($path)
531			{
532	156		if (array_key_exists($path, $this->json)) {
533	156		return;
534			}
535
536			// Recursively initialize parent directories
537	50		if ('/' !== $path) {
538	50		$this->ensureDirectoryExists(Path::getDirectory($path));
539	50		}
540
541	50		$this->json[$path] = null;
542	50		}
543
544			/**
545			* Adds a resource to the repository.
546			*
547			* @param string $path The Puli path to add the
548			* resource at.
549			* @param FilesystemResource\|LinkResource $resource The resource to add.
550			*/
551	156		private function addResource($path, $resource)
552			{
553	156		if (!$resource instanceof FilesystemResource && !$resource instanceof LinkResource) {
554	2		throw new UnsupportedResourceException(sprintf(
555			'The %s only supports adding FilesystemResource and '.
556	2		'LinkedResource instances. Got: %s',
557			// Get the short class name
558	2		$this->getShortClassName(get_class($this)),
559	2		$this->getShortClassName(get_class($resource))
560	2		));
561			}
562
563			// Don't modify resources attached to other repositories
564	154		if ($resource->isAttached()) {
565	4		$resource = clone $resource;
566	4		}
567
568	154		if ($resource instanceof LinkResource) {
569	4		$resource->attachTo($this, $path);
570
571	4		$this->insertReference($path, '@'.$resource->getTargetPath());
572
573	4		$this->appendToChangeStream($resource);
574	4		} else {
575			// Extension point for the optimized repository
576	154		$this->addFilesystemResource($path, $resource);
577			}
578	154		}
579
580			/**
581			* Returns the short name of a fully-qualified class name.
582			*
583			* @param string $className The fully-qualified class name.
584			*
585			* @return string The short class name.
586			*/
587	2		private function getShortClassName($className)
588			{
589	2		if (false !== ($pos = strrpos($className, '\\'))) {
590	2		return substr($className, $pos + 1);
591			}
592
593	2		return $className;
594			}
595			}
596

puli / repository

Pull Request — 1.0 (#79)

AbstractJsonRepository::contains() A

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like