allejo\stakx\Manager\TrackingManager

Complexity

Total Complexity

26

Size/Duplication

Total Lines	306
Duplicated Lines	0 %

Coupling/Cohesion

Components	5
Dependencies	4

Test Coverage

Coverage

97.78%

Importance

Changes

0

15 Methods

Rating	Name	Duplication	Size	Complexity
A	saveFolderDefinition()	0	5	1
A	saveTrackerOptions()	0	4	1
A	scanTrackableItems()	0	11	3
A	delArrayFromTracker()	0	13	2
A	delObjectFromTracker()	0	8	1
A	__construct()	0	11	1
A	enableTracking()	0	4	1
A	isHandled()	0	12	3
A	isTracked()	0	4	1
A	createNewItem()	0	4	1
A	refreshItem()	0	4	1
A	addArrayToTracker()	0	13	2
A	addObjectToTracker()	0	9	3
B	getJailedTrackedItems()	0	24	5
	handleTrackableItem()	0	1	?

<?php

/**
 * @copyright 2017 Vladimir Jimenez
 * @license   https://github.com/allejo/stakx/blob/master/LICENSE.md MIT
 */

namespace allejo\stakx\Manager;

use allejo\stakx\Command\BuildableCommand;
use allejo\stakx\Document\JailedDocument;
use allejo\stakx\Document\PageView;
use allejo\stakx\Document\TwigDocumentInterface;
use allejo\stakx\FrontMatter\FrontMatterDocument;
use allejo\stakx\Service;
use allejo\stakx\System\FileExplorer;
use Symfony\Component\Finder\SplFileInfo;

/**
 * Class TrackingManager.
 */
abstract class TrackingManager extends BaseManager
{
    /**
     * @var FileExplorer
     */
    protected $fileExplorer;

    /**
     * An array corresponding with $folderDefinitions to store metadata regarding a specificc folder.
     *
     * $folderDefinitionsOption['<folder path>'] = array()
     *
     * @var string[]
     */
    protected $folderDefinitionsOptions;

The variable name $folderDefinitionsOptions exceeds the maximum configured length of 20.

    /**
     * An array of folders which tracked items are stored in.
     *
     * $folderDefinitions[] = '<folder path>'
     *
     * @var string[]
     */
    protected $folderDefinitions;

    /**
     * The storage which contains the same information as $trackedItems but organized by relative file path instead of a
     * namespace or file name without extension.
     *
     * $trackedItemsOptions['<relative file path>'] = mixed
     *
     * @var array
     */
    protected $trackedItemsFlattened;

The variable name $trackedItemsFlattened exceeds the maximum configured length of 20.

    /**
     * The storage used to cache any information needed for a specific FrontMatterObject or DataItem.
     *
     * For example, with a DataItem, which is just an array, the file path to the original file can be stored in this
     * array to be accessible in the future to refresh the contents without parsing all of the files again.
     *
     * $trackedItemsOptions['<relative file path>'] = array
     *
     * @var array
     */
    protected $trackedItemsOptions;

    /**
     * The storage used for either FrontMatterObjects or DataItems in the respective static classes.
     *
     * $trackedItems['<namespace>']['<file name w/o extension>'] = mixed
     * $trackedItems['<file name w/o extension>'] = mixed
     *
     * @var array
     */
    protected $trackedItems;

    /**
     * Set to true when file tracking is enabled.
     *
     * @var bool
     */
    protected $tracking;

    public function __construct()
    {
        parent::__construct();

        $this->folderDefinitionsOptions = array();
        $this->folderDefinitions = array();
        $this->trackedItemsFlattened = array();
        $this->trackedItemsOptions = array();
        $this->trackedItems = array();
        $this->tracking = false;
    }

    /**
     * Whether or not to enable tracking of files.
     *
     * Setting this to false will disable a lot of the overhead and caching done when a project is being watched
     *
     * @param bool $enabled
     */
    public function enableTracking($enabled)
    {
        $this->tracking = $enabled;
    }

    /**
     * Check to see if the file belongs inside of one the folders being tracked by this manager.
     *
     * @param string $filePath
     *
     * @return bool True if the file is inside a tracked folder
     */
    public function isHandled($filePath)
    {
        foreach ($this->folderDefinitions as $folder)
        {
            if (substr($filePath, 0, strlen($folder)) === $folder)
            {
                return true;
            }
        }

        return false;
    }

    /**
     * Check whether a file is tracked.
     *
     * @param string $filePath The relative path of the file
     *
     * @return bool
     */
    public function isTracked($filePath)
    {
        return array_key_exists($filePath, $this->trackedItemsFlattened);
    }

    /**
     * @param SplFileInfo|string $filePath
     *
     * @return mixed|null
     */
    public function createNewItem($filePath)
    {
        return $this->handleTrackableItem($filePath);

It seems like $filePath defined by parameter $filePath on line 147 can also be of type string; however, allejo\stakx\Manager\TrackingManager::handleTrackableItem() does only seem to accept object<Symfony\Component\Finder\SplFileInfo>, maybe add an additional type check?

    }

