IBX-10885: Document Content Type search API (#2946)

* IBX-10885: Document Content Type search API

---------

Co-authored-by: dabrt <dabrt@users.noreply.github.com>
Co-authored-by: Bartek Wajda <bartlomiej.wajda@ibexa.co>

Author: dabrt

code_samples/api/public_php_api/src/Command/FindContentTypeCommand.php

@@ -0,0 +1,55 @@
+<?php declare(strict_types=1);
+
+namespace App\Command;
+
+use Ibexa\Contracts\Core\Repository\ContentTypeService;
+use Ibexa\Contracts\Core\Repository\Values\ContentType\Query\ContentTypeQuery;
+use Ibexa\Contracts\Core\Repository\Values\ContentType\Query\Criterion;
+use Ibexa\Contracts\Core\Repository\Values\ContentType\Query\SortClause;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand(
+    name: 'doc:find_content_types',
+    description: 'Lists content types that match specific criteria.'
+)]
+class FindContentTypeCommand extends Command
+{
+    public function __construct(private readonly ContentTypeService $contentTypeService)
+    {
+        parent::__construct();
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        // Find content types from the "Content" group that contains a specific field definition (in this case, a "Body" field).
+        $query = new ContentTypeQuery(
+            new Criterion\LogicalAnd([
+                new Criterion\ContentTypeGroupId([1]),
+                new Criterion\ContainsFieldDefinitionId([121]),
+            ]),
+            [
+                new SortClause\Id(),
+                new SortClause\Identifier(),
+                new SortClause\Name(),
+            ]
+        );
+
+        $searchResult = $this->contentTypeService->findContentTypes($query);
+
+        $output->writeln('Found ' . $searchResult->getTotalCount() . ' content type(s):');
+
+        foreach ($searchResult->getContentTypes() as $contentType) {
+            $output->writeln(sprintf(
+                '- [%d] %s (identifier: %s)',
+                $contentType->id,
+                $contentType->getName(),
+                $contentType->identifier
+            ));
+        }
+
+        return Command::SUCCESS;
+    }
+}

docs/content_management/content_api/managing_content.md

