From 4b52f8ba1b6a48df6d9473981a28a83eef8a99b1 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/17] 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 072cfa643a97310013c77e82c3d89dd9ef7c63ac 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/17] 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 0a7e0de0d2a845b6122646d0dd93915d8eec89be 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/17] 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 53a474e8bd5057053821f1cc1f843c9f62645846 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/17] 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 8a4c287267db7f85871e2073ed9bfac2a81d450b 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/17] 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 45960d5cb6220e93793a88f87192c1f4e9c331aa 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/17] 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 decfe1292284edd5ba134c03764573526f09d737 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/17] 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 053071cbec6d264dc1df41ea938767ca97fcdd1c 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/17] 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 8163ec9d566258745732170fb729b67a48d2f16d 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/17] 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 9a28e14326d0316b7c09f135a59bc4ef57a83d45 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/17] 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 ad9ea002029df5e046d2a420e6eb542d92332b9e 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/17] 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 8f1ecce9aea5582f341b59b23bbb1b20431454f2 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/17] 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 e7e9ec007c12062d58446a885478b651710ed1c6 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/17] 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 97ac58f4b303630a06c1561b9640aa8033e6b534 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/17] 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 9f1aabdf80fc77d4e52ad9a23b059d78a7382964 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/17] 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 7b33e269c818514eb19d4f63dcb2e63b7ed0a4d9 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/17] 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 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 17/17] 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()
{