Commit regarding issues #5, #6 and #7

No in depth comments on every class, since no real code changes have occurred.

The biggest changes include removing all scalar type hints from method signatures (since these do not seem to be present in 7.1) and adding documentation to every class.

The documentation includes descriptions of methods, attributes and the class itself.

Also the coding style was brought more inline with Symfony's coding standards.

All of this was done to lower the requirements for the bundle and make the code more understandable and readable.

Controller/ConfigProcessController.php

@@ -21,15 +21,27 @@
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 use Symfony\Component\HttpKernel\Exception\HttpException;
 
+/**
+ * Class ConfigProcessController is responsible for delivering the functionality required to bring the processed
+ * configuration into the bundle frontend.
+ *
+ * @package CJW\CJWConfigProcessor\Controller
+ */
 class ConfigProcessController extends AbstractController
 {
+    /**
+     * @var bool Not of much use at the moment.
+     */
     private $showFavouritesOutsideDedicatedView;
 
-    public function __construct (
-        ContainerInterface $symContainer,
-        ConfigResolverInterface $ezConfigResolver,
-        RequestStack $symRequestStack
-    )
+    /**
+     * ConfigProcessController constructor.
+     *
+     * @param ContainerInterface $symContainer
+     * @param ConfigResolverInterface $ezConfigResolver
+     * @param RequestStack $symRequestStack
+     */
+    public function __construct (ContainerInterface $symContainer, ConfigResolverInterface $ezConfigResolver, RequestStack $symRequestStack)
     {
         $this->container = $symContainer;
         ConfigProcessCoordinator::initializeCoordinator($symContainer,$ezConfigResolver,$symRequestStack);
@@ -45,6 +57,12 @@ public function __construct (
             $this->container->getParameter("cjw.favourite_parameters.display_everywhere");
     }
 
+    /**
+     * Currently unused function to only render the base layout template without any
+     * processed configuration or additional functionality.
+     *
+     * @return Response|null Returns the baselayout template to be rendered or an exception if something went wrong.
+     */
     public function getStartPage () {
         try {
             ConfigProcessCoordinator::startProcess();
@@ -55,7 +73,16 @@ public function getStartPage () {
         return $this->render("@CJWConfigProcessor/pagelayout.html.twig");
     }
 
-    public function getParameterList () {
+    /**
+     * Responsible for delivering the processed configuration for the frontend.
+     * Takes the processed configuration and renders it into a template.
+     *
+     * @return Response|null Returns a rendered template.
+     *
+     * @throws InvalidArgumentException If something went wrong with the caching mechanism, this exception is thrown.
+     */
+    public function getParameterList ()
+    {
         try {
             $parameters = ConfigProcessCoordinator::getProcessedParameters();
             $favourites = $this->showFavouritesOutsideDedicatedView ?
@@ -75,7 +102,19 @@ public function getParameterList () {
         }
     }
 
-    public function getSpecificSAParameters (Request $request, string $siteAccess = null) {
+    /**
+     * Responsible for bringing the single view of specific site access parameters into the frontend.
+     * If not site access context is given to the function, then simply the current site access of the request is used.
+     *
+     * @param Request $request The request made to the Symfony server.
+     * @param string $siteAccess The optional site access context, if non is given, then the current one of the request is used.
+     *
+     * @return Response|null Returns a rendered template with site access specific parameters.
+     *
+     * @throws InvalidArgumentException
+     */
+    public function getSpecificSAParameters (Request $request, $siteAccess = null)
+    {
         try {
             $specSAParameters = ConfigProcessCoordinator::getParametersForSiteAccess($siteAccess);
             $processedParameters = ConfigProcessCoordinator::getProcessedParameters();
@@ -110,17 +149,27 @@ public function getSpecificSAParameters (Request $request, string $siteAccess =
         );
     }
 
-    public function compareSiteAccesses (
-        string $firstSiteAccess,
-        string $secondSiteAccess,
-        string $limiter = null
-    ) {
+    /**
+     * Responsible for providing the site access comparison view to the bundle frontend.
+     *
+     * @param string $firstSiteAccess The first site access context for the first list of parameters in the comparison.
+     * @param string $secondSiteAccess The second site access context for the second list of parameters in the comparison.
+     * @param string|null $limiter An optional filter for the comparison (can be for common parameters only or uncommon, no filter if nothing is sent).
+     *
+     * @return Response|null Returns the rendered comparison template.
+     *
+     * @throws Exception Throws an exception if somethin went wrong during the process.
+     */
+    public function compareSiteAccesses ($firstSiteAccess, $secondSiteAccess, $limiter = null)
+    {
+        // Determine and retrieve the site access configuration for the two site accesses.
         $processedParameters = ConfigProcessCoordinator::getProcessedParameters();
         $resultParameters = $this->retrieveParamsForSiteAccesses($firstSiteAccess,$secondSiteAccess);
         $resultFavourites =
             $this->retrieveFavouritesForSiteAccesses($processedParameters,$firstSiteAccess,$secondSiteAccess);
         $limiterString = "Default Comparison";
 
+        // Filter the results if one is set.
         if ($limiter === "commons") {
             $resultParameters = Utility::removeUncommonParameters($resultParameters[0],$resultParameters[1]);
             $resultFavourites = Utility::removeUncommonParameters($resultFavourites[0],$resultFavourites[1]);
@@ -131,6 +180,7 @@ public function compareSiteAccesses (
             $limiterString = "Differences Comparison";
         }
 
+        // Provide the different values to the templates.
         $firstSiteAccessParameters = $resultParameters[0];
         $secondSiteAccessParameters = $resultParameters[1];
 
@@ -158,7 +208,16 @@ public function compareSiteAccesses (
         );
     }
 
-    public function getFavourites (string $siteAccess = null): Response
+    /**
+     * Retrieve the favourite parameters for the dedicated favourites view.
+     *
+     * @param string $siteAccess The (optional) site access context in which to view the favourite parameters.
+     *
+     * @return Response Returns the rendered favourite view template.
+     *
+     * @throws InvalidArgumentException Throws this error if something went wrong with the caching mechanism behind the favourites.
+     */
+    public function getFavourites ($siteAccess = null): Response
     {
         try {
             $processedParameters = ConfigProcessCoordinator::getProcessedParameters();
@@ -185,7 +244,18 @@ public function getFavourites (string $siteAccess = null): Response
         );
     }
 
-    public function getFavouriteKeyList (): Response {
+    /**
+     * Returns only a list of keys of the parameters that have been marked as favourites. It returns these
+     * in a json format for further processing in the frontend.
+     *
+     * <br>Example format for the keys: ["favourite.key.one", "favourite.key.second", "third.favourite.key"]
+     *
+     * @return Response Returns the list of favourite parameter keys as a flat json array.
+     *
+     * @throws InvalidArgumentException Throws this error if something went wrong with the caching mechanism behind the favourite parameters.
+     */
+    public function getFavouriteKeyList (): Response
+    {
         try {
             $processedParameters = ConfigProcessCoordinator::getProcessedParameters();
         } catch (Exception $error) {
@@ -198,7 +268,20 @@ public function getFavouriteKeyList (): Response {
         return $this->json($favourites);
     }
 
-    public function saveFavourites(Request $request): Response {
+    /**
+     * Allows saving a or multiple parameter keys as favourites in the application based on a sent
+     * json array of keys.
+     *
+     * <br>Example format for the keys: ["favourite.key.one", "favourite.key.second", "third.favourite.key"]
+     *
+     * @param Request $request The request which includes the favourite keys a json array.
+     *
+     * @return Response Returns 200 if no error was encountered with the sent data.
+     *
+     * @throws InvalidArgumentException Throws this error if something went wrong with the caching mechanism behind the favourite parameters.
+     */
+    public function saveFavourites(Request $request): Response
+    {
         $requestData = $request->getContent();
 
         try {
@@ -212,7 +295,20 @@ public function saveFavourites(Request $request): Response {
         return new Response(null, 200);
     }
 
-    public function removeFavourites (Request $request): Response {
+    /**
+     * Allows removing a or multiple parameter keys from the favourites in the application based on a
+     * sent json array of keys.
+     *
+     * <br>Example format for the keys: ["favourite.key.one", "favourite.key.second", "third.favourite.key"]
+     *
+     * @param Request $request The request which includes the keys to be removed as a json array.
+     *
+     * @return Response Returns 200 if no error was encountered with the sent data.
+     *
+     * @throws InvalidArgumentException Throws this error if something went wrong with the caching mechanism behind the favourite parameters.
+     */
+    public function removeFavourites (Request $request): Response
+    {
         $requestData = $request->getContent();
 
         try {
@@ -226,7 +322,18 @@ public function removeFavourites (Request $request): Response {
         return new Response(null, 200);
     }
 
-    public function downloadParameterListAsTextFile(string $downloadDenominator): BinaryFileResponse {
+    /**
+     * Allows to determine a specific list of parameters to be brought into a file representation and
+     * made available for download by the user.
+     *
+     * @param string $downloadDenominator A string which determines which parameters are supposed to be written to
+     *                                    a file ("all_parameters" = all parameters, "favourites" = only favourites,
+     *                                    "[site access]" all parameters for that site access).
+     *
+     * @return BinaryFileResponse Returns the file which has been created through the selected parameters.
+     */
+    public function downloadParameterListAsTextFile($downloadDenominator): BinaryFileResponse
+    {
         try {
             if ($downloadDenominator === "all_parameters") {
                 $resultingFile = ParametersToFileWriter::writeParametersToFile(
@@ -266,10 +373,19 @@ public function downloadParameterListAsTextFile(string $downloadDenominator): Bi
         return $response;
     }
 
-    private function retrieveParamsForSiteAccesses (
-        string $firstSiteAccess,
-        string $secondSiteAccess
-    ) {
+    /**
+     * Helper function to determine the specific parameters for both given site access contexts at the same time.
+     * It returns the found parameters in an array in which the first entry marks all the parameters for the first
+     * site access and the second every parameter for the second site access.
+     *
+     * @param string $firstSiteAccess The first site access for which to retrieve parameters.
+     * @param string $secondSiteAccess The second site access for which to retrieve parameters.
+     *
+     * @return array A two dimensional array of arrays in which the first entry includes the parameters for the first site access
+     *               and the second entry contains the parameters for the second site access.
+     */
+    private function retrieveParamsForSiteAccesses ($firstSiteAccess, $secondSiteAccess)
+    {
         $firstSiteAccessParameters = [];
         $secondSiteAccessParameters = [];
 
@@ -288,11 +404,22 @@ private function retrieveParamsForSiteAccesses (
         return [$firstSiteAccessParameters,$secondSiteAccessParameters];
     }
 
-    private function retrieveFavouritesForSiteAccesses(
-        array $processedParameters,
-        string $firstSiteAccess,
-        string $secondSiteAccess
-    ) {
+    /**
+     * Helper function to determine the favourite parameters for both given site access contexts at the same time.
+     * It returns the found parameters in an array in which the first entry marks all the parameters for the first
+     * site access and the second every parameter for the second site access.
+     *
+     * @param array $processedParameters The entire processed Symfony configuration to determine the favourite parameters if non had been set yet.
+     * @param string $firstSiteAccess The first site access for which to retrieve favourites.
+     * @param string $secondSiteAccess The second site access for which to retrieve favourites.
+     *
+     * @return array A two dimensional array of arrays in which the first entry includes the parameters for the first site access
+     *               and the second entry contains the parameters for the second site access.
+     *
+     * @throws InvalidArgumentException Throws this error if something went wrong with the caching mechanism behind the favourites.
+     */
+    private function retrieveFavouritesForSiteAccesses(array $processedParameters, $firstSiteAccess, $secondSiteAccess)
+    {
         $firstFavourites = [];
         $secondFavourites = [];
 

Controller/ConfigProcessLocationInfoController.php

@@ -7,20 +7,41 @@
 use CJW\CJWConfigProcessor\src\LocationAwareConfigLoadBundle\LocationRetrievalCoordinator;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\DependencyInjection\ContainerInterface;
+use Symfony\Component\HttpFoundation\JsonResponse;
 
+/**
+ * Class ConfigProcessLocationInfoController is a controller designed to enable frontend integration with getting locations
+ * for specific parameters.
+ *
+ * @package CJW\CJWConfigProcessor\Controller
+ */
 class ConfigProcessLocationInfoController extends AbstractController
 {
 
     private $projectDir;
 
-    public function __construct(ContainerInterface $symContainer, string $projectDir)
+    /**
+     * ConfigProcessLocationInfoController constructor.
+     * @param ContainerInterface $symContainer
+     * @param string $projectDir
+     */
+    public function __construct(ContainerInterface $symContainer, $projectDir)
     {
         $this->projectDir = $projectDir;
         $this->container = $symContainer;
         LocationRetrievalCoordinator::initializeCoordinator();
     }
 
-    public function retrieveLocationsForParameter (string $parameter, string $withSiteAccess) {
+    /**
+     * Responsible for determining the location info for a given parameter.
+     *
+     * @param string $parameter The key to the parameter to retrieve locations for.
+     * @param string $withSiteAccess String representation of a boolean to determine, whether to view the parameter key in a site access context.
+     *
+     * @return JsonResponse A json response which includes the paths where the parameter has been found and the values attached to these paths (also site access if set to true).
+     */
+    public function retrieveLocationsForParameter ($parameter, $withSiteAccess): JsonResponse
+    {
         $saPresent = ($withSiteAccess && $withSiteAccess !== "false")?? false;
         $group = null;
 

DependencyInjection/CJWConfigProcessorExtension.php

@@ -13,6 +13,15 @@
 class CJWConfigProcessorExtension extends Extension
 {
 
+    /**
+     * @override
+     * Standard Symfony extension loading function.
+     *
+     * @param array $configs
+     * @param ContainerBuilder $container
+     *
+     * @throws \Exception
+     */
     public function load(array $configs, ContainerBuilder $container)
     {
         $loader = new Loader\YamlFileLoader( $container, new FileLocator(__DIR__ . '/../Resources/config') );
@@ -24,6 +33,12 @@ public function load(array $configs, ContainerBuilder $container)
         $this->handleFavouriteParamConfig($config, $container);
     }
 
+    /**
+     * Responsible for handling the configuration specifically for the custom parameters feature.
+     *
+     * @param array $config The configuration array to be parsed into actual container parameters.
+     * @param ContainerBuilder $container The container to add the parameters to.
+     */
     private function handleCustomParamConfig (array $config, ContainerBuilder $container) {
         if (!isset($config["custom_site_access_parameters"])) {
             $allowParameters = false;
@@ -38,6 +53,12 @@ private function handleCustomParamConfig (array $config, ContainerBuilder $conta
         $container->setParameter("cjw.custom_site_access_parameters.scan_parameters", $scanParameters);
     }
 
+    /**
+     * Responsible for handling the configuration specifically for the favourite parameters feature.
+     *
+     * @param array $config The configuration array to be parsed into actual container parameters.
+     * @param ContainerBuilder $container The container to add the parameters to.
+     */
     private function handleFavouriteParamConfig (array $config, ContainerBuilder $container) {
         if (!isset($config["favourite_parameters"])) {
             $allowParameters = false;