From c8e43746def12580267bf4a9396b0e5dcf1caaa1 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Fri, 6 Dec 2024 14:39:24 +0100 Subject: [PATCH 01/32] Enhance `DateMetadata::TRASHED` phpdoc --- .../Values/Content/Query/Criterion/DateMetadata.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php index 78d5397468..f4dc7e449b 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php @@ -24,13 +24,13 @@ * BETWEEN: matches content whose date is between (included) the TWO given timestamps * * Example: - * + * ``` * $createdCriterion = new Criterion\DateMetadata( * Criterion\DateMetadata::CREATED, * Operator::GTE, - * strtotime( 'yesterday' ) + * strtotime('yesterday') * ); - * + * ``` */ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriterion { @@ -41,7 +41,7 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri public const PUBLISHED = 'published'; /** - * (applies to TrashService::findTrashItems only). + * Applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems() only. */ public const TRASHED = 'trashed'; From fb7804de2d57dbcce3729fe375d9df3fb73cc988 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 10 Dec 2024 19:35:09 +0100 Subject: [PATCH 02/32] Enhance `Criterion::getSpecifications()` phpdoc --- .../Repository/Values/Content/Query/Criterion.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion.php b/src/contracts/Repository/Values/Content/Query/Criterion.php index 7e80664698..e05ef03558 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion.php @@ -118,12 +118,12 @@ public function __construct(?string $target, ?string $operator, $value, ?Value $ * * Returns the combination of the Criterion's supported operator/value, * as an array of {@see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications} objects - * - Operator is one supported Operator, as an Operator::* constant - * - ValueType is the type of input value this operator requires, either array or single - * - SupportedTypes is an array of types the operator will accept - * - ValueCountLimitation is an integer saying how many values are expected. + * - `$operator` is a supported {@see Operator} constant. + * - `$valueFormat is the type of input value this operator requires, either array ({@see Specifications::FORMAT_ARRAY}) or single ({@see Specifications::FORMAT_SINGLE}). + * - `$valueTypes` are bitwise flags of types the operator will accept ({@see Specifications::TYPE_BOOLEAN}, {@see Specifications::TYPE_INTEGER}, and/or {@see Specifications::TYPE_STRING}). + * - `$valueCount` is an integer saying how many values are expected. * - * + * ``` * // IN and EQ are supported * return [ * // The EQ operator expects a single value, either as an integer or a string @@ -139,7 +139,7 @@ public function __construct(?string $target, ?string $operator, $value, ?Value $ * Specifications::TYPE_INTEGER | Specifications::TYPE_STRING * ) * ] - * + * ``` * * @return \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications[] */ From db1c8a133e6744e40e4c803cc5cc2f8dc1f6c1b1 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 10 Dec 2024 19:35:43 +0100 Subject: [PATCH 03/32] Enhance `Specifications` phpdoc --- .../Content/Query/Criterion/Operator/Specifications.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php b/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php index f22eeb6973..73c61c5d20 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php @@ -11,9 +11,7 @@ /** * This class is used by Criteria to describe which operators they support. * - * Instances of this class are returned in an array by the Criterion::getSpecifications() method - * - * @see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion::getSpecifications() + * Instances of this class are returned in an array by the {@see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion::getSpecifications()} method. */ class Specifications { From 784ba416abab7c564bde614b460e0590b55baebc Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 11 Dec 2024 13:00:52 +0100 Subject: [PATCH 04/32] Capable.php: Fix phpdoc summary Don't use advanced format in summary, it won't be rendered. --- src/contracts/Search/Capable.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/contracts/Search/Capable.php b/src/contracts/Search/Capable.php index a6504d9595..11cb1cfb1d 100644 --- a/src/contracts/Search/Capable.php +++ b/src/contracts/Search/Capable.php @@ -9,6 +9,8 @@ namespace Ibexa\Contracts\Core\Search; /** + * Capability interface for search engines. + * * Capability interface for search engines needed for {@see \Ibexa\Contracts\Core\Repository\SearchService::supports()}. * * @since 6.12 And ported to 6.7.6 for search engine forward compatibility. From 570e15a450b78c7588a219682cb435ba7abfb8ee Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 11 Dec 2024 16:59:46 +0100 Subject: [PATCH 05/32] VersionBuilder.php: Fix phpdoc summary, arrays and self usages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Don't use advanced format in summary, it won't be rendered. Define array key type, or it will be rendered as array phpDocumentor don't seem to understand self. --- .../Target/Builder/VersionBuilder.php | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/contracts/Limitation/Target/Builder/VersionBuilder.php b/src/contracts/Limitation/Target/Builder/VersionBuilder.php index baff618ec0..c4738544c0 100644 --- a/src/contracts/Limitation/Target/Builder/VersionBuilder.php +++ b/src/contracts/Limitation/Target/Builder/VersionBuilder.php @@ -14,6 +14,8 @@ use Ibexa\Core\Base\Exceptions\InvalidArgumentException; /** + * Version builder. + * * Builder of {@see \Ibexa\Contracts\Core\Limitation\Target\Version} instance. */ final class VersionBuilder @@ -28,6 +30,8 @@ public function build(): Target\Version /** * @param \Ibexa\Contracts\Core\Repository\Values\Content\Field[] $updatedFields + * + * @return VersionBuilder */ public function updateFields(array $updatedFields): self { @@ -41,7 +45,7 @@ public function updateFields(array $updatedFields): self * * @param array $languageCodes * - * @return self + * @return VersionBuilder * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException */ @@ -61,9 +65,9 @@ public function translateToAnyLanguageOf(array $languageCodes): self /** * Set intent to create Content from unspecified (yet) content type, any from the given list. * - * @param int[] $contentTypeIds + * @param array $contentTypeIds * - * @return self + * @return VersionBuilder * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException */ @@ -83,13 +87,13 @@ public function createFromAnyContentTypeOf(array $contentTypeIds): self /** * Set intent to change Version status. * - * Supported: VersionInfo::STATUS_DRAFT, VersionInfo::STATUS_PUBLISHED, VersionInfo::STATUS_ARCHIVED + * Supported: {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo::STATUS_DRAFT}, {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo::STATUS_PUBLISHED}, {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo::STATUS_ARCHIVED} * * @see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo * * @param int $status * - * @return self + * @return VersionBuilder * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException */ @@ -114,9 +118,9 @@ public function changeStatusTo(int $status): self * Set intent to update Content Version Fields. * * @param string|null $initialLanguageCode - * @param \Ibexa\Contracts\Core\Repository\Values\Content\Field[] $fields + * @param array $fields * - * @return self + * @return VersionBuilder */ public function updateFieldsTo(?string $initialLanguageCode, array $fields): self { @@ -138,9 +142,9 @@ static function (Field $field) { /** * Set intent to publish, to specified translations, all from the given list. * - * @param string[] $languageCodes + * @param array $languageCodes * - * @return self + * @return VersionBuilder * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException */ From cb84a02ec540326226920e1f832342c64eb3cfa7 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 11:20:26 +0100 Subject: [PATCH 06/32] ConstraintViolationAdapter's PHPDoc: Add a summary, reword description --- .../Generic/ValidationError/ConstraintViolationAdapter.php | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php b/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php index a7f63aa101..0d39e8ccf1 100644 --- a/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php +++ b/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php @@ -14,8 +14,10 @@ use Symfony\Component\Validator\ConstraintViolationInterface; /** - * {@see \Symfony\Component\Validator\ConstraintViolationInterface} to - * {@see \Ibexa\Contracts\Core\FieldType\ValidationError} adapter. + * Constraint violation validation error. + * + * Adapts {@see \Symfony\Component\Validator\ConstraintViolationInterface} to + * {@see \Ibexa\Contracts\Core\FieldType\ValidationError}. */ final class ConstraintViolationAdapter implements ValidationErrorInterface { From c80acf910ed0e03ea01c3d98a2cf4175e6d1c714 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 12:13:32 +0100 Subject: [PATCH 07/32] Enhance `Criterion::getSpecifications()` phpdoc --- .../Repository/Values/Content/Query/Criterion.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion.php b/src/contracts/Repository/Values/Content/Query/Criterion.php index e05ef03558..64e5faf370 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion.php @@ -118,10 +118,10 @@ public function __construct(?string $target, ?string $operator, $value, ?Value $ * * Returns the combination of the Criterion's supported operator/value, * as an array of {@see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications} objects - * - `$operator` is a supported {@see Operator} constant. - * - `$valueFormat is the type of input value this operator requires, either array ({@see Specifications::FORMAT_ARRAY}) or single ({@see Specifications::FORMAT_SINGLE}). - * - `$valueTypes` are bitwise flags of types the operator will accept ({@see Specifications::TYPE_BOOLEAN}, {@see Specifications::TYPE_INTEGER}, and/or {@see Specifications::TYPE_STRING}). - * - `$valueCount` is an integer saying how many values are expected. + * - {@see Specifications::$operator} is a supported {@see Operator} constant. + * - {@see Specifications::$valueFormat} is the type of input value this operator requires, either array ({@see Specifications::FORMAT_ARRAY}) or single ({@see Specifications::FORMAT_SINGLE}). + * - {@see Specifications::$valueTypes} are bitwise flags of types the operator will accept ({@see Specifications::TYPE_BOOLEAN}, {@see Specifications::TYPE_INTEGER}, and/or {@see Specifications::TYPE_STRING}). + * - {@see Specifications::$valueCount} is an integer saying how many values are expected. * * ``` * // IN and EQ are supported From 8253f7778fce9fc6bc82cc955b04365403ad8412 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 12:19:06 +0100 Subject: [PATCH 08/32] Enhance `DateMetadata::TRASHED` phpdoc --- .../Repository/Values/Content/Query/Criterion/DateMetadata.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php index f4dc7e449b..b18296252a 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php @@ -41,6 +41,8 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri public const PUBLISHED = 'published'; /** + * To search for contents based on when they have been sent to trash. + * * Applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems() only. */ public const TRASHED = 'trashed'; From abb184c2260f66270fa7e2602c888b3fc8250f2e Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 13:13:13 +0100 Subject: [PATCH 09/32] Enhance `DateMetadata` phpdoc --- .../Content/Query/Criterion/DateMetadata.php | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php index b18296252a..bde44bb36c 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php @@ -18,16 +18,16 @@ * A criterion that matches content based on one of the date metadata (created or modified). * * Supported Operators: - * EQ, IN: matches content whose date is or belongs to a list of timestamps - * GT, GTE: matches content whose date is greater than/greater than or equals the given timestamp - * LT, LTE: matches content whose date is lower than/lower than or equals the given timestamp - * BETWEEN: matches content whose date is between (included) the TWO given timestamps + * - {@see Operator::EQ EQ}, {@see Operator::IN IN}: matches content whose date is or belongs to a list of timestamps. + * - {@see Operator::GT GT}, {@see Operator::GTE GTE}: matches content whose date is greater than/greater than or equals the given timestamp. + * - {@see Operator::LT LT}, {@see Operator::LTE LTE}: matches content whose date is lower than/lower than or equals the given timestamp. + * - {@see Operator::BETWEEN BETWEEN}: matches content whose date is between TWO (included) given timestamps. * - * Example: + * The following example is a criterion for contents created yesterday or today: * ``` * $createdCriterion = new Criterion\DateMetadata( * Criterion\DateMetadata::CREATED, - * Operator::GTE, + * Criterion\Operator::GTE, * strtotime('yesterday') * ); * ``` @@ -43,7 +43,7 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri /** * To search for contents based on when they have been sent to trash. * - * Applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems() only. + * Applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems()} only. */ public const TRASHED = 'trashed'; @@ -59,8 +59,8 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri * * @throws \InvalidArgumentException If target is unknown * - * @param string $target One of DateMetadata::CREATED, DateMetadata::MODIFIED or DateMetadata::TRASHED (applies to TrashService::findTrashItems only) - * @param string $operator One of the Operator constants + * @param string $target One of {@see DateMetadata::CREATED}, {@see DateMetadata::MODIFIED}, or {@see DateMetadata::TRASHED} (applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems()} only) + * @param string $operator One of the {@see Operator} constants * @param mixed $value The match value, either as an array of as a single value, depending on the operator */ public function __construct(string $target, string $operator, $value) From 311961d42ccf993b198d6a69f1851d136188c3c7 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 13:31:12 +0100 Subject: [PATCH 10/32] Enhance `UserMetadata` phpdoc --- .../Content/Query/Criterion/UserMetadata.php | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php index 13f4775307..44d80610a0 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php @@ -19,16 +19,16 @@ * group, modifier). * * Supported Operators: - * EQ, IN: Matches the provided user ID(s) against the user IDs in the database + * - {@see Operator::EQ EQ}, {@see Operator::IN}: Matches the provided user ID(s) against the user IDs in the database. * - * Example: - * + * The following example is a criterion for contents owned by a user with ID 10 or 14: + * ``` * $createdCriterion = new Criterion\UserMetadata( * Criterion\UserMetadata::OWNER, - * Operator::IN, - * array( 10, 14 ) + * Criterion\Operator::IN, + * [10, 14] * ); - * + * ``` */ class UserMetadata extends Criterion implements TrashCriterion, FilteringCriterion { @@ -48,13 +48,13 @@ class UserMetadata extends Criterion implements TrashCriterion, FilteringCriteri public const MODIFIER = 'modifier'; /** - * Creates a new UserMetadata criterion on $metadata. + * Creates a new UserMetadata criterion. * * @throws \InvalidArgumentException If target is unknown * - * @param string $target One of UserMetadata::OWNER, UserMetadata::GROUP or UserMetadata::MODIFIED - * @param string|null $operator The operator the Criterion uses. If null is given, will default to Operator::IN if $value is an array, Operator::EQ if it is not. - * @param mixed $value The match value, either as an array of as a single value, depending on the operator + * @param string $target One of {@see UserMetadata::OWNER}, {@see UserMetadata::GROUP}, or {@see UserMetadata::MODIFIED}. + * @param string|null $operator The operator the Criterion uses. If null is given, will default to {@see Operator::IN} if $value is an array, {@see Operator::EQ} if it isn't. + * @param mixed $value The match value, either as an array of as a single value, depending on the operator. */ public function __construct(string $target, ?string $operator, $value) { From 160b5b93e3f9efeb60ae9d77a62c2d437e22ec18 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 13:31:19 +0100 Subject: [PATCH 11/32] Enhance `DateMetadata` phpdoc --- .../Repository/Values/Content/Query/Criterion/DateMetadata.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php index bde44bb36c..bbfe5f0643 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php @@ -55,7 +55,7 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri ]; /** - * Creates a new DateMetadata criterion on $metadata. + * Creates a new DateMetadata criterion. * * @throws \InvalidArgumentException If target is unknown * From a5db8814e600a8909a2e91181b9de1c427185f5f Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 13:31:43 +0100 Subject: [PATCH 12/32] Enhance `Capable` phpdoc --- src/contracts/Search/Capable.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Search/Capable.php b/src/contracts/Search/Capable.php index 11cb1cfb1d..0451ffda08 100644 --- a/src/contracts/Search/Capable.php +++ b/src/contracts/Search/Capable.php @@ -20,7 +20,7 @@ interface Capable /** * Query for supported capability of currently configured search engine. * - * @param int $capabilityFlag One of \Ibexa\Contracts\Core\Repository\SearchService::CAPABILITY_* constants. + * @param int $capabilityFlag One of {@see \Ibexa\Contracts\Core\Repository\SearchService}::CAPABILITY_* constants. * * @return bool */ From f4d1346ab83031a179492f9ca0522943e4ffda96 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 14:50:08 +0100 Subject: [PATCH 13/32] Enhance `Criterion` phpdoc --- .../Repository/Values/Content/Query/Criterion.php | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion.php b/src/contracts/Repository/Values/Content/Query/Criterion.php index 64e5faf370..16e1267357 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion.php @@ -44,13 +44,15 @@ abstract class Criterion implements CriterionInterface public $valueData; /** - * Performs operator validation based on the Criterion specifications returned by {@see getSpecifications()}. + * Creates a Criterion. + * + * Performs operator validation based on the Criterion specifications returned by {@see Criterion::getSpecifications()}. * * @param string|null $target The target the Criterion applies to: metadata identifier, field identifier... * @param string|null $operator - * The operator the Criterion uses. If null is given, will default to Operator::IN if $value is an array, - * Operator::EQ if it is not. - * @param scalar[]|scalar $value + * The operator the Criterion uses. If null is given, will default to {@see Operator::IN} if $value is an array, + * {@see Operator::EQ} if it isn't. + * @param array|scalar $value * @param \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Value|null $valueData * * @todo Add a dedicated exception @@ -141,14 +143,14 @@ public function __construct(?string $target, ?string $operator, $value, ?Value $ * ] * ``` * - * @return \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications[] + * @return array */ abstract public function getSpecifications(): array; /** * Returns a callback that checks the values types depending on the operator specifications. * - * @param int $valueTypes The accepted values, as a bit field of Specifications::TYPE_* constants + * @param int $valueTypes The accepted values, as a bit field of {@see Specifications}::TYPE_* constants * * @return callable */ From 7d161aa3f962db986513c248b77f338ddbd40d2b Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 15:09:17 +0100 Subject: [PATCH 14/32] Enhance `UserMetadata` phpdoc (fix typo) --- .../Repository/Values/Content/Query/Criterion/UserMetadata.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php index 44d80610a0..1b4f924508 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php @@ -52,7 +52,7 @@ class UserMetadata extends Criterion implements TrashCriterion, FilteringCriteri * * @throws \InvalidArgumentException If target is unknown * - * @param string $target One of {@see UserMetadata::OWNER}, {@see UserMetadata::GROUP}, or {@see UserMetadata::MODIFIED}. + * @param string $target One of {@see UserMetadata::OWNER}, {@see UserMetadata::GROUP}, or {@see UserMetadata::MODIFIER}. * @param string|null $operator The operator the Criterion uses. If null is given, will default to {@see Operator::IN} if $value is an array, {@see Operator::EQ} if it isn't. * @param mixed $value The match value, either as an array of as a single value, depending on the operator. */ From 1bd2df8982714d594d4199cc07a3b5d5bcd1f4ea Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 12 Dec 2024 15:50:43 +0100 Subject: [PATCH 15/32] Enhance `UserMetadata` phpdoc --- .../Repository/Values/Content/Query/Criterion/UserMetadata.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php index 1b4f924508..85f53a6f24 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php @@ -19,7 +19,7 @@ * group, modifier). * * Supported Operators: - * - {@see Operator::EQ EQ}, {@see Operator::IN}: Matches the provided user ID(s) against the user IDs in the database. + * - {@see Operator::EQ EQ}, {@see Operator::IN IN}: Matches the provided user ID(s) against the user IDs in the database. * * The following example is a criterion for contents owned by a user with ID 10 or 14: * ``` From 89a788c3201bdfa98575daf7266308ce46e1a127 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Fri, 13 Dec 2024 12:35:11 +0100 Subject: [PATCH 16/32] Enhance `FieldType\Generic\Type` phpdoc --- src/contracts/FieldType/Generic/Type.php | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/contracts/FieldType/Generic/Type.php b/src/contracts/FieldType/Generic/Type.php index aa0028cd67..55c61b8ab1 100644 --- a/src/contracts/FieldType/Generic/Type.php +++ b/src/contracts/FieldType/Generic/Type.php @@ -263,17 +263,17 @@ final public function acceptValue($inputValue): Value * This is an operation method for {@see acceptValue()}. * * Example implementation: - * + * ``` * protected function createValueFromInput( $inputValue ) * { - * if ( is_array( $inputValue ) ) + * if (is_array($inputValue)) * { * $inputValue = \My\FieldType\CookieJar\Value( $inputValue ); * } * * return $inputValue; * } - * + * ``` * * @param mixed $inputValue * @@ -310,15 +310,15 @@ protected function getValueClass(): string * FieldType class and is named "Value". * * Example implementation: - * + * ``` * protected function checkValueType($value): void * { - * if ( !$inputValue instanceof \My\FieldType\CookieJar\Value ) ) + * if (!$inputValue instanceof \My\FieldType\CookieJar\Value)) * { - * throw new InvalidArgumentException( "Given value type is not supported." ); + * throw new InvalidArgumentException("Given value type isn't supported."); * } * } - * + * ``` * * @param mixed $value A value returned by {@see createValueFromInput()}. * From 291ae2b7a584d7f2637fd53bb49f650a1a583dd0 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 17/32] 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() { From db6f8a1e8607fe06174da5dea133c9f3a2a60e3f Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 16 Dec 2024 10:43:14 +0100 Subject: [PATCH 18/32] LocationService: Fix count() phpdoc --- src/contracts/Repository/LocationService.php | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/contracts/Repository/LocationService.php b/src/contracts/Repository/LocationService.php index 124f7201d3..945323ffdd 100644 --- a/src/contracts/Repository/LocationService.php +++ b/src/contracts/Repository/LocationService.php @@ -267,9 +267,11 @@ public function loadAllLocations(int $offset = 0, int $limit = 25): array; public function find(Filter $filter, ?array $languages = null): LocationList; /** - * Count total number of items returned by {@see find} method. + * Counts total number of items matching the filter. * - * @param string[] $languages a list of language codes to be added as additional constraints. + * Return the count of items that would be returned by {@see LocationService::find()} method. + * + * @param array $languages a list of language codes to be added as additional constraints. * If skipped, by default, unless SiteAccessAware layer has been disabled, languages set * for a SiteAccess in a current context will be used. */ From b48fbb45d6dc1e634ad6ece3034448d8833141f4 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 16 Dec 2024 10:46:55 +0100 Subject: [PATCH 19/32] Enhance `LocationService` phpdoc --- src/contracts/Repository/LocationService.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/contracts/Repository/LocationService.php b/src/contracts/Repository/LocationService.php index 945323ffdd..5181d398d7 100644 --- a/src/contracts/Repository/LocationService.php +++ b/src/contracts/Repository/LocationService.php @@ -57,10 +57,10 @@ public function loadLocation(int $locationId, ?array $prioritizedLanguages = nul * Returned list of Locations will be filtered by what is found and what current user has access to. * * @param array $locationIds - * @param string[]|null $prioritizedLanguages Filter on and use as prioritized language code on translated properties of returned objects. + * @param array|null $prioritizedLanguages Filter on and use as prioritized language code on translated properties of returned objects. * @param bool|null $useAlwaysAvailable Respect always available flag on content when filtering on $prioritizedLanguages. * - * @return \Ibexa\Contracts\Core\Repository\Values\Content\Location[]|iterable + * @return array|iterable */ public function loadLocationList(array $locationIds, ?array $prioritizedLanguages = null, ?bool $useAlwaysAvailable = null): iterable; @@ -253,14 +253,14 @@ public function getAllLocationsCount(): int; * @param int $limit * @param int $offset * - * @return \Ibexa\Contracts\Core\Repository\Values\Content\Location[] + * @return array */ public function loadAllLocations(int $offset = 0, int $limit = 25): array; /** * Fetch a LocationList from the Repository filtered by the given conditions. * - * @param string[] $languages a list of language codes to be added as additional constraints. + * @param array|null $languages a list of language codes to be added as additional constraints. * If skipped, by default, unless SiteAccessAware layer has been disabled, languages set * for a SiteAccess in a current context will be used. */ @@ -271,7 +271,7 @@ public function find(Filter $filter, ?array $languages = null): LocationList; * * Return the count of items that would be returned by {@see LocationService::find()} method. * - * @param array $languages a list of language codes to be added as additional constraints. + * @param array|null $languages a list of language codes to be added as additional constraints. * If skipped, by default, unless SiteAccessAware layer has been disabled, languages set * for a SiteAccess in a current context will be used. */ From 338bd28fcd45bd0a602a4ffe5bc96555f0366b49 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 16 Dec 2024 11:34:27 +0100 Subject: [PATCH 20/32] Enhance `Location` phpdoc --- .../Repository/Values/Content/Location.php | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Location.php b/src/contracts/Repository/Values/Content/Location.php index 972302e695..7102605e59 100644 --- a/src/contracts/Repository/Values/Content/Location.php +++ b/src/contracts/Repository/Values/Content/Location.php @@ -22,8 +22,8 @@ * @property-read bool $hidden @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::isHidden()} instead. * @property-read bool $invisible @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::isInvisible()} instead. * @property-read bool $explicitlyHidden Indicates that the Location entity has been explicitly marked as hidden. - * @property-read string $remoteId a global unique id of the content object - * @property-read int $parentLocationId the id of the parent location + * @property-read string $remoteId A global unique ID of the content object + * @property-read int $parentLocationId The ID of the parent location * @property-read string $pathString @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getPathString()} instead. * @property-read array $path @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getPath()} instead. * @property-read int $depth @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getDepth()} instead. @@ -89,15 +89,15 @@ abstract class Location extends ValueObject /** * Location ID. * - * @var int Location ID. + * @var int */ protected $id; /** - * the status of the location. + * The status of the location. * - * a location gets the status DRAFT on newly created content which is not published. When content is published the - * location gets the status STATUS_PUBLISHED + * A location gets the status {@see Location::STATUS_DRAFT} on newly created content which is not published. + * When content is published the location gets the status {@see Location::STATUS_PUBLISHED}. * * @var int */ @@ -152,16 +152,19 @@ abstract class Location extends ValueObject protected $parentLocationId; /** - * The materialized path of the location entry, eg: /1/2/. + * The materialized path of the location entry, eg: /1/2/4/23/. * * @var string */ protected $pathString; /** - * Same as {@see Location::$pathString} but as array, e.g.: [ '1', '2', '4', '23' ]. + * The list of ancestor Locations' IDs, ordered in increasing depths, + * starting with '1', and ending with the current Location's ID. * - * @var string[] + * Same as {@see Location::$pathString} but as array, e.g.: `['1', '2', '4', '23']`. + * + * @var array */ protected array $path; @@ -259,7 +262,7 @@ public function getSortClauses(): array /** * The path to the Location represented by the current instance, - * e.g. /1/2/4/23 where 23 is current id. + * e.g. /1/2/4/23/ where 23 is current ID. */ public function getPathString(): string { @@ -267,9 +270,12 @@ public function getPathString(): string } /** - * Same as {@see Location::getPathString()} but as array, e.g.: [ '1', '2', '4', '23' ]. + * The list of ancestor Locations' IDs, ordered in increasing depths, + * starting with 1, and ending with the current Location's ID. + * + * Same as {@see Location::getPathString()} but as array, e.g.: `['1', '2', '4', '23']`. * - * @return string[] + * @return array */ public function getPath(): array { From bf724376ca98675bb5f50b946d32c0ae0c3c0e30 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 16 Dec 2024 11:35:42 +0100 Subject: [PATCH 21/32] Enhance `Location` phpdoc: @deprecated can't be nested nor used inline. --- src/contracts/Repository/SearchService.php | 86 ++++++++++++------- .../Repository/Values/Content/Location.php | 14 +-- 2 files changed, 63 insertions(+), 37 deletions(-) diff --git a/src/contracts/Repository/SearchService.php b/src/contracts/Repository/SearchService.php index 585c5ae894..852ebd3149 100644 --- a/src/contracts/Repository/SearchService.php +++ b/src/contracts/Repository/SearchService.php @@ -20,7 +20,9 @@ interface SearchService { /** - * Capability flag for scoring feature for use with {@see ::supports()}. + * Capability flag for scoring feature. + * + * To use with {@see SearchService::supports()}. * * Scoring, a search feature telling you how well one search hit scores compared to other items in the search result. * When this is supported you can expect search engine to populate SearchHit->score and SearchResult->maxScore @@ -31,9 +33,11 @@ interface SearchService public const CAPABILITY_SCORING = 1; /** - * Capability flag for facets feature for use with {@see ::supports()}. + * Capability flag for facets feature. + * + * To use with {@see SearchService::supports()}. * - * Faceted search: https://en.wikipedia.org/wiki/Faceted_search + * Faceted search: {@link https://en.wikipedia.org/wiki/Faceted_search} * * Note: Even if search engine tells you this is supported, beware: * - It might not support all facets, by design it will only return facets for facet builders the search engine supports. @@ -45,19 +49,24 @@ interface SearchService public const CAPABILITY_FACETS = 2; /** - * Capability flag for custom fields feature for use with {@see ::supports()}. + * Capability flag for custom fields feature. + * + * To use with {@see SearchService::supports()}. * - * Custom fields is the capability for search engines to 1. allow you to extend the search index via plugins to - * generate custom fields, like a different representation (format, ...) of an existing field or similar. And 2. - * allow you on some search criteria to specify this custom field to rather query on that instead of the default - * field generated by the system. + * Custom fields is the capability for search engines to: + * - Allow you to extend the search index via plugins to + * generate custom fields, like a different representation (format, ...) of an existing field or similar. + * - Allow you on some search criteria to specify this custom field to rather query on that instead of the default + * field generated by the system. * * @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up) */ public const CAPABILITY_CUSTOM_FIELDS = 4; /** - * Capability flag for spellcheck feature for use with {@see ::supports()}. + * Capability flag for spellcheck feature. + * + * To use with {@see SearchService::supports()}. * * Spell check within search capabilities refers to ability to suggest better wordings in fulltext search string. * @@ -70,7 +79,9 @@ interface SearchService public const CAPABILITY_SPELLCHECK = 8; /** - * Capability flag for highlight feature for use with {@see ::supports()}. + * Capability flag for highlight feature. + * + * To use with {@see SearchService::supports()}. * * Highlight in search refers to extracting relevant text from the search index that matches the search result, * typically returning a chunk of text of a predefined size with matching text highlighted. @@ -88,7 +99,9 @@ interface SearchService public const CAPABILITY_HIGHLIGHT = 16; /** - * Capability flag for suggest feature for use with {@see ::supports()}. + * Capability flag for suggest feature. + * + * To use with {@see SearchService::supports()}. * * WARNING: This feature is considered experimental given it is not completely clear what it is supposed to do. Feature * might be deprecated in the future. @@ -98,7 +111,9 @@ interface SearchService public const CAPABILITY_SUGGEST = 32; /** - * Capability flag for advanced fulltext feature for use with {@see ::supports()}. + * Capability flag for advanced fulltext feature. + * + * To use with {@see SearchService::supports()}. * * Advance full text is a feature making to possible by current engine to parse advance full text expressions. * @@ -108,7 +123,9 @@ interface SearchService public const CAPABILITY_ADVANCED_FULLTEXT = 64; /** - * Capability flag for aggregation feature for use with {@see ::supports()}. + * Capability flag for aggregation feature. + * + * To use with {@see SearchService::supports()}. * * @since 3.2 eZ Platform 3.2 (ezplatform-kernel 1.2) */ @@ -120,11 +137,11 @@ interface SearchService * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if query is not valid * * @param \Ibexa\Contracts\Core\Repository\Values\Content\Query $query - * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. + * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. * Also used to define which field languages are loaded for the returned content. - * Currently supports: array("languages" => array(,..), "useAlwaysAvailable" => bool) - * useAlwaysAvailable defaults to true to avoid exceptions on missing translations - * @param bool $filterOnUserPermissions if true only the objects which the user is allowed to read are returned. + * Currently, supports `['languages' => [,…], 'useAlwaysAvailable' => ]`. + * `useAlwaysAvailable` defaults to `true` to avoid exceptions on missing translations. + * @param bool $filterOnUserPermissions if `true` (default), only the objects which the user is allowed to read are returned. * * @return \Ibexa\Contracts\Core\Repository\Values\Content\Search\SearchResult */ @@ -142,10 +159,10 @@ public function findContent(Query $query, array $languageFilter = [], bool $filt * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if query is not valid * * @param \Ibexa\Contracts\Core\Repository\Values\Content\Query $query - * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. - * Currently supports: array("languages" => array(,..), "useAlwaysAvailable" => bool) - * useAlwaysAvailable defaults to true to avoid exceptions on missing translations - * @param bool $filterOnUserPermissions if true (default) only the objects which is the user allowed to read are returned. + * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. + * Currently, supports `['languages' => [,…], 'useAlwaysAvailable' => ]`. + * `useAlwaysAvailable` defaults to `true` to avoid exceptions on missing translations. + * @param bool $filterOnUserPermissions if `true` (default), only the objects which the user is allowed to read are returned. * * @return \Ibexa\Contracts\Core\Repository\Values\Content\Search\SearchResult */ @@ -159,10 +176,10 @@ public function findContentInfo(Query $query, array $languageFilter = [], bool $ * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if there is more than than one result matching the criterions * * @param \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion $filter - * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. - * Currently supports: array("languages" => array(,..), "useAlwaysAvailable" => bool) - * useAlwaysAvailable defaults to true to avoid exceptions on missing translations - * @param bool $filterOnUserPermissions if true only the objects which is the user allowed to read are returned. + * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. + * Currently, supports `['languages' => [,…], 'useAlwaysAvailable' => ]`. + * `useAlwaysAvailable` defaults to `true` to avoid exceptions on missing translations. + * @param bool $filterOnUserPermissions if `true` (default), only the objects which the user is allowed to read are returned. * * @return \Ibexa\Contracts\Core\Repository\Values\Content\Content */ @@ -184,10 +201,11 @@ public function suggest(string $prefix, array $fieldPaths = [], int $limit = 10, * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if query is not valid * * @param \Ibexa\Contracts\Core\Repository\Values\Content\LocationQuery $query - * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. - * Currently supports: array("languages" => array(,..), "useAlwaysAvailable" => bool) - * useAlwaysAvailable defaults to true to avoid exceptions on missing translations - * @param bool $filterOnUserPermissions if true only the objects which is the user allowed to read are returned. + * @param array $languageFilter Configuration for specifying prioritized languages query will be performed on. + * Also used to define which field languages are loaded for the returned content. + * Currently, supports `['languages' => [,…], 'useAlwaysAvailable' => ]`. + * `useAlwaysAvailable` defaults to `true` to avoid exceptions on missing translations. + * @param bool $filterOnUserPermissions if `true` (default), only the objects which the user is allowed to read are returned. * * @return \Ibexa\Contracts\Core\Repository\Values\Content\Search\SearchResult */ @@ -200,7 +218,15 @@ public function findLocations(LocationQuery $query, array $languageFilter = [], * * @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) * - * @param int $capabilityFlag One of CAPABILITY_* constants. + * @param int $capabilityFlag One of the CAPABILITY_* constants (only a single one, not a bitwise combination): + * {@see SearchService::CAPABILITY_SCORING CAPABILITY_SCORING}, + * {@see SearchService::CAPABILITY_FACETS CAPABILITY_FACETS}, + * {@see SearchService::CAPABILITY_CUSTOM_FIELDS CAPABILITY_CUSTOM_FIELDS}, + * {@see SearchService::CAPABILITY_SPELLCHECK CAPABILITY_SPELLCHECK}, + * {@internal SearchService::CAPABILITY_HIGHLIGHT CAPABILITY_HIGHLIGHT,} + * {@see SearchService::CAPABILITY_SUGGEST CAPABILITY_SUGGEST}, + * {@see SearchService::CAPABILITY_ADVANCED_FULLTEXT CAPABILITY_ADVANCED_FULLTEXT}, or + * {@see SearchService::CAPABILITY_AGGREGATIONS CAPABILITY_AGGREGATIONS}. * * @return bool */ diff --git a/src/contracts/Repository/Values/Content/Location.php b/src/contracts/Repository/Values/Content/Location.php index 7102605e59..b782f7ed76 100644 --- a/src/contracts/Repository/Values/Content/Location.php +++ b/src/contracts/Repository/Values/Content/Location.php @@ -16,17 +16,17 @@ * This class represents a location in the repository. * * @property-read \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo calls getContentInfo() - * @property-read int $contentId @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getContentId()} instead. - * @property-read int $id @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getId()} instead. + * @property-read int $contentId Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getContentId()} instead. + * @property-read int $id Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getId()} instead. * @property-read int $priority Position of the Location among its siblings when sorted using priority - * @property-read bool $hidden @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::isHidden()} instead. - * @property-read bool $invisible @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::isInvisible()} instead. + * @property-read bool $hidden Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::isHidden()} instead. + * @property-read bool $invisible Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::isInvisible()} instead. * @property-read bool $explicitlyHidden Indicates that the Location entity has been explicitly marked as hidden. * @property-read string $remoteId A global unique ID of the content object * @property-read int $parentLocationId The ID of the parent location - * @property-read string $pathString @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getPathString()} instead. - * @property-read array $path @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getPath()} instead. - * @property-read int $depth @deprecated 4.6.7 accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getDepth()} instead. + * @property-read string $pathString Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getPathString()} instead. + * @property-read array $path Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getPath()} instead. + * @property-read int $depth Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getDepth()} instead. * @property-read int $sortField Specifies which property the child locations should be sorted on. Valid values are found at {@link Location::SORT_FIELD_*} * @property-read int $sortOrder Specifies whether the sort order should be ascending or descending. Valid values are {@link Location::SORT_ORDER_*} */ From 738f7edf7ff2edba2a84e2a259388a99e1506b6a Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 16 Dec 2024 12:59:20 +0100 Subject: [PATCH 22/32] Enhance `Location` phpdoc: Add an internal link --- src/contracts/Repository/Values/Content/Location.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Repository/Values/Content/Location.php b/src/contracts/Repository/Values/Content/Location.php index b782f7ed76..5eb5edd09a 100644 --- a/src/contracts/Repository/Values/Content/Location.php +++ b/src/contracts/Repository/Values/Content/Location.php @@ -15,7 +15,7 @@ /** * This class represents a location in the repository. * - * @property-read \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo calls getContentInfo() + * @property-read \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo Calls {@see Location::getContentInfo()} * @property-read int $contentId Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getContentId()} instead. * @property-read int $id Since 4.6.7, accessing magic getter is deprecated and will be removed in 5.0.0. Use {@see Location::getId()} instead. * @property-read int $priority Position of the Location among its siblings when sorted using priority From 1b81844c7d92c9c43bb0c6bdf3ce9c2a9c6f8ddb Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Mon, 16 Dec 2024 17:37:49 +0100 Subject: [PATCH 23/32] Enhance `ValueObject` phpdoc - Describes a bit more `getProperties` - Details `getProperties` param type and returned type - Hides link to internal function - Uses `@internal` as a short for "@ignore This method is for internal use" - Fixes internal links --- .../Repository/Values/ValueObject.php | 38 ++++++++++--------- 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/src/contracts/Repository/Values/ValueObject.php b/src/contracts/Repository/Values/ValueObject.php index 3aa5b81e76..87741261c0 100644 --- a/src/contracts/Repository/Values/ValueObject.php +++ b/src/contracts/Repository/Values/ValueObject.php @@ -25,7 +25,7 @@ abstract class ValueObject * Readonly properties values must be set using $properties as they are not writable anymore * after object has been created. * - * @param array $properties + * @param array $properties */ public function __construct(array $properties = []) { @@ -35,17 +35,18 @@ public function __construct(array $properties = []) } /** - * Function where list of properties are returned. + * Returns list of available properties' names. * - * Used by {@see attributes()}, override to add dynamic properties + * {@internal Used by {@see ValueObject::attributes()}} + * Override to add dynamic properties. * - * @uses ::__isset() + * @uses ValueObject::__isset() * * @todo Make object traversable and reuse this function there (hence why this is not exposed) * - * @param array $dynamicProperties Additional dynamic properties exposed on the object + * @param array $dynamicProperties Additional dynamic properties exposed on the object * - * @return array + * @return array */ protected function getProperties($dynamicProperties = []) { @@ -62,7 +63,7 @@ protected function getProperties($dynamicProperties = []) /** * Magic set function handling writes to non public properties. * - * @ignore This method is for internal use + * @internal * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyNotFoundException When property does not exist * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyReadOnlyException When property is readonly (protected) @@ -83,7 +84,7 @@ public function __set($property, $value) * * Returns value for all readonly (protected) properties. * - * @ignore This method is for internal use + * @internal * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyNotFoundException exception on all reads to undefined properties so typos are not silently accepted. * @@ -104,7 +105,7 @@ public function __get($property) * * Returns true for all (public/)protected/private properties. * - * @ignore This method is for internal use + * @internal * * @param string $property Name of the property * @@ -118,12 +119,12 @@ public function __isset($property) /** * Magic unset function handling unset() to non public properties. * - * @ignore This method is for internal use + * @internal * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyNotFoundException exception on all writes to undefined properties so typos are not silently accepted and * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyReadOnlyException exception on readonly (protected) properties. * - * @uses ::__set() + * @uses ValueObject::__set() * * @param string $property Name of the property * @@ -144,7 +145,7 @@ public function __unset($property) * var_export() generates code, that calls this method when it * is parsed with PHP. * - * @ignore This method is for internal use + * @internal * * @param mixed[] $array * @@ -158,11 +159,11 @@ public static function __set_state(array $array) /** * Internal function for Legacy template engine compatibility to get property value. * - * @ignore This method is for internal use + * @internal * * @deprecated Since 5.0, available purely for legacy eZTemplate compatibility * - * @uses ::__get() + * @uses ValueObject::__get() * * @param string $property * @@ -176,11 +177,12 @@ final public function attribute($property) /** * Internal function for Legacy template engine compatibility to get properties. * - * @ignore This method is for internal use + * @internal * * @deprecated Since 5.0, available purely for legacy eZTemplate compatibility * - * @uses ::__isset() + * @uses ValueObject::getProperties() + * @uses ValueObject::__isset() * * @return array */ @@ -192,11 +194,11 @@ final public function attributes() /** * Internal function for Legacy template engine compatibility to check existence of property. * - * @ignore This method is for internal use + * @internal * * @deprecated Since 5.0, available purely for legacy eZTemplate compatibility * - * @uses ::__isset() + * @uses ValueObject::__isset() * * @param string $property * From 17e460d31d611da8f541b91e54c7a60fdc91f256 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 17 Dec 2024 17:02:18 +0100 Subject: [PATCH 24/32] Enhance `FieldType\Generic\Type` phpdoc: Fix internal links --- src/contracts/FieldType/Generic/Type.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/contracts/FieldType/Generic/Type.php b/src/contracts/FieldType/Generic/Type.php index 55c61b8ab1..b09f77220e 100644 --- a/src/contracts/FieldType/Generic/Type.php +++ b/src/contracts/FieldType/Generic/Type.php @@ -260,15 +260,15 @@ final public function acceptValue($inputValue): Value * If given $inputValue could not be converted or is already an instance of dedicate value object, * the method should simply return it. * - * This is an operation method for {@see acceptValue()}. + * This is an operation method for {@see Type::acceptValue()}. * * Example implementation: * ``` - * protected function createValueFromInput( $inputValue ) + * protected function createValueFromInput($inputValue) * { * if (is_array($inputValue)) * { - * $inputValue = \My\FieldType\CookieJar\Value( $inputValue ); + * $inputValue = \My\FieldType\CookieJar\Value($inputValue); * } * * return $inputValue; @@ -304,7 +304,7 @@ protected function getValueClass(): string /** * Throws an exception if the given $value is not an instance of the supported value subtype. * - * This is an operation method for {@see acceptValue()}. + * This is an operation method for {@see Type::acceptValue()}. * * Default implementation expects the value class to reside in the same namespace as its * FieldType class and is named "Value". @@ -320,7 +320,7 @@ protected function getValueClass(): string * } * ``` * - * @param mixed $value A value returned by {@see createValueFromInput()}. + * @param mixed $value A value returned by {@see Type::createValueFromInput()}. * * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException If the parameter is not an instance of the supported value subtype. */ From 170b6470463bbb9fe90992b2204ab5bd84e8786d Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 17 Dec 2024 17:03:39 +0100 Subject: [PATCH 25/32] Enhance `FieldType\FieldType` phpdoc: Fix code blocks --- src/contracts/FieldType/FieldType.php | 56 +++++++++++++-------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/src/contracts/FieldType/FieldType.php b/src/contracts/FieldType/FieldType.php index 46694a2458..388fb0e657 100644 --- a/src/contracts/FieldType/FieldType.php +++ b/src/contracts/FieldType/FieldType.php @@ -100,20 +100,20 @@ abstract public function getSettingsSchema(); * It is considered best practice to return a hash map, which contains * rudimentary settings structures, like e.g. for the "ezstring" FieldType * - * - * array( - * 'stringLength' => array( - * 'minStringLength' => array( - * 'type' => 'int', - * 'default' => 0, - * ), - * 'maxStringLength' => array( - * 'type' => 'int' - * 'default' => null, - * ) - * ), - * ); - * + * ``` + * [ + * 'stringLength' => [ + * 'minStringLength' => [ + * 'type' => 'int', + * 'default' => 0, + * ], + * 'maxStringLength' => [ + * 'type' => 'int' + * 'default' => null, + * ], + * ], + * ]; + * ``` * * @return mixed */ @@ -360,22 +360,22 @@ abstract public function fromPersistenceValue(FieldValue $fieldValue); * * @param \Ibexa\Contracts\Core\FieldType\Value $value * - * @return array Hash with relation type as key and array of destination content ids as value. + * @return array Hash with relation type as key and array of destination content IDs as value. * * Example: - * - * array( - * \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK => array( - * "contentIds" => array( 12, 13, 14 ), - * "locationIds" => array( 24 ) - * ), - * \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED => array( - * "contentIds" => array( 12 ), - * "locationIds" => array( 24, 45 ) - * ), - * \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD => array( 12 ) - * ) - * + * ``` + * [ + * \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK => [ + * 'contentIds' => [12, 13, 14], + * 'locationIds' => [24] + * ], + * \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED => [ + * 'contentIds" => [12], + * 'locationIds' => [24, 45] + * ], + * \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD => [12] + * ] + * ``` */ abstract public function getRelations(Value $value); } From f5fad53a31eef1549487bbf96dc1223bd594dd22 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 19 Dec 2024 11:13:01 +0100 Subject: [PATCH 26/32] Values\Content\Location: Set protected/read-only property as internal --- src/contracts/Repository/Values/Content/Location.php | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/contracts/Repository/Values/Content/Location.php b/src/contracts/Repository/Values/Content/Location.php index 5eb5edd09a..1d3142bdb3 100644 --- a/src/contracts/Repository/Values/Content/Location.php +++ b/src/contracts/Repository/Values/Content/Location.php @@ -90,6 +90,7 @@ abstract class Location extends ValueObject * Location ID. * * @var int + * @internal Read-only property accessed through magic getter. */ protected $id; @@ -110,6 +111,7 @@ abstract class Location extends ValueObject * sort order. * * @var int + * @internal Read-only property accessed through magic getter. */ protected $priority; @@ -117,6 +119,7 @@ abstract class Location extends ValueObject * Indicates that the Location entity is hidden (explicitly or hidden by content). * * @var bool + * @internal Read-only property accessed through magic getter. */ protected $hidden; @@ -125,6 +128,7 @@ abstract class Location extends ValueObject * or implicitly hidden by its Content or an ancestor Location. * * @var bool + * @internal Read-only property accessed through magic getter. */ protected $invisible; @@ -132,6 +136,7 @@ abstract class Location extends ValueObject * Indicates that the Location entity has been explicitly marked as hidden. * * @var bool + * @internal Read-only property accessed through magic getter. */ protected $explicitlyHidden; @@ -141,6 +146,7 @@ abstract class Location extends ValueObject * A universally unique identifier. * * @var string + * @internal Read-only property accessed through magic getter. */ protected $remoteId; @@ -148,6 +154,7 @@ abstract class Location extends ValueObject * Parent ID. * * @var int Location ID. + * @internal Read-only property accessed through magic getter. */ protected $parentLocationId; @@ -155,6 +162,7 @@ abstract class Location extends ValueObject * The materialized path of the location entry, eg: /1/2/4/23/. * * @var string + * @internal Read-only property accessed through magic getter. */ protected $pathString; @@ -165,6 +173,7 @@ abstract class Location extends ValueObject * Same as {@see Location::$pathString} but as array, e.g.: `['1', '2', '4', '23']`. * * @var array + * @internal Read-only property accessed through magic getter. */ protected array $path; @@ -172,6 +181,7 @@ abstract class Location extends ValueObject * Depth location has in the location tree. * * @var int + * @internal Read-only property accessed through magic getter. */ protected $depth; @@ -181,6 +191,7 @@ abstract class Location extends ValueObject * Valid values are found at {@link Location::SORT_FIELD_*} * * @var int + * @internal Read-only property accessed through magic getter. */ protected $sortField; @@ -190,6 +201,7 @@ abstract class Location extends ValueObject * Valid values are {@link Location::SORT_ORDER_*} * * @var int + * @internal Read-only property accessed through magic getter. */ protected $sortOrder; From 89871587d3c5c4bc2fada942a0bc76f3e1b6aa66 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:14:46 +0100 Subject: [PATCH 27/32] Revert "Values\Content\Location: Set protected/read-only property as internal" This reverts commit 44aede1d26a38c8fee71ec204804f9b3aca8f3b4. --- src/contracts/Repository/Values/Content/Location.php | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/contracts/Repository/Values/Content/Location.php b/src/contracts/Repository/Values/Content/Location.php index 1d3142bdb3..5eb5edd09a 100644 --- a/src/contracts/Repository/Values/Content/Location.php +++ b/src/contracts/Repository/Values/Content/Location.php @@ -90,7 +90,6 @@ abstract class Location extends ValueObject * Location ID. * * @var int - * @internal Read-only property accessed through magic getter. */ protected $id; @@ -111,7 +110,6 @@ abstract class Location extends ValueObject * sort order. * * @var int - * @internal Read-only property accessed through magic getter. */ protected $priority; @@ -119,7 +117,6 @@ abstract class Location extends ValueObject * Indicates that the Location entity is hidden (explicitly or hidden by content). * * @var bool - * @internal Read-only property accessed through magic getter. */ protected $hidden; @@ -128,7 +125,6 @@ abstract class Location extends ValueObject * or implicitly hidden by its Content or an ancestor Location. * * @var bool - * @internal Read-only property accessed through magic getter. */ protected $invisible; @@ -136,7 +132,6 @@ abstract class Location extends ValueObject * Indicates that the Location entity has been explicitly marked as hidden. * * @var bool - * @internal Read-only property accessed through magic getter. */ protected $explicitlyHidden; @@ -146,7 +141,6 @@ abstract class Location extends ValueObject * A universally unique identifier. * * @var string - * @internal Read-only property accessed through magic getter. */ protected $remoteId; @@ -154,7 +148,6 @@ abstract class Location extends ValueObject * Parent ID. * * @var int Location ID. - * @internal Read-only property accessed through magic getter. */ protected $parentLocationId; @@ -162,7 +155,6 @@ abstract class Location extends ValueObject * The materialized path of the location entry, eg: /1/2/4/23/. * * @var string - * @internal Read-only property accessed through magic getter. */ protected $pathString; @@ -173,7 +165,6 @@ abstract class Location extends ValueObject * Same as {@see Location::$pathString} but as array, e.g.: `['1', '2', '4', '23']`. * * @var array - * @internal Read-only property accessed through magic getter. */ protected array $path; @@ -181,7 +172,6 @@ abstract class Location extends ValueObject * Depth location has in the location tree. * * @var int - * @internal Read-only property accessed through magic getter. */ protected $depth; @@ -191,7 +181,6 @@ abstract class Location extends ValueObject * Valid values are found at {@link Location::SORT_FIELD_*} * * @var int - * @internal Read-only property accessed through magic getter. */ protected $sortField; @@ -201,7 +190,6 @@ abstract class Location extends ValueObject * Valid values are {@link Location::SORT_ORDER_*} * * @var int - * @internal Read-only property accessed through magic getter. */ protected $sortOrder; From 16378098761a1330c5c2d3212c0da2c71dfe864c Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Fri, 20 Dec 2024 16:21:07 +0100 Subject: [PATCH 28/32] Revert src/lib/Limitation/ Revert 1799d56726f42e82f65a1054a2a823746dd2a4de changes on src/lib/Limitation/ as this is out of contracts scope. --- src/lib/Limitation/LocationLimitationType.php | 5 +++-- src/lib/Limitation/SubtreeLimitationType.php | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/lib/Limitation/LocationLimitationType.php b/src/lib/Limitation/LocationLimitationType.php index e0ce4ec2b6..3c7cd6571f 100644 --- a/src/lib/Limitation/LocationLimitationType.php +++ b/src/lib/Limitation/LocationLimitationType.php @@ -224,9 +224,10 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren } /** - * Returns an integer code meaning that the value must be an array listing location IDs. + * Returns info on valid $limitationValues. * - * @return int {@see LocationLimitationType::VALUE_SCHEMA_LOCATION_ID} + * @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. */ public function valueSchema() { diff --git a/src/lib/Limitation/SubtreeLimitationType.php b/src/lib/Limitation/SubtreeLimitationType.php index 3ceb4cee0d..c642ec64e8 100644 --- a/src/lib/Limitation/SubtreeLimitationType.php +++ b/src/lib/Limitation/SubtreeLimitationType.php @@ -258,9 +258,10 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren } /** - * Returns an integer code meaning that the value must be an array listing location paths. + * Returns info on valid $limitationValues. * - * @return int {@see SubtreeLimitationType::VALUE_SCHEMA_LOCATION_PATH} + * @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. */ public function valueSchema() { From 8f9c4e9d78b94799600d459584b95e9f3553c8bf Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Fri, 20 Dec 2024 17:15:29 +0100 Subject: [PATCH 29/32] `Limitation\Type`: type array keys --- src/contracts/Limitation/Type.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/contracts/Limitation/Type.php b/src/contracts/Limitation/Type.php index cb5410d705..584cba60e1 100644 --- a/src/contracts/Limitation/Type.php +++ b/src/contracts/Limitation/Type.php @@ -92,17 +92,17 @@ public function acceptValue(APILimitationValue $limitationValue); * * @param \Ibexa\Contracts\Core\Repository\Values\User\Limitation $limitationValue * - * @return \Ibexa\Contracts\Core\FieldType\ValidationError[] + * @return array */ public function validate(APILimitationValue $limitationValue); /** * Create the Limitation Value. * - * The is the method to create values as Limitation type needs value knowledge anyway in acceptValue, + * This is the method to create values as Limitation type needs value knowledge anyway in acceptValue, * the reverse relation is provided by means of identifier lookup (Value has identifier, and so does RoleService). * - * @param mixed[] $limitationValues + * @param array $limitationValues * * @return \Ibexa\Contracts\Core\Repository\Values\User\Limitation */ @@ -120,7 +120,7 @@ public function buildValue(array $limitationValues); * @param \Ibexa\Contracts\Core\Repository\Values\User\Limitation $value * @param \Ibexa\Contracts\Core\Repository\Values\User\UserReference $currentUser * @param \Ibexa\Contracts\Core\Repository\Values\ValueObject $object - * @param \Ibexa\Contracts\Core\Repository\Values\ValueObject[]|null $targets An array of location, parent or "assignment" + * @param array|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, {@see Type::ACCESS_GRANTED}, {@see Type::ACCESS_ABSTAIN}, or {@see Type::ACCESS_DENIED}. From 90254e45fa823e897c13bed1113e38781643c466 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Sun, 22 Dec 2024 13:16:03 +0100 Subject: [PATCH 30/32] ValueObject: Format desc --- src/contracts/Repository/Values/ValueObject.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/contracts/Repository/Values/ValueObject.php b/src/contracts/Repository/Values/ValueObject.php index 87741261c0..0bee880688 100644 --- a/src/contracts/Repository/Values/ValueObject.php +++ b/src/contracts/Repository/Values/ValueObject.php @@ -12,9 +12,9 @@ /** * The base class for all value objects and structs. * - * Supports readonly properties by marking them as protected. + * Supports read-only properties by marking them as protected. * In this case they will only be writable using constructor, and need to be documented - * using property-read <$var> annotation in class doc in addition to inline property doc. + * using `@property-read <$var>` annotation in class doc in addition to inline property doc. * Writable properties must be public and must be documented inline. */ abstract class ValueObject From 33b627bb2f16559ddcd43784a5ad0b799c9e6d64 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Sun, 22 Dec 2024 19:54:27 +0100 Subject: [PATCH 31/32] ValueObject: Format desc --- src/contracts/Repository/Values/ValueObject.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Repository/Values/ValueObject.php b/src/contracts/Repository/Values/ValueObject.php index 0bee880688..99a1b1dbc5 100644 --- a/src/contracts/Repository/Values/ValueObject.php +++ b/src/contracts/Repository/Values/ValueObject.php @@ -22,7 +22,7 @@ abstract class ValueObject /** * Construct object optionally with a set of properties. * - * Readonly properties values must be set using $properties as they are not writable anymore + * Readonly properties values must be set using `$properties` as they aren't writable anymore * after object has been created. * * @param array $properties From 6482ce2a8ffa79f7e40c7b433e6865c696c407d1 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Sun, 22 Dec 2024 19:54:41 +0100 Subject: [PATCH 32/32] ValueObject: Format desc --- src/contracts/Repository/Values/ValueObject.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/contracts/Repository/Values/ValueObject.php b/src/contracts/Repository/Values/ValueObject.php index 99a1b1dbc5..e55c5c102d 100644 --- a/src/contracts/Repository/Values/ValueObject.php +++ b/src/contracts/Repository/Values/ValueObject.php @@ -61,7 +61,7 @@ protected function getProperties($dynamicProperties = []) } /** - * Magic set function handling writes to non public properties. + * Magic set function handling writes to non-public properties. * * @internal *