Skip to content

Commit

Permalink
Documentation Overhaul (derived from the very same commit in the ezpl…
Browse files Browse the repository at this point in the history 
…atform 2.5 version) for issues #5, #6 and #4

- Added or improved documentation for every php class of the bundle

- Refactored code for every function and class of the bundle to fit Symfony's coding style more

- In ConfigProcessController.php and routing.yaml for parameter list file download changed the parameter name from "downloadDenominator" to "downloadDescriptor" so it is more clear what the parameter does

- Improved ParametersToFileWriter.php and added checks and editions for special character within keys and also values in order to improve the file representation and keep the output valid yaml (there will hopefully soon be even more improvements to the functionality)
  • Loading branch information
JAC - Frederic Bauer committed Dec 21, 2020
1 parent 23f6292 commit f32d91f
Show file tree
Hide file tree
Showing 27 changed files with 1,005 additions and 381 deletions.
181 changes: 147 additions & 34 deletions Controller/ConfigProcessController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,27 @@
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
use Symfony\Component\HttpKernel\Exception\HttpException;

/**
* Class ConfigProcessController is the main controller of the bundle and responsible for bringing the
* processed configuration into the 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);
Expand All @@ -45,7 +57,14 @@ public function __construct (
$this->container->getParameter("cjw.favourite_parameters.display_everywhere");
}

public function getStartPage () {
/**
* 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();
} catch (Exception $e) {
Expand All @@ -55,7 +74,14 @@ 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 or delivers an error response in case of an error.
*/
public function getParameterList (): ?Response
{
try {
$parameters = ConfigProcessCoordinator::getProcessedParameters();
$favourites = $this->showFavouritesOutsideDedicatedView ?
Expand All @@ -75,7 +101,17 @@ 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|null $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.
*/
public function getSpecificSAParameters (Request $request, string $siteAccess = null): Response
{
try {
$specSAParameters = ConfigProcessCoordinator::getParametersForSiteAccess($siteAccess);
$processedParameters = ConfigProcessCoordinator::getProcessedParameters();
Expand Down Expand Up @@ -110,17 +146,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 something went wrong during the process.
*/
public function compareSiteAccesses (string $firstSiteAccess, string $secondSiteAccess, string $limiter = null): ?Response
{
// 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]);
Expand All @@ -131,6 +177,7 @@ public function compareSiteAccesses (
$limiterString = "Differences Comparison";
}

// Provide the different values to the templates.
$firstSiteAccessParameters = $resultParameters[0];
$secondSiteAccessParameters = $resultParameters[1];

Expand Down Expand Up @@ -158,6 +205,13 @@ public function compareSiteAccesses (
);
}

/**
* Retrieve the favourite parameters for the dedicated favourites view.
*
* @param string|null $siteAccess The (optional) site access context in which to view the favourite parameters.
*
* @return Response Returns the rendered favourite view template.
*/
public function getFavourites (string $siteAccess = null): Response
{
try {
Expand All @@ -168,7 +222,7 @@ public function getFavourites (string $siteAccess = null): Response

$siteAccesses = Utility::determinePureSiteAccesses($processedParameters);
$groups = Utility::determinePureSiteAccessGroups($processedParameters);
$siteAccessesToScanFor = $siteAccess?
$siteAccessesToScanFor = $siteAccess ?
ConfigProcessCoordinator::getSiteAccessListForController($siteAccess) : [];

$favourites =
Expand All @@ -185,7 +239,16 @@ 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.
*/
public function getFavouriteKeyList (): Response
{
try {
$processedParameters = ConfigProcessCoordinator::getProcessedParameters();
} catch (Exception $error) {
Expand All @@ -198,7 +261,18 @@ 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 in a json array.
*
* @return Response Returns 200 if no error was encountered with the sent data.
*/
public function saveFavourites(Request $request): Response
{
$requestData = $request->getContent();

try {
Expand All @@ -212,7 +286,18 @@ 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.
*/
public function removeFavourites (Request $request): Response
{
$requestData = $request->getContent();

try {
Expand All @@ -226,26 +311,36 @@ 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 $downloadDescriptor 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(string $downloadDescriptor): BinaryFileResponse
{
try {
if ($downloadDenominator === "all_parameters") {
if ($downloadDescriptor === "all_parameters") {
$resultingFile = ParametersToFileWriter::writeParametersToFile(
ConfigProcessCoordinator::getProcessedParameters(),
$downloadDenominator
ConfigProcessCoordinator::getProcessedParameters()
);
} else if ($downloadDenominator === "favourites") {
} else if ($downloadDescriptor === "favourites") {
$resultingFile = ParametersToFileWriter::writeParametersToFile(
FavouritesParamCoordinator::getFavourites(
ConfigProcessCoordinator::getProcessedParameters()
),
$downloadDenominator
$downloadDescriptor
);
} else {
$resultingFile = ParametersToFileWriter::writeParametersToFile(
ConfigProcessCoordinator::getParametersForSiteAccess(
$downloadDenominator
$downloadDescriptor
),
$downloadDenominator
$downloadDescriptor
);
}
} catch (InvalidArgumentException | Exception $error) {
Expand All @@ -266,10 +361,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 (string $firstSiteAccess, string $secondSiteAccess): array
{
$firstSiteAccessParameters = [];
$secondSiteAccessParameters = [];

Expand All @@ -288,11 +392,20 @@ 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.
*/
private function retrieveFavouritesForSiteAccesses(array $processedParameters, string $firstSiteAccess, string $secondSiteAccess): array
{
$firstFavourites = [];
$secondFavourites = [];

Expand Down
29 changes: 28 additions & 1 deletion Controller/ConfigProcessLocationInfoController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,47 @@
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 the retrieving
* locations for specific parameters feature.
*
* @package CJW\CJWConfigProcessor\Controller
*/
class ConfigProcessLocationInfoController extends AbstractController
{

/**
* @var string The directory root of the project.
*/
private $projectDir;

/**
* ConfigProcessLocationInfoController constructor.
*
* @param ContainerInterface $symContainer
* @param string $projectDir
*/
public function __construct(ContainerInterface $symContainer, string $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 (string $parameter, string $withSiteAccess): JsonResponse
{
$saPresent = ($withSiteAccess && $withSiteAccess !== "false")?? false;
$group = null;

Expand Down
Loading

0 comments on commit f32d91f

Please sign in to comment.