Skip to content

Commit

Permalink
Enhance Location phpdoc: @deprecated can't be nested nor used inline.
Browse files Browse the repository at this point in the history
  • Loading branch information
@adriendupuis
adriendupuis committed Dec 16, 2024
1 parent 879e59a commit c59a8a9
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 37 deletions.
86 changes: 56 additions & 30 deletions src/contracts/Repository/SearchService.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.
*
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
*
Expand All @@ -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)
*/
Expand All @@ -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<string, mixed> $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: <code>array("languages" => array(<language1>,..), "useAlwaysAvailable" => bool)</code>
* 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' => [<language_code_string>,…], 'useAlwaysAvailable' => <bool>]`.
* `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
*/
Expand All @@ -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: <code>array("languages" => array(<language1>,..), "useAlwaysAvailable" => bool)</code>
* 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<string, mixed> $languageFilter Configuration for specifying prioritized languages query will be performed on.
* Currently, supports `['languages' => [<language_code_string>,…], 'useAlwaysAvailable' => <bool>]`.
* `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
*/
Expand All @@ -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: <code>array("languages" => array(<language1>,..), "useAlwaysAvailable" => bool)</code>
* 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<string, mixed> $languageFilter Configuration for specifying prioritized languages query will be performed on.
* Currently, supports `['languages' => [<language_code_string>,…], 'useAlwaysAvailable' => <bool>]`.
* `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
*/
Expand All @@ -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: <code>array("languages" => array(<language1>,..), "useAlwaysAvailable" => bool)</code>
* 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<string, mixed> $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' => [<language_code_string>,…], 'useAlwaysAvailable' => <bool>]`.
* `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
*/
Expand All @@ -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
*/
Expand Down
14 changes: 7 additions & 7 deletions src/contracts/Repository/Values/Content/Location.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_*}
*/
Expand Down

0 comments on commit c59a8a9

Please sign in to comment.