diff --git a/README.md b/README.md index 3810f4c..5402e80 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ with the following functionality (excerpt): - **Limit** the comparison to common or uncommon parameters of the lists - **Search** for specific keys or values in the parameter list - **Mark** parameters as favourites and view them in a dedicated view +- **Get** location info about the parameters (which files do they appear in and with what value) - **Download** a file representation of the parameter lists - **And** more diff --git a/Resources/doc/changelogs/CHANGELOG-2.x.md b/Resources/doc/changelogs/CHANGELOG-2.x.md index 41c0b39..28e46ba 100644 --- a/Resources/doc/changelogs/CHANGELOG-2.x.md +++ b/Resources/doc/changelogs/CHANGELOG-2.x.md @@ -2,11 +2,23 @@ ## 2.0.1 (xx.12.2020) -* Adapted the custom kernel boot process to make the location retrieval functionality -available in Symfony 3.4 and Ibexa Platform 2.5 +* Adapted the custom kernel boot process to make the location retrieval functionality + available in Symfony 3.4 and Ibexa Platform 2.5 +* Fixed that changes to the favourite parameter list via the frontend would be ignored + +* Fixed error in synchronous scrolling, where unique nodes would not be added to the other list (when they were + the first node of the list) + +* Changed differences highlighting via the url, to only start highlighting, when the entire page is already loaded and done + with the other javascripts + * Improved some internal documentation +* Improved config path retrieval: Now the process is able to find configuration files more effectively + and easily and should be aware of every used file for configuration except for the custom bundle config + which is conducted by the bundles themselves. + ## 2.0 (11.12.2020) * This changelog has been created to ship with the first full version of the bundle diff --git a/src/LocationAwareConfigLoadBundle/ConfigPathUtility.php b/src/LocationAwareConfigLoadBundle/ConfigPathUtility.php index 69fe9c9..55b6c23 100644 --- a/src/LocationAwareConfigLoadBundle/ConfigPathUtility.php +++ b/src/LocationAwareConfigLoadBundle/ConfigPathUtility.php @@ -21,25 +21,39 @@ class ConfigPathUtility { - /** @var string The assortment of file extensions which can be used to configure symfony. */ + /** + * @var string The assortment of file extensions which can be used to configure symfony. + */ private static $configExtensions = ""; - /** @var array Stores all added configuration paths */ + /** + * @var array Stores all added configuration paths + */ private static $configPaths = []; - /** @var PhpFilesAdapter A cache for the routes that have been determined throughout the previous loading processes. */ + /** + * @var PhpFilesAdapter A cache for the routes that have been determined throughout the previous loading processes. + */ private static $configPathCache; - /** @var bool States whether it has been tried to retrieve the existing paths from the cache already / the cache has been initialised. */ + /** + * @var bool States whether it has been tried to retrieve the existing paths from the cache already / the cache has been initialised. + */ private static $cacheInitialized = false; - /** @var bool States whether there has been a change in paths (this only occurs through adding a path (for now)). */ + /** + * @var bool States whether there has been a change in paths (this only occurs through adding a path (for now)). + */ private static $pathsChanged = false; - /** @var bool This boolean states whether there has been a change to the paths that warrants the kernel and thereby load process to be restarted to include the newly found paths. */ + /** + * @var bool This boolean states whether there has been a change to the paths that warrants the kernel and thereby load process to be restarted to include the newly found paths. + */ private static $restartLoadProcess = false; - /** @var string The directory in which to cache all the routes (in order to prevent the cache from being stored only temporarily) */ + /** + * @var string The directory in which to cache all the routes (in order to prevent the cache from being stored only temporarily) + */ private static $cacheDir = null; /** @@ -47,7 +61,7 @@ class ConfigPathUtility * It initiates the cache (if it hasn't already), retrieves the routes from the cache, parses the manually defined routes * and sets the internal boolean attributes to their initial value. */ - public static function initializePathUtility(): void + public static function initializePathUtility() { if (!self::$cacheInitialized) { // If the cache has not yet been instantiated @@ -75,7 +89,7 @@ function () { // Parse the manual path_config-file self::getUserDefinedPaths(); - } catch (Exception $e) { + } catch (InvalidArgumentException | Exception $e) { self::$configPaths = []; } } @@ -90,27 +104,30 @@ function () { *
But, paths which point to a file / directory which does not exist, are not added to the paths list. * * @param string $extensionPath The path pointing to a bundle's ExtensionClass. + * * @return string|null Returns the converted string or null, if the path does not point to the DependencyInjection or a directory which does not exist. */ - public static function convertExtensionPathToConfigDirectory(string $extensionPath) { - // Get the index in the string where "DependencyInjection" is present - $diPosition = strpos($extensionPath,"DependencyInjection"); + public static function convertExtensionPathToConfigDirectory(string $extensionPath) + { + $configDirPath = preg_match("/\.php$/",$extensionPath)? dirname($extensionPath) : $extensionPath; - if(!$diPosition) { - return null; + if (preg_match("/\/$/", $configDirPath)) { + $configDirPath = substr($configDirPath,0,strlen($configDirPath)-1); } - // Change it from DependencyInjection to the config directory - $configDirPath = substr($extensionPath,0,$diPosition)."Resources/config/"; + while (!preg_match("/.*\/vendor\/?$/", $configDirPath)) { + if (file_exists($configDirPath.DIRECTORY_SEPARATOR."Resources".DIRECTORY_SEPARATOR."config")) { + $configDirPath = $configDirPath.DIRECTORY_SEPARATOR."Resources".DIRECTORY_SEPARATOR."config".DIRECTORY_SEPARATOR; + break; + } else if (file_exists($configDirPath.DIRECTORY_SEPARATOR."config")) { + $configDirPath = $configDirPath.DIRECTORY_SEPARATOR."config".DIRECTORY_SEPARATOR; + break; + } - if (!file_exists($configDirPath)) { - return null; + $configDirPath = dirname($configDirPath); } - // Since the entire directory is added as a glob resource, the "*" signals that all files within the directory are - // to be looked at (only one level deep) and the extensions signal that only files which end on one of the config - // extensions are considered. - return $configDirPath."*".self::$configExtensions; + return preg_match("/\/$/", $configDirPath)? $configDirPath."*".self::$configExtensions : null; } /** @@ -120,7 +137,8 @@ public static function convertExtensionPathToConfigDirectory(string $extensionPa * @param string $configPath The path to be added to the list. * @param bool $isGlobPattern A boolean stating whether the path is a glob-resource / pattern which will have to be loaded differently from non-glob-pattern. */ - public static function addPathToPathlist(string $configPath, bool $isGlobPattern = true): void { + public static function addPathToPathlist(string $configPath, bool $isGlobPattern = true): void + { // If the cache has not been initialised, initialise it. if (!self::$cacheInitialized) { self::initializePathUtility(); @@ -139,7 +157,8 @@ public static function addPathToPathlist(string $configPath, bool $isGlobPattern * *
Also signals, that a restart of the load process is useful / necessary. */ - public static function storePaths(): void { + public static function storePaths(): void + { if (self::$cacheInitialized && self::$pathsChanged) { try { self::$configPathCache->deleteItem("cjw_config_paths"); @@ -197,7 +216,9 @@ public static function setConfigExtensions(string $configExtensions): void } /** - * @param string $cacheDir + * Sets the cache directory for this class of the bundle, based on the general cache path of the installation. + * + * @param string $cacheDir The blank, standard cache path of the project. */ public static function setCacheDir(string $cacheDir): void { @@ -238,9 +259,11 @@ private static function getUserDefinedPaths(): void * Checks the user defined paths for any kind of errors with regards to the definition of said paths. * * @param array $path A path array (hopefully with 3 items under the keys of "path", "glob" and "addConfExt"). + * * @return bool Boolean which states whether the path at least passes the most basic checks regarding their structure. */ - private static function checkUserDefinedPath(array $path): bool { + private static function checkUserDefinedPath(array $path): bool + { if (is_array($path) && count($path) === 3) { if (!(key_exists("path",$path) && is_string($path["path"]) && !empty($path["path"]))) { return false; diff --git a/src/LocationAwareConfigLoadBundle/CustomContainerBuilder.php b/src/LocationAwareConfigLoadBundle/CustomContainerBuilder.php index aacd5b3..770b8e6 100644 --- a/src/LocationAwareConfigLoadBundle/CustomContainerBuilder.php +++ b/src/LocationAwareConfigLoadBundle/CustomContainerBuilder.php @@ -6,6 +6,7 @@ use Exception; use ReflectionClass; +use Symfony\Component\DependencyInjection\Alias; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Definition; @@ -19,6 +20,9 @@ */ class CustomContainerBuilder extends ContainerBuilder { + /** + * @var bool Boolean which determines whether the bundle configuration mode is active or not. + */ private $isBundleConfigMode; public function __construct() @@ -33,7 +37,8 @@ public function __construct() * * @param string $location The location to be set. */ - public function setCurrentLocation(string $location) { + public function setCurrentLocation(string $location) + { /** The parameterBag is the custom one created to feature such a function */ $this->parameterBag->setCurrentLocation($location); @@ -41,6 +46,14 @@ public function setCurrentLocation(string $location) { /** * @override + * In order to be able to actively influence the way locations are read for parameters during the bundle configuration + * process, the compilation of the container is caught through this function and then, after the measures for the + * bundle configuration are set in place, the normal compilation process of the container takes place. + * + *
This was done in order to prevent the bundles from constantly adding the same parameters unchanged back into + * the container, which led to dozens of useless entries into the location lists for every parameter. + * + * @param bool $resolveEnvPlaceholders */ public function compile($resolveEnvPlaceholders = false) { @@ -61,6 +74,7 @@ public function compile($resolveEnvPlaceholders = false) * config directories to be tracked. * * @param string $name The name of the bundle who's extension config to retrieve. + * * @return array Returns the found configuration. */ public function getExtensionConfig($name) @@ -90,6 +104,8 @@ public function getExtensionConfig($name) * @override * This override ensures, that no definition of a service will be added while loading the config files of the bundles * outside of the bundle configuration phase. + * + * @param array $definitions */ public function addDefinitions(array $definitions) { @@ -102,6 +118,11 @@ public function addDefinitions(array $definitions) * @override * This override ensures, that no service will be registered while loading the config files of the bundles * outside of the bundle configuration phase. + * + * @param string $id + * @param string|null $class + * + * @return Definition|null */ public function register($id, $class = null) { @@ -116,6 +137,11 @@ public function register($id, $class = null) * @override * This override ensures, that no service definition will be added while loading the config files of the bundles * outside of the bundle configuration phase. + * + * @param string $id + * @param Definition $definition + * + * @return Definition|null */ public function setDefinition($id, Definition $definition) { @@ -130,6 +156,11 @@ public function setDefinition($id, Definition $definition) * @override * This override ensures, that no service alias will be set while loading the config files of the bundles * outside of the bundle configuration phase. + * + * @param string $alias + * @param $id + * + * @return string|Alias|null */ public function setAlias($alias, $id) { @@ -139,11 +170,13 @@ public function setAlias($alias, $id) return null; } - + /** * @override * This override ensures, that no service definition will be registered while loading the config files of the bundles * outside of the bundle configuration phase. + * + * @param array $definitions */ public function setDefinitions(array $definitions) { diff --git a/src/LocationAwareConfigLoadBundle/CustomDelegatingLoader.php b/src/LocationAwareConfigLoadBundle/CustomDelegatingLoader.php index 08e5382..7af6083 100644 --- a/src/LocationAwareConfigLoadBundle/CustomDelegatingLoader.php +++ b/src/LocationAwareConfigLoadBundle/CustomDelegatingLoader.php @@ -4,6 +4,7 @@ namespace CJW\CJWConfigProcessor\src\LocationAwareConfigLoadBundle; +use Exception; use Symfony\Component\Config\Loader\DelegatingLoader; use Symfony\Component\Config\Loader\LoaderResolverInterface; @@ -16,7 +17,9 @@ class CustomDelegatingLoader extends DelegatingLoader { - /** @var CustomContainerBuilder A container builder which serves to build the container while keeping track of the files used to do so. */ + /** + * @var CustomContainerBuilder A container builder which serves to build the container while keeping track of the files used to do so. + */ private $container; public function __construct(LoaderResolverInterface $resolver, CustomContainerBuilder $containerBuilder) @@ -32,9 +35,11 @@ public function __construct(LoaderResolverInterface $resolver, CustomContainerBu * @override * This override ensures that everytime a resource is loaded (which is not a global pattern) the path to said resource is set * in and known by the container. + * * @param $resource * @param string|null $type - * @throws \Exception + * + * @throws Exception */ public function load($resource, $type = null) { diff --git a/src/LocationAwareConfigLoadBundle/CustomValueStorage.php b/src/LocationAwareConfigLoadBundle/CustomValueStorage.php index 6ad1d43..0125ec2 100644 --- a/src/LocationAwareConfigLoadBundle/CustomValueStorage.php +++ b/src/LocationAwareConfigLoadBundle/CustomValueStorage.php @@ -14,16 +14,24 @@ class CustomValueStorage { - /** @var array This is an array of all locations that have been encountered during the loading process. */ + /** + * @var array This is an array of all locations that have been encountered during the loading process. + */ private static $encounteredLocations = []; - /** @var array An array of all parameters being loaded by the config loading process and the values accompanied by the paths they stem from. */ + /** + * @var array An array of all parameters being loaded by the config loading process and the values accompanied by the paths they stem from. + */ private static $parameterAndTheirLocations = []; - /** @var bool States whether new parameter values or paths can be added to the internal arrays or not. */ + /** + * @var bool States whether new parameter values or paths can be added to the internal arrays or not. + */ private static $allowWrite = true; - /** @var bool States whether the bundle config loading process has begun. */ + /** + * @var bool States whether the bundle config loading process has begun. + */ private static $bundleConfig = false; /** @@ -41,7 +49,8 @@ class CustomValueStorage * @param mixed $value The value attached to both the parametername and then the given path as well. It is going to be added under path-key as an entry of the array. * @param string $path The path (the origin) of the parameter value that is being set. It serves as a key under the parameter-key of the array. */ - public static function addParameterOrLocation(string $parameterName, $value, string $path) { + public static function addParameterOrLocation(string $parameterName, $value, string $path) + { // Only if it is currently allowed to write, will the process even begin if (self::$allowWrite) { if (!in_array($path, self::$encounteredLocations)) { @@ -66,7 +75,8 @@ public static function addParameterOrLocation(string $parameterName, $value, str * It simply sets an internal boolean which then prohibits any parameters or paths / values to be set. * In order to unlock the writing process, use {@see unlockParameters()}. */ - public static function lockParameters() { + public static function lockParameters() + { self::$allowWrite = false; } @@ -75,7 +85,8 @@ public static function lockParameters() { * to the internal parameter-and-path storage. It sets the internal boolean to a different value * than {@see lockParameters()}. */ - public static function unlockParameters() { + public static function unlockParameters() + { self::$allowWrite = true; } @@ -91,7 +102,8 @@ public static function unlockParameters() { * * @param bool $activate A boolean stating that the mode is either to be active (true) or not (false). */ - public static function activateBundleConfigMode(bool $activate) { + public static function activateBundleConfigMode(bool $activate) + { self::$bundleConfig = $activate; } @@ -100,7 +112,8 @@ public static function activateBundleConfigMode(bool $activate) { * bundleConfigMode and the lock-status of the class internally. This serves to allow a "fresh" start with the internal * storage. */ - public static function reset(): void { + public static function reset(): void + { self::$parameterAndTheirLocations = []; self::$bundleConfig = false; self::$allowWrite = true; @@ -112,7 +125,8 @@ public static function reset(): void { * * @return array Returns an array of parameters as super-keys, the locations as sub-keys and the values found at the paths as entries. */ - public static function getParametersAndTheirLocations() { + public static function getParametersAndTheirLocations() + { ksort(self::$parameterAndTheirLocations,SORT_STRING); return self::$parameterAndTheirLocations; } @@ -123,7 +137,8 @@ public static function getParametersAndTheirLocations() { * * @return array Returns an array which is filled with all encountered locations during the configuration-loading-process. */ - public static function getEncounteredLocations() { + public static function getEncounteredLocations() + { return self::$encounteredLocations; } @@ -131,9 +146,11 @@ public static function getEncounteredLocations() { * Allows a specific parameter to be retrieved from the internal storage of the class. * * @param string $parameterName The name of the parameter as string. + * * @return array|null Returns the internal array with `$path => $value` pairs or null if the parameter is not present in the internal array. */ - public static function getLocationsForSpecificParameter(string $parameterName) { + public static function getLocationsForSpecificParameter(string $parameterName) + { // Only if that parameter exists as a key in the array, will that parameters paths and values be returned, otherwise null return isset(self::$parameterAndTheirLocations[$parameterName]) ? self::$parameterAndTheirLocations[$parameterName] : null; diff --git a/src/LocationAwareConfigLoadBundle/LoadInitializer.php b/src/LocationAwareConfigLoadBundle/LoadInitializer.php index 4811b5c..9a72835 100644 --- a/src/LocationAwareConfigLoadBundle/LoadInitializer.php +++ b/src/LocationAwareConfigLoadBundle/LoadInitializer.php @@ -26,6 +26,9 @@ */ class LoadInitializer extends \AppKernel { + /** + * @var Kernel An instance of the actual Symfony kernel handling all the requests (to ensure the correct paths are used). + */ private $kernel; public function __construct(string $environment, bool $debug) @@ -169,10 +172,7 @@ protected function getContainerBuilder() * @param ContainerBuilder $container * @param LoaderInterface $loader */ - protected function configureContainer( - ContainerBuilder $container, - LoaderInterface $loader - ): void + protected function configureContainer(ContainerBuilder $container, LoaderInterface $loader): void { parent::configureContainer($container, $loader); @@ -199,7 +199,8 @@ protected function configureContainer( *
* It is employed to allow a reboot to occur during the loading process (in order to take newly found config-paths into account). */ - private function cleanUpCache() { + private function cleanUpCache() + { $glob = glob($this->getCacheDir()."/*"); foreach ($glob as $file) { diff --git a/src/LocationAwareConfigLoadBundle/LocationAwareParameterBag.php b/src/LocationAwareConfigLoadBundle/LocationAwareParameterBag.php index 8dd1df6..4a23a5f 100644 --- a/src/LocationAwareConfigLoadBundle/LocationAwareParameterBag.php +++ b/src/LocationAwareConfigLoadBundle/LocationAwareParameterBag.php @@ -5,12 +5,20 @@ use Symfony\Component\DependencyInjection\ParameterBag\EnvPlaceholderParameterBag; -//use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag; +/** + * Class LocationAwareParameterBag is a custom parameter bag which is designed to keep track of the resources being + * loaded into the container and this bag. It is reliant on information it receives from other classes of the load + * process higher up in the chain to keep its path information up to date. + * + * @package CJW\CJWConfigProcessor\src\LocationAwareConfigLoadBundle + */ class LocationAwareParameterBag extends EnvPlaceholderParameterBag { - /** @var string Stores the current location that is being loaded */ + /** + * @var string Stores the current location that is being loaded. + */ private $currentLocation; public function __construct(array $parameters = []) @@ -29,7 +37,8 @@ public function __construct(array $parameters = []) * * @param string $location The path / file that is being loaded. */ - public function setCurrentLocation(string $location) { + public function setCurrentLocation(string $location) + { $this->currentLocation = $location; } diff --git a/src/LocationAwareConfigLoadBundle/LocationRetrievalCoordinator.php b/src/LocationAwareConfigLoadBundle/LocationRetrievalCoordinator.php index 7bedea8..545996f 100644 --- a/src/LocationAwareConfigLoadBundle/LocationRetrievalCoordinator.php +++ b/src/LocationAwareConfigLoadBundle/LocationRetrievalCoordinator.php @@ -8,26 +8,43 @@ use Symfony\Component\Cache\Adapter\PhpFilesAdapter; use Symfony\Component\Cache\Exception\CacheException; + +/** + * Class LocationRetrievalCoordinator is the instigator of the entire location retrieval process and responsible for + * creating and using both the custom kernel and helper classes to determine, keep track of and store the locations + * of and for every determined parameter. + * + * @package CJW\CJWConfigProcessor\src\LocationAwareConfigLoadBundle + */ class LocationRetrievalCoordinator { - /** @var LoadInitializer A custom kernel that initiates the entire custom loading process. */ + /** + * @var LoadInitializer A custom kernel that initiates the entire custom loading process. + */ private static $customConfigLoader; - /** @var array An array which not only stores the parameters, but also the paths they have been read from (including the values set there) */ + /** + * @var array An array which not only stores the parameters, but also the paths they have been read from (including the values set there) + */ public static $parametersAndLocations; - /** @var PhpFilesAdapter A cache which is supposed to store parameters that have been parsed. */ + /** + * @var PhpFilesAdapter A cache which is supposed to store parameters that have been parsed. + */ private static $cache; - /** @var bool */ + /** + * @var bool Boolean which describes whether the class has been instantiated and all important attributes of it have been initialized. + */ private static $initialized = false; /** * "Initiates" the class and sets all missing and non-instantiated attributes of the class prior to the rest * of its functions being called. */ - public static function initializeCoordinator(): void { + public static function initializeCoordinator() + { if (!self::$customConfigLoader) { // Environment is taken from "SYMFONY_ENV" variable, if not set, defaults to "prod" $environment = getenv('SYMFONY_ENV'); @@ -93,7 +110,9 @@ function () { } /** - * @return array + * Retrieves all parameters and the associated locations which have been retrieved by the class. + * + * @return array An associative array, which contains the parameters as first keys, then the different paths and the values that have been set in those files. */ public static function getParametersAndLocations(): array { @@ -104,11 +123,19 @@ public static function getParametersAndLocations(): array return self::$parametersAndLocations; } - public static function getParameterLocations ( - string $parameterName, - array $siteAccessGroups = null, - bool $withSiteAccess = false - ) { + /** + * This functionality allows to retrieve all locations specific to one parameter given to the function. This can + * be done in a site access context too, where all site access versions of the given parameter will be looked at + * as well. + * + * @param string $parameterName The name of the parameter who's locations should be retrieved. + * @param array|null $siteAccessGroups An array of the site access groups that exist in the current installation (required to determine site access groups versions of the parameter). + * @param bool $withSiteAccess A boolean which states whether the parameter should be viewed in a site access context. Set to true, all site access versions of the given parameter are looked at. + * + * @return array|null An array of locations for the parameter of null if nothing could be found. + */ + public static function getParameterLocations (string $parameterName, array $siteAccessGroups = null, bool $withSiteAccess = false) + { if (!self::$initialized) { self::initializeCoordinator(); } @@ -120,16 +147,14 @@ public static function getParameterLocations ( * Returns the internal array which keeps track of all encountered locations without any connection to * the parameters, values or other information. It resembles a plain "stack" of locations. * - * @param string $parameterName - * @param array|null $siteAccessGroups - * @param bool $withSiteAccess + * @param string $parameterName The name of the parameter who's locations should be retrieved. + * @param array|null $siteAccessGroups An array of the site access groups that exist in the current installation (required to determine site access groups versions of the parameter). + * @param bool $withSiteAccess A boolean which states whether the parameter should be viewed in a site access context. Set to true, all site access versions of the given parameter are looked at. + * * @return array Returns an array which is filled with all encountered locations during the configuration-loading-process. */ - private static function getLocationsForSpecificParameter ( - string $parameterName, - array $siteAccessGroups = null, - bool $withSiteAccess = false - ) { + private static function getLocationsForSpecificParameter(string $parameterName, array $siteAccessGroups = null, bool $withSiteAccess = false) + { $parameterKeySegments = explode(".", $parameterName); if (is_array($parameterKeySegments) && count($parameterKeySegments) > 1) { @@ -205,10 +230,19 @@ private static function getLocationsForSpecificParameter ( } } - private static function getLocationsFromRewrittenSiteAccessParameter( - string $newSiteAccess, - array $originalParameterKeySegments - ) { + + /** + * This function takes the original parameter name which has been split up by the "." (dots) and a given site access + * by which to look at it and creates a new parameter name through the given parts. Afterwards it checks for whether + * locations exist for that specific parameter. + * + * @param string $newSiteAccess The site access with which to construct the parameter name. + * @param array $originalParameterKeySegments An array of all segments of the parameter key. + * + * @return array Returns an array which includes the found locations for the new parameter or an empty one if nothing could be found. + */ + private static function getLocationsFromRewrittenSiteAccessParameter(string $newSiteAccess, array $originalParameterKeySegments) + { if ($originalParameterKeySegments[1] !== $newSiteAccess) { $originalParameterKeySegments[1] = $newSiteAccess; diff --git a/src/Utility/Utility.php b/src/Utility/Utility.php index 4c817c7..51524f1 100644 --- a/src/Utility/Utility.php +++ b/src/Utility/Utility.php @@ -8,14 +8,29 @@ use Psr\Cache\InvalidArgumentException; use Symfony\Component\Cache\Adapter\AdapterInterface; +/** + * Class Utility is, as the name implies, a class which is responsible for delivering utility functionality that can + * be employed (mostly without any conditions) in other classes. + * + * @package CJW\CJWConfigProcessor\src\Utility + */ class Utility { - public static function removeUncommonParameters ( - array $firstParameterList, - array $secondParameterList, - int $level = 0 - ): array + /** + * Responsible for removing uncommon parameters between two given hierarchical, associative arrays of parameters. + * It is designed to work with site access versions of the parameters, which means that the parameters typically + * don't go deeper then two levels. + * + * @param array $firstParameterList The first list of parameters to check against the second. + * @param array $secondParameterList The second list of parameters to check against the first. + * @param int $level The (optional) amount of levels the comparison has gone to in the two arrays. + * + * @return array[] A multi dimensional array, which contains the first and second parameter lists with only the common parameters. + * + * @see removeCommonParameters For a similar function which does the opposite. + */ + public static function removeUncommonParameters (array $firstParameterList, array $secondParameterList, int $level = 0): array { $firstListKeys = array_keys($firstParameterList); $secondListKeys = array_keys($secondParameterList); @@ -51,11 +66,20 @@ public static function removeUncommonParameters ( return [$firstParameterList,$secondParameterList]; } - public static function removeCommonParameters ( - array $firstParameterList, - array $secondParameterList, - int $level = 0 - ): array + /** + * Responsible for removing common parameters between two given hierarchical, associative arrays of parameters. + * It is designed to work with site access versions of the parameters, which means that the parameters typically + * don't go deeper then two levels. + * + * @param array $firstParameterList The first list of parameters to check against the second. + * @param array $secondParameterList The second list of parameters to check against the first. + * @param int $level The (optional) amount of levels the comparison has gone to in the two arrays. + * + * @return array[] A multi dimensional array, which contains the first and second parameter lists with only the uncommon parameters. + * + * @see removeUncommonParameters For a similar function which does the opposite. + */ + public static function removeCommonParameters (array $firstParameterList, array $secondParameterList, int $level = 0): array { $firstListKeys = array_keys($firstParameterList); $secondListKeys = array_keys($secondParameterList); @@ -91,9 +115,12 @@ public static function removeCommonParameters ( /** * Taken off StackOverflow from + * * @author Captain kurO * @url https://stackoverflow.com/questions/173400/how-to-check-if-php-array-is-associative-or-sequential/4254008#4254008 + * * @param array $array + * * @return bool */ public static function has_string_keys(array $array): bool @@ -106,9 +133,15 @@ public static function has_string_keys(array $array): bool ) > 0; } - public static function determinePureSiteAccesses( - array $processedParameterArray - ): array + /** + * Determines and then returns the defined "pure" site accesses of your installation through a given list of the + * application configuration. Pure in this case means, that site access groups are not included in that list. + * + * @param array $processedParameterArray An associative, hierarchical array of parameters to search for the site accesses. + * + * @return string[] Returns an array of site accesses in the form of strings. + */ + public static function determinePureSiteAccesses(array $processedParameterArray): array { try { $results = @@ -121,9 +154,15 @@ public static function determinePureSiteAccesses( } } - public static function determinePureSiteAccessGroups ( - array $processedParameterArray - ): array + /** + * Determines and then returns the defined site access groups of your installation through a given list of the + * application configuration. Pure in this case means, that the site accesses are not included in that list. + * + * @param array $processedParameterArray An associative, hierarchical array of parameters to search for the site accesses. + * + * @return array Returns an array of the found site access groups (empty if non are found). + */ + public static function determinePureSiteAccessGroups (array $processedParameterArray): array { try { return $processedParameterArray["ezpublish"]["siteaccess"]["groups"]["parameter_value"]; @@ -132,10 +171,19 @@ public static function determinePureSiteAccessGroups ( } } - public static function removeEntryThroughKeyList ( - array $parameters, - array $keyList - ): array + /** + * Takes a given list of hierarchical key segments and also an associative array of parameters and aims to delete + * the key at the very bottom of the key list from the parameters array. + * + *
For example: Giving only one key segment / key in the list will remove that key from the very first level of + * the associative parameters array. + * + * @param array $parameters An associative array of parameters from which to delete the given key. + * @param array $keyList A list of keys that will be gone through to the very last given segment, which is then going to be deleted from the given parameters array. + * + * @return array Returns the remaining array of parameters, after the key segment has been deleted. + */ + public static function removeEntryThroughKeyList (array $parameters, array $keyList): array { $key = reset($keyList); array_splice($keyList,0,1); @@ -157,10 +205,18 @@ public static function removeEntryThroughKeyList ( return $parameters; } - public static function removeSpecificKeySegment ( - string $keySegment, - array $parametersToRemoveFrom - ): array + /** + * Similar to {@see removeEntryThroughKeyList}, aims to remove a specific key from an associative array of parameters. + * In contrast to the above mentioned function, this one takes only one specific key and goes through the entire + * array until the key is found, while the other function goes through the given list of segments and only these + * segments and then deletes the key if it exists. + * + * @param string $keySegment The specific key to be removed from the given array. + * @param array $parametersToRemoveFrom An associative array of parameters from which to remove the given key, if it exists. + * + * @return array Returns the resulting array of parameters, after the key segment has been deleted (unchanged from the given array, if the key could not be found). + */ + public static function removeSpecificKeySegment (string $keySegment, array $parametersToRemoveFrom): array { $result = $parametersToRemoveFrom;