    /**
     * Update the contents of a specified file.
     *
     * @param SplFileInfo|string $filePath The relative path of the file
     *
     * @return PageView
     */
    public function refreshItem($filePath)
    {
        return $this->handleTrackableItem($filePath);

It seems like $filePath defined by parameter $filePath on line 159 can also be of type string; however, allejo\stakx\Manager\TrackingManager::handleTrackableItem() does only seem to accept object<Symfony\Component\Finder\SplFileInfo>, maybe add an additional type check?

    }

    /**
     * Save data to the tracker with a reference to the file it came from.
     *
     * @param string      $key       The name of the file
     * @param mixed       $data      The data to save the
     * @param string      $filePath  The relative file path from the root of the website
     * @param string|null $namespace The name of the collection this data belongs to, if any
     */
    protected function addArrayToTracker($key, $data, $filePath, $namespace = null)
    {
        if (is_null($namespace))
        {
            $this->trackedItems[$key] = $data;
            $this->trackedItemsFlattened[$filePath] = &$this->trackedItems[$key];
        }
        else
        {
            $this->trackedItems[$namespace][$key] = $data;
            $this->trackedItemsFlattened[$filePath] = &$this->trackedItems[$namespace][$key];
        }
    }

    /**
     * Add a FrontMatterObject based object to the tracker.
     *
     * @param TwigDocumentInterface $trackedItem
     * @param string $key
     * @param string|null $namespace
     */
    protected function addObjectToTracker($trackedItem, $key, $namespace = null)
    {
        if (!($trackedItem instanceof FrontMatterDocument) && !($trackedItem instanceof TwigDocumentInterface))
        {
            throw new \InvalidArgumentException('Only TwigDocumentInterface objects can be added to the tracker');
        }

        $this->addArrayToTracker($key, $trackedItem, $trackedItem->getRelativeFilePath(), $namespace);
    }

    /**
     * Remove all data related to an array that was saved.
     *
     * @param string      $key
     * @param string      $filePath
     * @param string|null $namespace
     */
    protected function delArrayFromTracker($key, $filePath, $namespace = null)
    {
        if (is_null($namespace))
        {
            unset($this->trackedItems[$key]);
        }
        else
        {
            unset($this->trackedItems[$namespace][$key]);
        }

        unset($this->trackedItemsFlattened[$filePath]);
    }

    /**
     * Remove an entry from the tracked items array.
     *
     * @param mixed       $trackedItem
     * @param string|null $namespace
     */
    protected function delObjectFromTracker($trackedItem, $namespace = null)
    {
        $this->delArrayFromTracker(
            $trackedItem->getFileName(),
            $trackedItem->getRelativeFilePath(),
            $namespace
        );
    }

    /**
     * Save a folder that is tracked by this manager and its respective options.
     *
     * @param string $folderPath
     * @param array  $options
     */
    protected function saveFolderDefinition($folderPath, $options = array())
    {
        $this->folderDefinitions[] = $folderPath;
        $this->folderDefinitionsOptions[$folderPath] = $options;
    }

    /**
     * Save any options related to an item needed in order to refresh the content.
     *
     * @param string $filePath
     * @param array  $options
     */
    protected function saveTrackerOptions($filePath, $options = array())
    {
        $this->trackedItemsOptions[$filePath] = $options;
    }

    /**
     * Parse the specified folder for items to track.
     *
     * @param string $path
     * @param mixed  $options  Special options that will be passed to the static::parseTrackableItem() implementation
     * @param array  $includes
     * @param array  $excludes
     */
    protected function scanTrackableItems($path, $options = array(), $includes = array(), $excludes = array())
    {
        $fileExplorerFlags = array_key_exists('fileExplorer', $options) ? $options['fileExplorer'] : null;
        $this->fileExplorer = FileExplorer::create($path, $excludes, $includes, $fileExplorerFlags);
        $fileExplorer = $this->fileExplorer->getExplorer();

        foreach ($fileExplorer as $file)
        {
            $this->handleTrackableItem($file, $options);
        }
    }

    /**
     * Return an array of JailedDocuments created from the tracked items
     *
     * @return JailedDocument[]
     */
    protected function getJailedTrackedItems()
    {
        $jailItems = array();

        /**
         * @var string $key
         * @var TwigDocumentInterface $item
         */
        foreach ($this->trackedItemsFlattened as &$item)
        {
            if (!Service::getParameter(BuildableCommand::USE_DRAFTS) && $item->isDraft()) { continue; }

            if (empty($item->getNamespace()))
            {
                $jailItems[$item->getName()] = $item->createJail();
            }
            else
            {
                $jailItems[$item->getNamespace()][$item->getName()] = $item->createJail();
            }
        }

        return $jailItems;
    }

    /**
     * Handle a specific file type, parse it into the appropriate object type, and add it to the tracker.
     *
     * This function should make use of the appropriate functions:
     *
     *  - TrackingManager::addObjectToTracker()
     *  - TrackingManager::addArrayToTracker()
     *  - TrackingManager::saveTrackerOptions()
     *
     * @param SplFileInfo $filePath
     * @param mixed       $options
     *
     * @return mixed|null
     */
    abstract protected function handleTrackableItem($filePath, $options = array());
}