From 9c37b26d44d72c41b4cc9cb3d95149998ea2bc99 Mon Sep 17 00:00:00 2001
From: "valentin.pocotilenco" <valentin.pocotilenco@renam.md>
Date: Tue, 3 Oct 2023 23:37:28 +0300
Subject: [PATCH] added phpDoc to tool related methods
---
.../Controllers/AttrReleaseTestController.php | 7 +-
app/Http/Controllers/ResultsController.php | 20 +++-
.../Controllers/ServiceProviderController.php | 15 ++-
app/Libraries/EarcUtils.php | 98 +++++++++++++++++++
4 files changed, 136 insertions(+), 4 deletions(-)
diff --git a/app/Http/Controllers/AttrReleaseTestController.php b/app/Http/Controllers/AttrReleaseTestController.php
index b2a7ec1..9ffe617 100755
--- a/app/Http/Controllers/AttrReleaseTestController.php
+++ b/app/Http/Controllers/AttrReleaseTestController.php
@@ -8,8 +8,11 @@ use Illuminate\Http\Request;
class AttrReleaseTestController extends Controller
{
/**
- * Initiates the test
- *
+ * Initiates the attribute release test
+ *
+ * @param Request $request
+ *
+ * @return Redirect
*/
public function __invoke(Request $request)
{
diff --git a/app/Http/Controllers/ResultsController.php b/app/Http/Controllers/ResultsController.php
index 31ee41e..0d092b6 100755
--- a/app/Http/Controllers/ResultsController.php
+++ b/app/Http/Controllers/ResultsController.php
@@ -12,7 +12,12 @@ use Illuminate\Http\Request;
class ResultsController extends Controller
{
/**
- * Show Results.
+ * Show verdict for Idp
+ *
+ * @param Request $request
+ * @param mixed $test_id
+ *
+ * @return Response
*/
public function __invoke(Request $request, $test_id)
{
@@ -77,6 +82,11 @@ class ResultsController extends Controller
}
}
+ /**
+ * Retrieve and parse test log for all entities.
+ *
+ * @return array
+ */
public function getHistoricalResults()
{
$idps = IdpResult::all()->unique('idp_entity_id');
@@ -109,6 +119,14 @@ class ResultsController extends Controller
return $historical_results;
}
+ /**
+ * Retrieve and parse test log for single entity
+ *
+ * @param Request $request
+ * @param mixed $idp_entity_id
+ *
+ * @return array
+ */
public function getSingleHistoricalResult(Request $request, $idp_entity_id)
{
$idp_entity_id = urldecode($idp_entity_id);
diff --git a/app/Http/Controllers/ServiceProviderController.php b/app/Http/Controllers/ServiceProviderController.php
index ecae996..aa90a5e 100755
--- a/app/Http/Controllers/ServiceProviderController.php
+++ b/app/Http/Controllers/ServiceProviderController.php
@@ -15,7 +15,10 @@ class ServiceProviderController extends Controller
{
/**
* Handles the SP part
- *
+ *
+ * @param Request $request
+ *
+ * @return Redirect
*/
public function __invoke(Request $request)
{
@@ -52,6 +55,16 @@ class ServiceProviderController extends Controller
}
}
+ /**
+ * Parse and store test results.
+ * - retrieve and store IdP info
+ * - store eduPersonTargetedID attributes info
+ * - store obtained score
+ *
+ * @param mixed $request
+ *
+ * @return string
+ */
private function store_results($request){
//Store the attributes
$idp_entity_id = $request->server->get('SHIB_Shib-Identity-Provider');
diff --git a/app/Libraries/EarcUtils.php b/app/Libraries/EarcUtils.php
index f10064d..2ff841b 100755
--- a/app/Libraries/EarcUtils.php
+++ b/app/Libraries/EarcUtils.php
@@ -7,6 +7,13 @@ use SimpleSAML\Module\metarefresh\MetaLoader;
class EarcUtils
{
+ /**
+ * Return user friendly name of checked categories
+ *
+ * @param mixed $value
+ *
+ * @return string
+ */
public function getEncatName($value)
{
switch ($value) {
@@ -23,6 +30,13 @@ class EarcUtils
return $ret;
}
+ /**
+ * Retrieve metadata of SP entity by ID from metadata files in SimpleSAMLphp
+ *
+ * @param mixed $sp_entity_id_input
+ *
+ * @return array
+ */
public static function getSpMetadata($sp_entity_id_input)
{
include Configuration::getInstance()->getPathValue('attributenamemapdir', 'attributemap/').'oid2name.php';
@@ -68,6 +82,11 @@ class EarcUtils
}
}
+ /**
+ * Parse attribute OID to hunam readable attributes
+ *
+ * @return array
+ */
public static function getAttributeMap()
{
include Configuration::getInstance()->getPathValue('attributenamemapdir', 'attributemap/').'oid2name.php';
@@ -75,6 +94,13 @@ class EarcUtils
return $attributemap;
}
+ /**
+ * Retrieve metadata of IdP entity by ID from metadata files in SimpleSAMLphp
+ *
+ * @param mixed $entityid
+ *
+ * @return array
+ */
public static function getIdpMetadata($entityid)
{
$metaloader = new MetaLoader(null);
@@ -87,6 +113,13 @@ class EarcUtils
return $metadata[$entityid];
}
+ /**
+ * Get IdP Name from metadata files in SimpleSAMLphp
+ *
+ * @param mixed $entityid
+ *
+ * @return string
+ */
public static function getIdentityProviderName($entityid)
{
$idp_metadata = self::getIdpMetadata($entityid);
@@ -104,6 +137,13 @@ class EarcUtils
}
}
+ /**
+ * Check research-and-scholarship support on IdP entity
+ *
+ * @param mixed $idp_metadata
+ *
+ * @return bool
+ */
public static function isRnsSupportIndicated($idp_metadata)
{
$ret = false;
@@ -118,6 +158,13 @@ class EarcUtils
return $ret;
}
+ /**
+ * Check research-and-scholarship support on SP entity
+ *
+ * @param mixed $sp_metadata
+ *
+ * @return bool
+ */
public static function isRnsIndicated($sp_metadata)
{
$ret = false;
@@ -132,6 +179,14 @@ class EarcUtils
return $ret;
}
+ /**
+ * Check eduPerson mail based or schacHomeOrganizationType attributes returned value
+ *
+ * @param mixed $attributeName
+ * @param mixed $attributeValue
+ *
+ * @return mixed
+ */
public static function checkAttributeSyntax($attributeName, $attributeValue)
{
$failed = array();
@@ -151,6 +206,13 @@ class EarcUtils
}
}
+ /**
+ * Check minimal sufficient set of released attributes
+ *
+ * @param mixed $released_attributes
+ *
+ * @return bool
+ */
public static function isMinimalSubsetSent($released_attributes)
{
$minimalSubset = array('eduPersonPrincipalName', 'mail', 'displayName');
@@ -163,6 +225,13 @@ class EarcUtils
return true;
}
+ /**
+ * Check basic set of released attributes
+ *
+ * @param mixed $released_attributes
+ *
+ * @return bool
+ */
public static function isBasicSubsetSent($released_attributes)
{
$minimalSubset = array('eduPersonPrincipalName', 'eduPersonTargetedID', 'eduPersonUniqueId');
@@ -175,6 +244,14 @@ class EarcUtils
return false;
}
+ /**
+ * Check attributes redundancy
+ *
+ * @param mixed $attributeName
+ * @param mixed $released_attributes
+ *
+ * @return bool
+ */
public static function canBeRedundant($attributeName, $released_attributes)
{
if (($attributeName == 'schacHomeOrganization' && (array_key_exists('eduPersonPrincipalName', $released_attributes) || array_key_exists('eduPersonScopedAffiliation', $released_attributes))) ||
@@ -194,6 +271,18 @@ class EarcUtils
}
}
+ /**
+ * Additional analysis of released attributes for more precise evaluation
+ *
+ * @param mixed $mark
+ * @param mixed $sp
+ * @param mixed $released_attributes
+ * @param mixed $superfluous_attributes
+ * @param mixed $idp_metadata
+ * @param mixed $non_personal_attributes
+ *
+ * @return string
+ */
public static function getExtraPoints($mark, $sp, $released_attributes, $superfluous_attributes, $idp_metadata, $non_personal_attributes)
{
$ret = '';
@@ -259,6 +348,15 @@ class EarcUtils
}
}
+ /**
+ * Released attributes analysis and verdict calculation
+ *
+ * @param mixed $sp_entity_id
+ * @param mixed $released_attributes
+ * @param mixed $idp_entityid
+ *
+ * @return array
+ */
public static function calculateVerdictForAnSP($sp_entity_id, $released_attributes, $idp_entityid)
{
$additional_information = array();
--
GitLab