From 1799d56726f42e82f65a1054a2a823746dd2a4de Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Fri, 13 Dec 2024 17:21:52 +0100 Subject: [PATCH] Enhance `Limitation\Type` phpdoc One docblock per constant. --- src/contracts/Limitation/Type.php | 50 +++++++++++++++---- src/lib/Limitation/LocationLimitationType.php | 5 +- src/lib/Limitation/SubtreeLimitationType.php | 5 +- 3 files changed, 45 insertions(+), 15 deletions(-) diff --git a/src/contracts/Limitation/Type.php b/src/contracts/Limitation/Type.php index b93aa4a5c4..cb5410d705 100644 --- a/src/contracts/Limitation/Type.php +++ b/src/contracts/Limitation/Type.php @@ -21,26 +21,57 @@ interface Type { /** - * Constants for return value of {@see evaluate()}. + * Access is granted. * - * Currently ACCESS_ABSTAIN must mean that evaluate does not support the provided $object or $targets, - * this is currently only supported by role limitations as policy limitations should not allow this. + * Constant for return value of {@see Type::evaluate()}. * * Note: In future version constant values might change to 1, 0 and -1 as used in Symfony. * * @since 5.3.2 */ public const ACCESS_GRANTED = true; + + /** + * The type abstains from voting. + * + * Constant for return value of {@see Type::evaluate()}. + * + * Returning ACCESS_ABSTAIN must mean that evaluate does not support the provided $object or $targets, + * this is only supported by role limitations as policy limitations should not allow this. + * + * Note: In future version constant values might change to 1, 0 and -1 as used in Symfony. + * + * @since 5.3.2 + */ public const ACCESS_ABSTAIN = null; + + /** + * Access is denied. + * + * Constant for return value of {@see Type::evaluate()}. + * + * Note: In future version constant values might change to 1, 0 and -1 as used in Symfony. + * + * @since 5.3.2 + */ public const ACCESS_DENIED = false; /** - * Constants for valueSchema() return values. + * Limitation's value must be an array of location IDs. + * + * Constant for {@see Type::valueSchema()} return values. * - * Used in cases where a certain value is accepted but the options are to many to return as a hash of options. * GUI should typically present option to browse content tree to select limitation value(s). */ public const VALUE_SCHEMA_LOCATION_ID = 1; + + /** + * Limitation's value must be an array of location paths. + * + * Constant for {@see Type::valueSchema()} return values. + * + * GUI should typically present option to browse content tree to select limitation value(s). + */ public const VALUE_SCHEMA_LOCATION_PATH = 2; /** @@ -92,7 +123,7 @@ public function buildValue(array $limitationValues); * @param \Ibexa\Contracts\Core\Repository\Values\ValueObject[]|null $targets An array of location, parent or "assignment" * objects, if null: none where provided by caller * - * @return bool|null Returns one of ACCESS_* constants + * @return bool|null Returns one of ACCESS_* constants, {@see Type::ACCESS_GRANTED}, {@see Type::ACCESS_ABSTAIN}, or {@see Type::ACCESS_DENIED}. */ public function evaluate(APILimitationValue $value, APIUserReference $currentUser, APIValueObject $object, array $targets = null); @@ -112,9 +143,10 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren /** * Returns info on valid $limitationValues. * - * @return mixed[]|int In case of array, a hash with key as valid limitations value and value as human readable name - * of that option, in case of int on of VALUE_SCHEMA_* constants. - * Note: The hash might be an instance of Traversable, and not a native php array. + * @return array|Traversable|int In case of array, a hash with key as valid limitations value and value as human-readable name + * of that option. Note: The hash might be an instance of Traversable instead of a native PHP array. + * In case of int, one of VALUE_SCHEMA_* constants. Used in cases where a certain value is accepted + * but the options are too many to return as a hash of options. */ public function valueSchema(); } diff --git a/src/lib/Limitation/LocationLimitationType.php b/src/lib/Limitation/LocationLimitationType.php index 3c7cd6571f..e0ce4ec2b6 100644 --- a/src/lib/Limitation/LocationLimitationType.php +++ b/src/lib/Limitation/LocationLimitationType.php @@ -224,10 +224,9 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren } /** - * Returns info on valid $limitationValues. + * Returns an integer code meaning that the value must be an array listing location IDs. * - * @return mixed[]|int In case of array, a hash with key as valid limitations value and value as human readable name - * of that option, in case of int on of VALUE_SCHEMA_ constants. + * @return int {@see LocationLimitationType::VALUE_SCHEMA_LOCATION_ID} */ public function valueSchema() { diff --git a/src/lib/Limitation/SubtreeLimitationType.php b/src/lib/Limitation/SubtreeLimitationType.php index c642ec64e8..3ceb4cee0d 100644 --- a/src/lib/Limitation/SubtreeLimitationType.php +++ b/src/lib/Limitation/SubtreeLimitationType.php @@ -258,10 +258,9 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren } /** - * Returns info on valid $limitationValues. + * Returns an integer code meaning that the value must be an array listing location paths. * - * @return mixed[]|int In case of array, a hash with key as valid limitations value and value as human readable name - * of that option, in case of int on of VALUE_SCHEMA_ constants. + * @return int {@see SubtreeLimitationType::VALUE_SCHEMA_LOCATION_PATH} */ public function valueSchema() {