@@ -165,6 +165,35 @@ To change the identifier of the copy, use a [`ContentTypeUpdateStruct`](/api/php
 [[= include_file('code_samples/api/public_php_api/src/Command/CreateContentTypeCommand.php', 87, 93) =]]
 ```
 
+### Finding and filtering content types
+
+You can find content types that match specific criteria by using the [`ContentTypeService::findContentTypes()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-ContentTypeService.html#method_findContentTypes) method.
+This method accepts a `ContentTypeQuery` object that supports filtering and sorting by IDs, identifiers, group membership, and other criteria.
+
+!!! note "Criterions and sort clauses"
+
+    For a full list of available criterions and sort clauses that you can use when finding and filtering content types, see [Content Type Search Criteria](content_type_criteria.md) and [Content Type Search Sort Clauses](content_type_sort_clauses.md) references.
+
+
+The following example shows how you can use the criteria to find content types:
+
+```php hl_lines="28-38"
+[[= include_file('code_samples/api/public_php_api/src/Command/FindContentTypeCommand.php') =]]
+```
+
+#### Query parameters
+
+When constructing a `ContentTypeQuery`, you can pass the following parameters:
+
+- `?CriterionInterface $criterion = null` — a filter to apply (use one or a combination of the criterions above)
+
+- `array $sortClauses = []` — list of sort clauses to order the results
+
+- `int $offset = 0` — starting offset (for pagination)
+
+- `int $limit = 25` — maximum number of results to return
+
+
 ## Calendar events
 
 You can handle the calendar using `CalendarServiceInterface` (`Ibexa\Contracts\Calendar\CalendarServiceInterface`).

docs/search/content_type_search_reference/content_type_criteria.md

@@ -0,0 +1,26 @@
+---
+description: Content Type Search Criteria help define and fine-tune search queries for content types.
+page_type: reference
+month_change: true
+---
+
+# Content Type Search Criteria reference
+
+Content Type Search Criteria are only supported by [Content Type Search (`ContentTypeService::findContentTypes`)](managing_content.md#finding-and-filtering-content-types).
+
+| Criterion | Description |
+|-------|-------------|
+| [ContainsFieldDefinitionId](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-ContainsFieldDefinitionId.html) | Matches content types that contain a field definition with the specified ID. |
+| [ContentTypeGroupId](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-ContentTypeGroupId.html) | Matches content types by their assigned group ID. |
+| [ContentTypeId](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-ContentTypeId.html) | Matches content types by their ID. |
+| [ContentTypeIdentifier](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-ContentTypeIdentifier.html) | Matches content types by their identifier. |
+| [IsSystem](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-IsSystem.html) | Matches content types based on whether the group they belong to is system or not. |
+| [LogicalAnd](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-LogicalAnd.html) | Implements a logical AND Criterion. It matches if ALL of the provided Criteria match. |
+| [LogicalOr](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-LogicalOr.html) | Implements a logical OR Criterion. It matches if at least one of the provided Criteria matches. |
+| [LogicalNot](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-Criterion-LogicalNot.html) | Implements a logical NOT Criterion. It matches if the provided Criterion doesn't match. |
+
+The following example shows how to use them to search for content types:
+
+```php hl_lines="29-31"
+[[= include_file('code_samples/api/public_php_api/src/Command/FindContentTypeCommand.php') =]]
+```

docs/search/content_type_search_reference/content_type_sort_clauses.md

@@ -0,0 +1,26 @@
+---
+description: Content Type Search Sort Clauses
+month_change: true
+---
+
+# Content Type Search Sort Clauses
+
+Content Type Search Sort Clauses are the sorting options for content types.
+They're only supported by [Content Type Search (`ContentTypeService::findContentTypes`)](managing_content.md#finding-and-filtering-content-types).
+
+Sort Clauses are found in the [`Ibexa\Contracts\Core\Repository\Values\ContentType\Query\SortClause`](/api/php_api/php_api_reference/namespaces/ibexa-contracts-core-repository-values-contenttype-query-sortclause.html) namespace:
+
+| Name | Description |
+| --- | --- |
+| [Id](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-SortClause-Id.html)| Sort by content type's id |
+| [Identifier](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-SortClause-Identifier.html)| Sort by content type's identifier |
+| [Name](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-ContentType-Query-SortClause-Name.html)| Sort by content type's name |
+
+
+The following example shows how to use them to sort the searched content types:
+
+```php hl_lines="34-36"
+[[= include_file('code_samples/api/public_php_api/src/Command/FindContentTypeCommand.php') =]]
+```
+
+You can change the default sorting order by using the `SORT_ASC` and `SORT_DESC` constants from [`AbstractSortClause`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-CoreSearch-Values-Query-AbstractSortClause.html#constants).

mkdocs.yml

@@ -567,6 +567,7 @@ nav:
             - LogicalAnd Criterion: search/criteria_reference/logicaland_criterion.md
             - LogicalNot Criterion: search/criteria_reference/logicalnot_criterion.md
             - LogicalOr Criterion: search/criteria_reference/logicalor_criterion.md
+        - Content Type Search Criteria: search/content_type_search_reference/content_type_criteria.md
         - Product Search Criteria:
             - Product Search Criteria: search/criteria_reference/product_search_criteria.md
             - AttributeName: search/criteria_reference/attributename_criterion.md
@@ -706,6 +707,7 @@ nav:
                 - SectionName: search/sort_clause_reference/sectionname_sort_clause.md
                 - UserLogin: search/sort_clause_reference/userlogin_sort_clause.md
                 - Visibility: search/sort_clause_reference/visibility_sort_clause.md
+            - Content Type Sort Clauses: search/content_type_search_reference/content_type_sort_clauses.md
             - Product Sort Clauses:
                 - Product Sort Clauses: search/sort_clause_reference/product_sort_clauses.md
                 - BasePrice: search/sort_clause_reference/baseprice_sort_clause.md