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); } diff --git a/src/contracts/FieldType/Generic/Type.php b/src/contracts/FieldType/Generic/Type.php index aa0028cd67..b09f77220e 100644 --- a/src/contracts/FieldType/Generic/Type.php +++ b/src/contracts/FieldType/Generic/Type.php @@ -260,20 +260,20 @@ 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 ) ) + * if (is_array($inputValue)) * { - * $inputValue = \My\FieldType\CookieJar\Value( $inputValue ); + * $inputValue = \My\FieldType\CookieJar\Value($inputValue); * } * * return $inputValue; * } - * + * ``` * * @param mixed $inputValue * @@ -304,23 +304,23 @@ 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". * * 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()}. + * @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. */ 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 { 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 */ diff --git a/src/contracts/Limitation/Type.php b/src/contracts/Limitation/Type.php index b93aa4a5c4..584cba60e1 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; /** @@ -61,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 */ @@ -89,10 +120,10 @@ 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 + * @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/contracts/Repository/LocationService.php b/src/contracts/Repository/LocationService.php index 124f7201d3..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,23 +253,25 @@ 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. */ 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|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. */ 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 972302e695..5eb5edd09a 100644 --- a/src/contracts/Repository/Values/Content/Location.php +++ b/src/contracts/Repository/Values/Content/Location.php @@ -15,18 +15,18 @@ /** * 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 \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 - * @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 $remoteId A global unique ID of the content object + * @property-read int $parentLocationId The ID of the parent location + * @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_*} */ @@ -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 { diff --git a/src/contracts/Repository/Values/Content/Query/Criterion.php b/src/contracts/Repository/Values/Content/Query/Criterion.php index 7e80664698..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 @@ -118,12 +120,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. + * - {@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 * return [ * // The EQ operator expects a single value, either as an integer or a string @@ -139,16 +141,16 @@ 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[] + * @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 */ diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php index 78d5397468..bbfe5f0643 100644 --- a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php +++ b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php @@ -18,19 +18,19 @@ * 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, - * strtotime( 'yesterday' ) + * Criterion\Operator::GTE, + * strtotime('yesterday') * ); - * + * ``` */ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriterion { @@ -41,7 +41,9 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri public const PUBLISHED = 'published'; /** - * (applies to TrashService::findTrashItems only). + * 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'; @@ -53,12 +55,12 @@ 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 * - * @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) 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 { diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php index 13f4775307..85f53a6f24 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 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::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. */ public function __construct(string $target, ?string $operator, $value) { diff --git a/src/contracts/Repository/Values/ValueObject.php b/src/contracts/Repository/Values/ValueObject.php index 3aa5b81e76..e55c5c102d 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 @@ -22,10 +22,10 @@ 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 + * @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 = []) { @@ -60,9 +61,9 @@ protected function getProperties($dynamicProperties = []) } /** - * Magic set function handling writes to non public properties. + * 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 * diff --git a/src/contracts/Search/Capable.php b/src/contracts/Search/Capable.php index a6504d9595..0451ffda08 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. @@ -18,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 */