diff --git a/docs/administration/admin_panel/segments_admin_panel.md b/docs/administration/admin_panel/segments_admin_panel.md index 755a6dc664..cb8426d56e 100644 --- a/docs/administration/admin_panel/segments_admin_panel.md +++ b/docs/administration/admin_panel/segments_admin_panel.md @@ -15,4 +15,4 @@ Each segment group can contain segments that you can target content for. ![Segment](admin_panel_segment.png) -You can assign users to segments [through the API](segment_api.md#assigning-users). +You can assign users to segments over the REST API. diff --git a/docs/administration/configuration/configuration.md b/docs/administration/configuration/configuration.md index 560f2a9201..ca2f22cd6f 100644 --- a/docs/administration/configuration/configuration.md +++ b/docs/administration/configuration/configuration.md @@ -59,7 +59,7 @@ All kinds of values are accepted, including arrays and deep hashes. For configuration that is meant to be exposed to an end-user (or end-developer), it's usually a good idea to also [implement semantic configuration]([[= symfony_doc =]]/components/config/definition.html). -You can also [implement SiteAccess-aware semantic configuration](siteaccess_aware_configuration.md). +Settings can also be [SiteAccess-aware](siteaccess_aware_configuration.md), taking a different value per SiteAccess, SiteAccess group, or globally. For example: diff --git a/docs/ai/ai_actions/ai_actions_guide.md b/docs/ai/ai_actions/ai_actions_guide.md index 626fb9460c..cc7b32393a 100644 --- a/docs/ai/ai_actions/ai_actions_guide.md +++ b/docs/ai/ai_actions/ai_actions_guide.md @@ -129,14 +129,6 @@ An intuitive AI Actions interface within the **Admin** panel displays a list of Here, you can search for specific actions and filter them by type or status. By accessing the detailed view of individual AI actions, you can quickly review all their parameters. -### Extensibility - -Built-in AI action types offer a good starting point, but the real power of AI Actions lies in extensibility. -Extending AI Actions opens up new possibilities for content management and editing. -Developers can define new models and AI action types that use the existing AI service or even integrate additional services. -The latter involves developing a new service connector, writing a handler that communicates with the new service, defining a new AI action type, and creating a form for configuring options, which extends the default action configuration form shown in the **Admin** panel. -For example, if this is your organization's requirement, a developer could write a handler that uses an AI service available internally, without exposing your data to a third-party service. - ## Use cases Out of the box, after you configure access to the OpenAI service, AI Actions come with two action types that can help your organization with the following tasks. diff --git a/docs/ai/ai_actions/configure_ai_actions.md b/docs/ai/ai_actions/configure_ai_actions.md index 2dc910441c..cfcce3d41d 100644 --- a/docs/ai/ai_actions/configure_ai_actions.md +++ b/docs/ai/ai_actions/configure_ai_actions.md @@ -16,7 +16,7 @@ To use this feature you must first configure the built-in service connectors. Once the framework is configured, before you can start using AI Actions, you can configure access to [[= product_name_base =]]-made service connectors by following the instructions below. -Only then you can restart you application and start [working with the AI Actions feature]([[= user_doc =]]/ai_actions/work_with_ai_actions/). +Once the connectors are configured, you can start [working with the AI Actions feature]([[= user_doc =]]/ai_actions/work_with_ai_actions/). !!! note "Taxonomy suggestions" diff --git a/docs/ai/mcp/mcp_guide.md b/docs/ai/mcp/mcp_guide.md index 169356a354..597e2c468c 100644 --- a/docs/ai/mcp/mcp_guide.md +++ b/docs/ai/mcp/mcp_guide.md @@ -31,7 +31,6 @@ With the MCP Servers feature, you can: - create MCP servers [by using YAML configuration](mcp_config.md#mcp-server-configuration) - assign different tools, prompts, and resources to different MCP servers, varying them for each site and purpose - use [built-in tools](mcp_config.md#built-in-tools) included in the package -- [create custom server capabilities](mcp_usage.md#create-capability-class) with PHP API MCP servers are defined specifically for each repository and assigned to individual [SiteAccesses](siteaccess.md) scopes. This way you can build flexible configurations that match different contexts. diff --git a/docs/ai/mcp/mcp_usage.md b/docs/ai/mcp/mcp_usage.md index 4741b58836..090e299ebe 100644 --- a/docs/ai/mcp/mcp_usage.md +++ b/docs/ai/mcp/mcp_usage.md @@ -115,50 +115,6 @@ An `ibexa.mcp.example` route is now available: php bin/console debug:router ibexa.mcp.example ``` -### Create capability class - -Create an `ExampleCapabilities` class that implements `McpCapabilityInterface`. - -The class contains: - -- a method marked with an `McpTool` attribute that associates it with the `example` server as the `greet` tool -- a method marked with an `McpPrompt` attribute that provides a prompt template to users - -``` php -[[= include_code('code_samples/mcp/src/Mcp/ExampleCapabilities.php') =]] -``` - -In this example, the `servers` attribute parameter associates only this tool with the `example` server. -Alternatively, you can assign all tools from the class to a server by using the `tools` parameter in the server configuration. -For more information, see [tools configuration](mcp_config.md#tool-configuration). - -For the prompt, the `servers` parameter is required. -Therefore, the example prompt must use it to be associated with the `example` server. - -During development and testing, you may need to clear the cache to ensure that new or modified capabilities are properly re-discovered. -In this example, use the following command: - -```bash -php bin/console cache:pool:clear cache.tagaware.filesystem -``` - -!!! tip "Cache clearing" - - During development, clear caches aggressively. - The following commands clear all cache types, regardless of where they are stored: - ```bash - php bin/console cache:clear - php bin/console cache:pool:clear --all - ``` - -### Create MCP server list command - -To check the MCP server configuration, create a small command that uses the MCP server configuration registry injected through `McpServerConfigurationRegistryInterface` and autowiring: - -``` php -[[= include_code('code_samples/mcp/src/Command/McpServerListCommand.php') =]] -``` - ### Perform `curl` test To test the `example` MCP server, a sequence of `curl` commands is used to simulate the communication between an AI client and the MCP server. diff --git a/docs/api/rest_api/rest_api_usage/rest_requests.md b/docs/api/rest_api/rest_api_usage/rest_requests.md index 1e55d3cac5..4e65cdcfb2 100644 --- a/docs/api/rest_api/rest_api_usage/rest_requests.md +++ b/docs/api/rest_api/rest_api_usage/rest_requests.md @@ -157,26 +157,11 @@ When searching for content items (or locations), the query grammar is also parti ### Creating content with binary attachments -The example below is a command-line script to upload images. It's based on the [Symfony HttpClient]([[= symfony_doc =]]/http_client.html). - -This script: - -- receives an image path and optionally a name as command-line arguments, -- uses the [HTTP basic authentication](rest_api_authentication.md#http-basic-authentication), if it's enabled, -- creates a draft in the /Media/Images folder by posting (`POST`) data to [`/content/objects`](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_post), -- and, publishes (`PUBLISH`) the draft through [`/content/objects/{contentId}/versions/{versionNo}`](../rest_api_reference/rest_api_reference.html#managing-content-publish-a-content-version). - -=== "XML" - - ``` php - [[= include_code('code_samples/api/rest_api/create_image.xml.php', 1, None, 1) =]] - ``` - -=== "JSON" - - ``` php - [[= include_code('code_samples/api/rest_api/create_image.json.php', indent_level=1) =]] - ``` +To create content with a binary attachment, such as an image, post the content +data to [`/content/objects`](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_post) +to create a draft, then publish it through +[`/content/objects/{contentId}/versions/{versionNo}`](../rest_api_reference/rest_api_reference.html#managing-content-publish-a-content-version). +Authenticate the requests as described in [HTTP basic authentication](rest_api_authentication.md#http-basic-authentication). ### Search (`/views`) diff --git a/docs/api/rest_api/rest_api_usage/testing_rest_api.md b/docs/api/rest_api/rest_api_usage/testing_rest_api.md index c44fe90fa9..a7c35fa6d8 100644 --- a/docs/api/rest_api/rest_api_usage/testing_rest_api.md +++ b/docs/api/rest_api/rest_api_usage/testing_rest_api.md @@ -19,22 +19,6 @@ For examples of using `curl`, refer to: - [Location header](rest_responses.md#location-header) - [ContentInfo body](rest_responses.md#response-body) -## PHP - -You can use [Symfony HttpClient]([[= symfony_doc =]]/http_client.html) to test REST API. -Open a PHP shell in a terminal with `php -a` and copy-paste this code into it: - -``` php -[[= include_code('code_samples/api/rest_api/load_content.php', 3, 9, remove_indent=True) =]] -``` - -`$resource` URI should be edited to address the right domain. - -On a freshly installed [[= product_name =]], `52` is the Content ID of the home page. -If necessary, substitute `52` with the content ID of an item from your database. - -For a content creation example that uses PHP, see [Creating content with binary attachments](rest_requests.md#creating-content-with-binary-attachments) - ## JS The REST API can help you implement JavaScript / AJAX interaction. diff --git a/docs/customer_management/cp_applications.md b/docs/customer_management/cp_applications.md index 0e53e7c483..149a238b59 100644 --- a/docs/customer_management/cp_applications.md +++ b/docs/customer_management/cp_applications.md @@ -61,28 +61,6 @@ First, under the `ibexa.system..corporate_accounts.application.states` ad [[= include_file('code_samples/customer_portal/config/packages/customer_portal.yaml') =]] ``` -### Create new Form Type - -Next, create a new form type in `src/Form/VerifyType.php`. -It's displayed in the application review stage. - -``` php hl_lines="17-18 25" -[[= include_code('code_samples/customer_portal/src/Form/VerifyType.php') =]] -``` - -Line 29 defines where the form should be displayed, line 21 adds **Note** field, and line 22 adds the **Verify** button. - -### Create event subscriber to pass the form - -Add an event subscriber that passes a new form type to the frontend. -Create `src/Corporate/EventSubscriber/ApplicationDetailsViewSubscriber.php` following the example below: - -``` php hl_lines="35" -[[= include_code('code_samples/customer_portal/src/Corporate/EventSubscriber/ApplicationDetailsViewSubscriber.php') =]] -``` - -In line 39, you can see the `verify_form` parameter that passes the `verify` form to the application review view. - ### Add form template To be able to see the changes you need to add a new template `templates/themes/admin/corporate_account/application/details.html.twig`. @@ -96,19 +74,3 @@ To check the progress, go to **Members** -> **Applications**. Select one application from the list and inspect application review view for a new button. ![Verify button](img/cp_new_status.png) - -### Create event subscriber to verify state - -Now, you need to pass the information that the button has been selected to the list of applications to change the application status. -Create another event subscriber that passes the information from the created form to the application list `src/Corporate/EventSubscriber/VerifyStateEventSubscriber.php`. - -``` php hl_lines="42 68" -[[= include_code('code_samples/customer_portal/src/Corporate/EventSubscriber/VerifyStateEventSubscriber.php') =]] -``` - -In line 46, you can see that it handles changes to verify status. -The subscriber only informs that the status has been changed (line 72). - -Now, if you click the **Verify** button during application review, the application gets **Verify** status. - -![Verify status](img/cp_verify_status.png) diff --git a/docs/multisite/languages/back_office_translations.md b/docs/multisite/languages/back_office_translations.md index d72ab64f63..79ac1b7682 100644 --- a/docs/multisite/languages/back_office_translations.md +++ b/docs/multisite/languages/back_office_translations.md @@ -47,33 +47,7 @@ It's good practice to provide your labels in translations files, instead of lite To provide label strings, make use of the `Symfony\Component\Translation\TranslatorInterface` and its `trans()` method. -The method takes as arguments: - -- `id` of the message you want to translate -- an array of parameters -- domain of the string - -Here's an example: - -``` php hl_lines="12-14" -use Symfony\Contracts\Translation\TranslatorInterface; - -final readonly class MyService -{ - public function __construct(private TranslatorInterface $translator) - { - } - - public function getTranslatedDescription(): string - { - return $this->translator->trans( - 'custom.extension.description', - [], - 'custom_extension' - ); - } -} -``` +The method takes the message `id`, an array of parameters, and the string's domain as arguments. The strings are provided in .xliff files. The file should be stored in your project's or your bundle's `Resources/translations` folder. diff --git a/docs/multisite/languages/language_api.md b/docs/multisite/languages/language_api.md deleted file mode 100644 index c3be51f6b3..0000000000 --- a/docs/multisite/languages/language_api.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: You can add languages to the system and get information about existing languages via the PHP API. ---- - -# Language API - -You can manage languages configured in the system with PHP API by using `LanguageService`. - -## Getting language information - -To get a list of all languages in the system use `LanguageService::loadLanguages`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/AddLanguageCommand.php', 32, 37, remove_indent=True) =]] -``` - -## Creating a language - -To create a new language, you need to create a `LanguageCreateStruct` and provide it with the language code and language name. -Then, use `LanguageService::createLanguage` and pass the `LanguageCreateStruct` to it: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/AddLanguageCommand.php', 38, 42, remove_indent=True) =]] -``` diff --git a/docs/multisite/siteaccess/injecting_siteaccess.md b/docs/multisite/siteaccess/injecting_siteaccess.md deleted file mode 100644 index 1e269b14f8..0000000000 --- a/docs/multisite/siteaccess/injecting_siteaccess.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: Inject the SiteAccess service to get SiteAccess information in your custom PHP code. ---- - -# Injecting SiteAccess - -The [service container]([[= symfony_doc =]]/service_container.html) exposes the SiteAccess through the `Ibexa\Core\MVC\Symfony\SiteAccess\SiteAccessService` service, which fulfills the `Ibexa\Core\MVC\Symfony\SiteAccess\SiteAccessServiceInterface` contract. -This means you can inject it into any custom service constructor, type hinting that contract. -You can get the current SiteAccess from that service by calling the `SiteAccessServiceInterface::getCurrent` method. - -For example, define a service which depends on the Repository's ContentService and the SiteAccessService. - -``` yaml -services: - App\MyService: - arguments: ['@Ibexa\Core\MVC\Symfony\SiteAccess\SiteAccessService'] -``` - -``` php -.. ['all' => true], -]; -``` - -## Parsing semantic configuration - -To parse semantic configuration, create a `Configuration` class which extends `Ibexa\Bundle\Core\DependencyInjection\Configuration\SiteAccessAware\Configuration` and then extend its `generateScopeBaseNode()` method: - -``` php hl_lines="19" -[[= include_code('code_samples/multisite/siteaccess/Configuration.php') =]] -``` - -!!! note - - Default name for the *SiteAccess root node* is `system`, but you can customize it. - To do this, pass the name you want to use as a second argument of `$this->generateScopeBaseNode()`. - -This enables you to use the following SiteAccess-aware configuration: - -``` yaml -acme_example: - system: - : - name: name_1 - custom_setting: - number: 456 - enabled: true - : - name: name_2 - custom_setting: - string: value - number: 123 - enabled: false -``` - -## Mapping to internal settings - -Semantic configuration must always be mapped to internal key/value settings within the service container. -You usually do it in the [service container]([[= symfony_doc =]]/service_container.html) extension. - -``` php -[[= include_file('code_samples/multisite/siteaccess/AcmeExampleExtension.php', 0, 42) =]][[= include_file('code_samples/multisite/siteaccess/AcmeExampleExtension.php', 53, 62) =]] -``` - -You can also map simple settings by calling `$processor->mapSetting()`, without having to call `$processor->mapConfig()` with a callable. - -``` php -[[= include_code('code_samples/multisite/siteaccess/AcmeExampleExtension.php', 45, 46, remove_indent=True) =]] -``` - -!!! caution "Important" - - Always ensure you have defined and loaded default settings. - -In `@AcmeExampleBundle/Resources/config/default_settings.yaml`: - -``` yaml -parameters: - acme_example.default.name: name_1 - acme_example.default.custom_setting: - string: ~ - number: 0 - enabled: false -``` - -### Merging hash values between scopes - -When you define a hash as semantic config, you sometimes don't want the SiteAccess settings to replace the default or group values, -but enrich them by appending new entries. -This is possible by using `$processor->mapConfigArray()`, which you must call outside the closure (before or after), so that it's called only once. - -``` php -[[= include_code('code_samples/multisite/siteaccess/AcmeExampleExtension.php', 49, 49, remove_indent=True) =]] -``` - -Consider the following default config in `default_settings.yaml`: - -``` yaml -parameters: - acme_example.default.custom_setting: - string: ~ - os_types: [windows] - number: 0 - enabled: false - language: php -``` - -And then this semantic configuration in `config/packages/acme.yaml`: - -``` yaml -acme_example: - system: - siteaccess_group: - custom_setting: - string: value - number: 123 - - # Assuming "siteaccess1" is part of "siteaccess_group" - siteaccess1: - custom_setting: - os_types: [linux, macos] - number: 456 - enabled: true - language: javascript -``` - -By calling `mapConfigArray()` you can get the following end configuration, where keys defined for `custom_setting` in default/group/SiteAccess scopes are merged: - -``` yaml -parameters: - acme_example.siteaccess1.custom_setting: - string: value - os_types: [linux, macos] - number: 456 - enabled: true - language: javascript -``` - -#### Merging from second level - -In the example above, entries were merged in respect to the scope order of precedence. -However, because you defined the `os_types` key for `siteaccess1`, it completely overrode the default value, because the merge process is done only at the first level. - -You can add another level by passing `ContextualizerInterface::MERGE_FROM_SECOND_LEVEL` as the third argument to `$contextualizer->mapConfigArray()`: - -``` php -[[= include_code('code_samples/multisite/siteaccess/AcmeExampleExtension.php', 52, 53, remove_indent=True) =]] -``` - -When you use `ContextualizerInterface::MERGE_FROM_SECOND_LEVEL` with the configuration above, you get the following result: - -``` yaml -parameters: - acme_example.siteaccess1.custom_setting: - string: value - os_types: [windows, linux, macos] - number: 456 - enabled: true - language: javascript -``` - -There is also another option, `ContextualizerInterface::UNIQUE`, that ensures the array setting has unique values. -It only works on normal arrays, not hashes. - -!!! note - - Merge isn't recursive. Only second level merge is possible by using `ContextualizerInterface::MERGE_FROM_SECOND_LEVEL` option. - -### Dedicated mapper object - -Instead of passing a callable to `$processor->mapConfig()`, you can pass an instance of -`Ibexa\Bundle\Core\DependencyInjection\Configuration\SiteAccessAware\ConfigurationMapperInterface`. - -This can be useful if you have a lot of configuration to map and don't want to pollute your service container extension class (it's better for maintenance). - -#### Merging hash values between scopes - -You should not use `$contextualizer->mapConfigArray()` within the scope loop, like for simple values. -When using a closure/callable, you usually call it before or after `$processor->mapConfig()`. -For mapper objects, you can use a dedicated interface: `HookableConfigurationMapperInterface`, which defines two methods: `preMap()` and `postMap()`. diff --git a/docs/permissions/permission_overview.md b/docs/permissions/permission_overview.md index 5f89078342..7bc3f48bda 100644 --- a/docs/permissions/permission_overview.md +++ b/docs/permissions/permission_overview.md @@ -31,54 +31,3 @@ Instead, try to organize your content so that it can be covered with general rol Using groups is easier to manage and more secure. It also improves system performance. The more role assignments and complex policies you add for a given user, the more complex the search/load queries are, because they always take permissions into account. - -## Permissions for custom controllers - -You can control access to a custom controller by implementing the `performAccessCheck()` method. - -In the following example the user doesn't have access to the controller unless they have the `section/view` policy: - -``` php {skip-validation} -use Ibexa\Core\MVC\Symfony\Security\Authorization\Attribute; - -public function performAccessCheck(): void -{ - parent::performAccessCheck(); - $this->denyAccessUnlessGranted(new Attribute('section', 'view')); -} -``` - -`Attribute` accepts three arguments: - -- `module` is the policy module (for example,`content`) -- `function` is the function inside the module (for example, `read`) -- `limitations` are optional limitations to check against. Here you can provide two keys: - - `valueObject` is the object you want to check for, for example `ContentInfo`. - - `targets` are a table of value objects that are the target of the operation. - For example, to check if content can be assigned to a Section, provide the Section as `targets`. - `targets` accept location, object state and section objects. - -### Checking user access - -To check if a user has access to an operation, use the `isGranted()` method. -For example, to check if content can be assigned to a Section: - -``` php {skip-validation} -$hasAccess = $this->isGranted( - new Attribute('section', 'assign', ['valueObject' => $contentInfo, 'targets' => [$section]]) -); -``` - -You can also use the permission resolver (`Ibexa\Core\Repository\Permission\PermissionResolver`). -The `canUser()` method checks if the user can perform a given action with the selected object. - -For example: `canUser('content', 'edit', $content, [$location] );` -checks the `content/edit` permission for the provided content item at the provided location. - -### Blocking access to controller action - -To block access to a specific action of the controller, add the following to the action's definition: - -``` php {skip-validation} -$this->denyAccessUnlessGranted(new Attribute('state', 'administrate')); -``` diff --git a/docs/product_catalog/attributes/symbol_attribute_type.md b/docs/product_catalog/attributes/symbol_attribute_type.md index 8596b95309..e093c12882 100644 --- a/docs/product_catalog/attributes/symbol_attribute_type.md +++ b/docs/product_catalog/attributes/symbol_attribute_type.md @@ -29,59 +29,6 @@ The built-in symbol attribute formats in `ibexa/product-catalog-symbol-attribute Maximum length of the symbol value is 160 characters. -## Create custom symbol attribute format - -Under the `ibexa_product_catalog_symbol_attribute.formats` key, you can use configuration to create your own symbol format. - -See the example below: - -``` yaml -ibexa_product_catalog_symbol_attribute: - formats: - manufacturer_part_number: - name: 'Manufacturer Part Number' - pattern: '/^[A-Z]{3}-\d{5}$/' - examples: - - 'RPI-14645' - - 'MSS-24827' - - 'SEE-15444' -``` - -This following example specifies the format for a "Manufacturer Part Number", defined with the `manufacturer_part_number` identifier. - -The pattern is specified using a regular expression. -According to the pattern option, the attribute value: - -- must be a string -- begins with three capital letters (A-Z), followed by a hyphen ("-") -- ends with five digits (0-9), with no other characters before or after - -Certain formats, such as the International Standard Book Number (ISBN-10) and the European Article Number (EAN-13), contain checksum digits and are self-validating. - -To validate checksum of symbol: - -1\. Create a class implementing the `\Ibexa\Contracts\ProductCatalogSymbolAttribute\Value\ChecksumInterface` interface. - -2\. Register the class as a service using the `ibexa.product_catalog.attribute.symbol.checksum` tag and specify the format identifier using the `format` attribute. - -See below the example implementation of checksum validation using Luhn formula: - -``` php -[[= include_code('code_samples/product_catalog/Symbol/Format/Checksum/LuhnChecksum.php') =]] -``` - -Example service definition: - -``` yaml -services: - App\PIM\Symbol\Format\Checksum\LuhnChecksum: - tags: - - name: ibexa.product_catalog.attribute.symbol.checksum - format: my_format -``` - -The format attribute (`my_format`) is the identifier used under the `ibexa_product_catalog_symbol_attribute.formats` key. - ## Search for products with given symbol attribute You can use `SymbolAttribute` Search Criterion to find products by symbol attribute: diff --git a/docs/product_catalog/catalog_api.md b/docs/product_catalog/catalog_api.md deleted file mode 100644 index 2d8d568398..0000000000 --- a/docs/product_catalog/catalog_api.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: Use PHP API to get information about and manage product catalogs. ---- - -# Catalog API - -To get information about product catalogs and manage them, use `CatalogServiceInterface`. - -## Get catalog - -To get a single catalog, use `Ibexa\Contracts\ProductCatalog\CatalogServiceInterface::getCatalog()` and provide it with catalog ID, or `CatalogServiceInterface::getCatalogByIdentifier()` and pass the identifier: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/CatalogCommand.php', 69, 70, remove_indent=True) =]] -``` - -## Get products in catalog - -To get products from a catalog, request the product query from the catalog object with `Ibexa\Contracts\ProductCatalog\Values\CatalogInterface::getQuery()`. -Then, create a new `ProductQuery` based on it and run a product search with `ProductServiceInterface::findProduct()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/CatalogCommand.php', 73, 78, remove_indent=True) =]] -``` - -## Create catalog - -To create a catalog, you need to prepare a `CatalogCreateStruct` that contains: identifier, name, description, and Criteria for filtering products. -Then, pass this struct to `CatalogServiceInterface::createCatalog()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/CatalogCommand.php', 52, 66, remove_indent=True) =]] -``` - -## Update catalog - -Use `CatalogServiceInterface::updateCatalog()` to update an existing catalog. -You must pass the catalog object and a `CatalogUpdateStruct` to the method. -In the following example, you update the catalog to publish it: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/CatalogCommand.php', 81, 84, remove_indent=True) =]] -``` diff --git a/docs/product_catalog/price_api.md b/docs/product_catalog/price_api.md deleted file mode 100644 index 70664c71f9..0000000000 --- a/docs/product_catalog/price_api.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -description: Use PHP API to manage currencies in the shop and product prices. ---- - -# Price API - -## Currencies - -To manage currencies, use `CurrencyServiceInterface`. - -To access a currency object by its code, use `CurrencyServiceInterface::getCurrencyByCode`. -To access a whole list of currencies, use `CurrencyServiceInterface::findCurrencies`. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/CurrencyCommand.php', 46, 53, remove_indent=True) =]] -``` - -To create a new currency, use `CurrencyServiceInterface::createCurrency()` and provide it with a `CurrencyCreateStruct` with code, number of fractional digits and a flag indicating if the currency is enabled: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/CurrencyCommand.php', 61, 63, remove_indent=True) =]] -``` - -## Prices - -To manage prices, use `ProductPriceServiceInterface`. - -To retrieve the price of a product in the currency for the current context, use `Product::getPrice()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 61, 63, remove_indent=True) =]] -``` - -To retrieve the price of a product in a specific currency, use `ProductPriceService::getPriceByProductAndCurrency`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 65, 67, remove_indent=True) =]] -``` - -To get all prices (in different currencies) for a given product, use `ProductPriceServiceInterface::findPricesByProductCode`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 79, 84, remove_indent=True) =]] -``` - -To load price definitions that match given criteria, use `ProductPriceServiceInterface::findPrices`: - -``` php -[[= include_file('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 12, 16) =]] -// ... -[[= include_file('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 85, 95) =]] -``` - -You can also use `ProductPriceServiceInterface` to create or modify existing prices. -For example, to create a new price for a given currency, use `ProductPriceService::createProductPrice` and provide it with a `ProductPriceCreateStruct` object: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 70, 75, remove_indent=True) =]] -``` - -!!! note - - Prices operate using the [`Money`](https://github.com/moneyphp/money) library. - That is why all amounts are provided [in the smallest unit](https://www.moneyphp.org/en/stable/getting-started.html#instantiation). - For example, for euro `50000` refers to 50000 cents, equal to 500 euros. - -### Resolve prices - -To display a product price on a product page, you must calculate its value based on a base price and the context. -Context contains information about any price modifiers that may apply to a specific customer group. -To determine the final price, or resolve the price, use the `PriceResolverInterface` service, which takes the following conditions into account: - -1. Existence of base price for the product in the specified currency -2. Existence of customer group-related modifiers - -If the base price in the specified currency is missing, the return value is `null`. - -To resolve a price of a product in the currency for the current context, use either `PriceResolverInterface::resolvePrice()` or `PriceResolverInterface::resolvePrices()`: - -``` php -[[= include_file('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 7, 8) =]][[= include_file('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 11, 12) =]] -// ... -[[= include_file('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 96, 100) =]] -``` - -## VAT - -To get information about the VAT categories and rates configured in the system, use `VatServiceInterface`. -VAT is configured per region, so you also need to use `RegionServiceInterface` to get the relevant region object. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/VatCommand.php', 42, 42, remove_indent=True) =]] -``` - -To get information about all VAT categories configured for the selected region, use `VatServiceInterface::getVatCategories()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/VatCommand.php', 44, 48, remove_indent=True) =]] -``` - -To get a single VAT category, use `VatServiceInterface::getVatCategoryByIdentifier()` and provide it with the region object and the identifier of the VAT category: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/VatCommand.php', 50, 50, remove_indent=True) =]] -``` diff --git a/docs/product_catalog/product_api.md b/docs/product_catalog/product_api.md deleted file mode 100644 index 48e46a855d..0000000000 --- a/docs/product_catalog/product_api.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -description: Use PHP API to manage products, their attributes, availability, and prices. -month_change: false ---- - -# Product API - -## Products - -[[= product_name =]]'s Product API provides two services for handling product information, which differ in function: - -| Service name | Description | -| ------------ | ----------- | -| `ProductServiceInterface` | Use it to retrieve product data regardless of the source: [[= product_name =]], [[[= pim_product_name =]]](/product_catalog/quable/quable.md), or [remote PIM](add_remote_pim_support.md) | -| `LocalProductServiceInterface` | Use it to modify products defined in [[= product_name =]] | - -!!! tip "Product REST API" - - To learn how to load products using the REST API, see [REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Product/operation/api_productcatalogproductsview_post). - -### Getting product information - -Get an individual product by using the `ProductServiceInterface::getProduct()` method: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 56, 58, remove_indent=True) =]] -``` - -Find multiple products with `ProductServiceInterface::findProducts()`. - -Provide the method with optional filter, query or Sort Clauses. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 60, 69, remove_indent=True) =]] -``` - -See [Product Search Criteria](product_search_criteria.md) and [Product Sort Clauses](product_sort_clauses.md) references for more information about how to use the `ProductQuery` class. - -### Modifying products - -To create, update and delete products, use the `LocalProductServiceInterface`. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 81, 84, remove_indent=True) =]] -``` - -To create a product, use `LocalProductServiceInterface::newProductCreateStruct()` to get a `ProductCreateStruct`. -Provide the method with the product type object and the main language code. -You also need to set (at least) the code for the product and the required Field of the underlying content type, `name`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 71, 77, remove_indent=True) =]] -``` - -To delete a product, use `LocalProductServiceInterface::deleteProduct()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 116, 116, remove_indent=True) =]] -``` - -### Product variants - -#### Searching for variants of a specific product - -You can access the variants of a product by using the `ProductServiceInterface::findProductVariants()` method. -The method takes the product object and a `ProductVariantQuery` object as parameters. - -You can filter variants by: - -- variant codes: - - ``` php - [[= include_code('code_samples/api/product_catalog/src/Command/ProductVariantCommand.php', 51, 54, indent_level=1, remove_indent=True) =]] - ``` - -- product criteria: - - To use [Product Search Criteria](product_search_criteria.md) with `ProductVariantQuery`, wrap it with the `ProductCriterionAdapter` class, as in the example below: - - ``` php hl_lines="4" - [[= include_code('code_samples/api/product_catalog/src/Command/ProductVariantCommand.php', 56, 66, indent_level=1, remove_indent=True) =]] - ``` - -From a variant (`ProductVariantInterface`), you can access the attributes that are used to generate the variant by using the `ProductVariantInterface::getDiscriminatorAttributes()` method. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductVariantCommand.php', 70, 73, remove_indent=True) =]] -``` - -#### Searching for variants across all products - -To search for variants across all products, use the `ProductServiceInterface::findVariants()` method. -This method takes a `ProductVariantQuery` object and returns variants regardless of their base product. - -Unlike `findProductVariants()`, which requires a specific product object, `findVariants()` allows you to search the entire variant catalog. - -You can filter variants by: - -- variant codes: - - ``` php - [[= include_code('code_samples/api/product_catalog/src/Command/ProductVariantCommand.php', 84, 87, indent_level=1, remove_indent=True) =]] - ``` - -- product criteria: - - To use [Product Search Criteria](product_search_criteria.md) with `ProductVariantQuery`, wrap it with the `ProductCriterionAdapter` class, as in the example below: - - ``` php hl_lines="4" - [[= include_code('code_samples/api/product_catalog/src/Command/ProductVariantCommand.php', 93, 100, indent_level=1, remove_indent=True) =]] - ``` - -#### Creating variants - -To create a product variant, use `LocalProductServiceInterface::createProductVariants()`. -This method takes the product and an array of `ProductVariantCreateStruct` objects as parameters. -`ProductVariantCreateStruct` specifies the attribute values and the code for the new variant. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductVariantCommand.php', 86, 91, remove_indent=True) =]] -``` - -### Product assets - -You can get assets assigned to a product by using `AssetServiceInterface`. - -Use `AssetServiceInterface` to get a single asset by providing the product object and the assets's ID as parameters: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductAssetCommand.php', 47, 48, remove_indent=True) =]] -``` - -To get all assets assigned to a product, use `AssetServiceInterface::findAssets()`. -You can retrieve the tags (corresponding to attribute values) of assets with the `AssetInterface::getTags()` method: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductAssetCommand.php', 50, 58, remove_indent=True) =]] -``` - -## Product types - -To work with product types, use `ProductTypeServiceInterface`. - -### Creating product types - -To create a product type, use `LocalProductTypeServiceInterface`. - -First, create a product type struct with `LocalProductTypeServiceInterface::newProductTypeCreateStruct()`, providing the identifier and main language code: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 49, 52, remove_indent=True) =]] -``` - -You can set names in multiple languages by using `setNames()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 54, 57, remove_indent=True) =]] -``` - -To create a virtual product type (for products that don't require shipping), use `setVirtual()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 59, 59, remove_indent=True) =]] -``` - -#### Adding field definitions - -To add custom field definitions to the product type, use `getContentTypeCreateStruct()` to access the underlying content type struct. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 63, 69, remove_indent=True) =]] -``` - -#### Assigning attributes - -To assign product attributes to the product type, use `setAssignedAttributesDefinitions()` with an array of `AssignAttributeDefinitionStruct` objects. - -First, retrieve the attribute definition by using `AttributeDefinitionServiceInterface`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 71, 71, remove_indent=True) =]] -``` - -Then create the assignment struct with the attribute definition, and set whether it's required and whether it's a discriminator (used for product variants): - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 73, 79, remove_indent=True) =]] -``` - -For more information about working with attributes through PHP API, see [Attributes](#attributes). - -#### Storing new product type - -Finally, create the product type with `LocalProductTypeServiceInterface::createProductType()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 81, 81, remove_indent=True) =]] -``` - -### Getting product types - -Get a product type object by using `ProductTypeServiceInterface::getProductType()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 83, 83, remove_indent=True) =]] -``` - -You can also get a list of product types with `ProductTypeServiceInterface::findProductTypes()`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 87, 91, remove_indent=True) =]] -``` - -## Product availability - -Product availability is an object which defines whether a product is set as available, in what stock, and whether it can be ordered. -To manage it, use `ProductAvailabilityServiceInterface`. - -The `AvailabilityInterface` provides two distinct availability values: - -- `getAvailability()` returns the value of availability flag as set for the product -- `getComputedAvailability()` returns whether the product can be ordered - -For more information about the distinction between these two values, see [Availability and computed availability](products.md#availability-and-computed-availability). - -To check whether a product is set as available, use `ProductAvailabilityServiceInterface::hasAvailability()`. - -You can get the availability object with `ProductAvailabilityServiceInterface::getAvailability()`. -The returned object contains both the stored and computed availability: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 92, 97, remove_indent=True) =]] -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 120, 120, remove_indent=True) =]] -``` - -To evaluate computed availability for a specific context, for example, a specific requested quantity or customer group, pass an optional `AvailabilityContextInterface` object as the second argument: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 108, 114, remove_indent=True) =]] -``` - -To change availability for a product, use `ProductAvailabilityServiceInterface::updateProductAvailability()` with a `ProductAvailabilityUpdateStruct` and provide it with the product object. -The second parameter defines whether product is available, and the third whether its stock is infinite. The fourth parameter is the stock number: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 99, 101, remove_indent=True) =]] -``` - -## Attributes - -To get information about product attribute groups, use the `AttributeGroupServiceInterface`, or `LocalAttributeGroupServiceInterface` to modify attribute groups. - -`AttributeGroupServiceInterface::getAttributeGroup()` enables you to get a single attribute group by its identifier. -`AttributeGroupServiceInterface::findAttributeGroups()` gets attribute groups, all of them or filtered with an optional `AttributeGroupQuery` object: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 50, 50, remove_indent=True) =]] - -[[= include_code('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 71, 75, remove_indent=True) =]] -``` - -To create an attribute group, use `LocalAttributeGroupServiceinterface::createAttributeGroup()` and provide it with an `AttributeGroupCreateStruct`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 45, 48, remove_indent=True) =]] -``` - -To get information about product attributes, use the `AttributeDefinitionServiceInterface`, or `LocalAttributeDefinitionServiceInterface` to modify attributes. - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 57, 58, remove_indent=True) =]] -``` - -To create an attribute, use `LocalAttributeGroupServiceinterface::createAttributeDefinition()` and provide it with an `AttributeDefinitionCreateStruct`: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 62, 67, remove_indent=True) =]] -``` diff --git a/docs/product_catalog/product_catalog_guide.md b/docs/product_catalog/product_catalog_guide.md index 4df7dd972b..b27345ade9 100644 --- a/docs/product_catalog/product_catalog_guide.md +++ b/docs/product_catalog/product_catalog_guide.md @@ -48,7 +48,7 @@ For more information, see [Product attributes](products.md#product-attributes) a ### Product variants One product can have multiple versions, for example, there can be a t-shirt in different colors. -You can [create variants of products](product_api.md#creating-variants), differing in some characteristics, based on product attributes. +You can create variants of products, differing in some characteristics, based on product attributes. ![Product variants](img/product_attributes.png) diff --git a/docs/product_catalog/products.md b/docs/product_catalog/products.md index 846490b39c..4f3e4ad5a7 100644 --- a/docs/product_catalog/products.md +++ b/docs/product_catalog/products.md @@ -106,7 +106,7 @@ The product catalog distinguishes between two types of availability: - Availability as a value set per product or variant - Availability represents whether the product was set as **Available**, for example in the [back office **Availability** tab]([[= user_doc =]]/product_catalog/manage_availability_and_stock/#set-product-availability) or [PHP API](product_api.md#product-availability). + Availability represents whether the product was set as **Available**, for example in the [back office **Availability** tab]([[= user_doc =]]/product_catalog/manage_availability_and_stock/#set-product-availability). - Computed availability diff --git a/docs/product_catalog/quable/quable.md b/docs/product_catalog/quable/quable.md index 1d3229b354..ad365fa08d 100644 --- a/docs/product_catalog/quable/quable.md +++ b/docs/product_catalog/quable/quable.md @@ -26,6 +26,5 @@ Products can be viewed, selected, and embedded in [[= product_name =]], while al [[= cards([ "product_catalog/quable/install_quable", "product_catalog/quable/configure_quable_connector", - "product_catalog/quable/quable_api", ("https://developers.quable.com/", "Quable technical documentation", "Explore Quable's technical documentation"), ]) =]] diff --git a/docs/product_catalog/quable/quable_api.md b/docs/product_catalog/quable/quable_api.md deleted file mode 100644 index cad33bc9be..0000000000 --- a/docs/product_catalog/quable/quable_api.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: Learn how to use PHP and REST APIs to retrieve product data from Quable -month_change: false ---- - - -# [[= pim_product_name =]] API - -As [[= pim_product_name =]] products are represented as [[= product_name =]] products, you can use the existing [Product APIs](product_api.md) to retrieve the product information. - -[[= pim_product_name =]] is the source of truth about products and categories and you should only use the [[= product_name =]] APIs to read the information coming from [[= pim_product_name =]], but you can't use them to modify it. -To modify the information, use the [[[= pim_product_name =]] interface](https://www.quable.com) or the dedicated [[[= pim_product_name =]] APIs](https://developers.quable.com/quable-api/). - -## REST API Usage - -To learn how to work with [[= product_name =]] REST API, see [REST API reference](rest_api_usage.md). - -You can use the following endpoints to retrieve product and category information: - -- [Product REST API](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Product) -- [Taxonomy REST API](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Taxonomy) - -## PHP API Usage - -### Retrieve products - -To retrieve product information coming from [[= pim_product_name =]], use the same APIs as described in [Product API](product_api.md). - -The following example shows how you can retrieve a single product: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 55, 57, remove_indent=True) =]] -``` - -### Search for products - -Use [`ProductQuery`](product_api.md#getting-product-information) to search for multiple products: - -``` php -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 59, 69, remove_indent=True) =]] -``` - -When working with [[= pim_product_name =]] products, the following search criteria are supported: - -|Search Criterion|Search based on| -|-----|-----| -|[CreatedAt](createdat_criterion.md)|Date and time when product was created| -|[LogicalAnd](logicaland_criterion.md)|Composite criterion combining multiple criteria with AND| -|[MatchAll](matchall_criterion.md)|All products| -|[ProductCategory](productcategory_criterion.md)|Product category assigned to product| -|[ProductCategorySubtree](productcategorysubtree_criterion.md)|Product category subtree| -|[ProductCode](productcode_criterion.md)|Product's code| -|[ProductName](productname_criterion.md)|Product's name| -|[ProductType](producttype_criterion.md)|Product type| -|[UpdatedAt](updated_at_criterion.md)|Date and time when product was last updated| - -The following sort clauses are supported: - -|Sort Clause|Sorting based on| -|-----|-----| -|[CreatedAt](createdat_sort_clause.md)|Date and time of the creation of a product| -|[ProductCode](productcode_sort_clause.md)|Product's code| -|[ProductName](productname_sort_clause.md)|Product's name| - -### Manage stock and pricing - -For information stored outside of [[= pim_product_name =]], such as [product availability](product_api.md#product-availability) or [pricing](price_api.md), you can use the existing services to manage them: - -``` php hl_lines="6 14" -// Manage availability -[[= include_code('code_samples/api/product_catalog/src/Command/ProductCommand.php', 86, 90, remove_indent=True) =]] - -// Manage prices -[[= include_file('code_samples/api/product_catalog/src/Command/ProductPriceCommand.php', 69, 75, remove_indent=True) =]] -``` diff --git a/docs/raptor_cdp/raptor_cdp_activation/raptor_cdp_data_export.md b/docs/raptor_cdp/raptor_cdp_activation/raptor_cdp_data_export.md index e4f4e360c2..de2e5ee5c9 100644 --- a/docs/raptor_cdp/raptor_cdp_activation/raptor_cdp_data_export.md +++ b/docs/raptor_cdp/raptor_cdp_activation/raptor_cdp_data_export.md @@ -45,7 +45,6 @@ The first one is used to send the test user data to the Data Manager. If it passes a validation test in the **Activation** section, use the latter one to send a full version. You can extend exported user data with custom fields from your user content, such as date of birth, preferences, or other profile information. -For more information, see [Data customization](raptor_cdp_data_customization.md#export-additional-user-data). Next, go back to [[= product_name_cdp =]] and select **Validate & download**. If the file passes, you can see a confirmation message. @@ -65,7 +64,7 @@ If you make any alterations, select the **Parse File** to generate columns with In the **Transform & Map** section you transform data and map it to a schema. At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. -If you have [extended user data export with custom fields](raptor_cdp_data_customization.md#export-additional-user-data), those fields appear as additional columns in this section. +If user data export has been extended with custom fields, those fields appear as additional columns in this section. Make sure to add them to your schema in Raptor so they can be used for segmentation and recommendations. Next, select **Create schema based on the downloaded columns**. diff --git a/docs/raptor_cdp/raptor_cdp_data_customization.md b/docs/raptor_cdp/raptor_cdp_data_customization.md deleted file mode 100644 index f4731c02d2..0000000000 --- a/docs/raptor_cdp/raptor_cdp_data_customization.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -description: Data customization in Raptor CDP. ---- - -# Customize [[= product_name_cdp =]] data - -You can customize user, content, and product data exported to CDP and you can control what field type information you want to export. -By default, custom field types have basic export functionality. -It casts their `Value` object to string, thanks to `\Stringable` implementation. - -## Export additional user data - -You can extend user data exported to CDP by attaching custom information, for example user content fields or user preferences. -Use it for advanced customer segmentation and recommendations in marketing campaigns. - -To add custom data to user exports, create a class that extends `\Ibexa\Contracts\Cdp\Export\User\AbstractUserItemProcessor` and implement the `doProcess()` method. -The base class handles user field validation and provides helper methods for working with user content. - -The following example adds a custom date of birth field to the exported data: - -``` php -[[= include_code('code_samples/raptor_cdp/date_of_birth_export/src/Export/User/DateOfBirthUserItemProcessor.php') =]] -``` - -Register your processor as a Symfony service and tag it with `ibexa.cdp.export.user.item_processor`: - -``` yaml -services: - - App\Export\User\DateOfBirthUserItemProcessor: - parent: Ibexa\Contracts\Cdp\Export\User\AbstractUserItemProcessor - arguments: - $dateOfBirthFieldIdentifier: 'date_of_birth' - tags: - - { name: 'ibexa.cdp.export.user.item_processor', priority: 100 } -``` - -The `priority` parameter controls the order of execution when multiple processors are registered. -Higher priority values run first. -Your custom processor can modify the data returned from the previous processors, for example by adding new entries or modifying the existing ones. - -The exported user data includes your custom fields: - -```json -{ - "date_of_birth": "2000-01-01", - "id": 1, - "login": "example", - "email": "example@example.org", - "name": "John Doe", -} -``` - -## Export field types - -Field types are exported with metadata, for example, ID, field definition name, type, or value. -You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. -The provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. -Additionally, you can specify `priority` to override the default behavior. -All system Field Processors use `-100` priority, and any higher priority value overrides them. - -The interface is plain and has two methods that you need to provide: - -- **supports** - decides whether your `FieldProcessor` can work with the `Field` instance. -- **process** - takes `Field` instance and then returns a flat array of scalar values that are combined with the payload data. -​ -A common field type is serialized to: - -```json -{ - "field_measurement_simple_id": 1792, - "field_measurement_simple_type": "ibexa_measurement", - "field_measurement_simple_language_code": "eng-GB", - "field_measurement_simple_value_measurement": "data transfer rate", - "field_measurement_simple_value_unit_identifier": "megabyte per second", - "field_measurement_simple_value_unit_symbol": "MB/s", - "field_measurement_simple_value_unit_is_base": false, - "field_measurement_simple_value_base_unit_identifier": "bit per second", - "field_measurement_simple_value_base_unit_symbol": "bit/s", - "field_measurement_simple_value_simple": 100, - "field_measurement_simple_value_simple_base_unit": 800000000 -} -``` - -Field identifier is a prefix that is automatically added to each key. -You can only use scalar values. - -### Built in Field Processors for custom field types - -You can provide your own CDP export functionality by using one of the system Field Processors: - -#### `\Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor` - -It results in the field type being excluded from the exported payload. -To avoid adding the field type data to the payload, register a new service as follows: -​ - -```yaml -custom_fieldtype.cdp.export.field_processor: - class: Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor - autoconfigure: false - arguments: - $fieldTypeIdentifier: custom_fieldtype - tags: - - { name: 'ibexa.cdp.export.content.field_processor', priority: 0 } -``` - -## Export field type values - -To customize export of field type values, provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. -New implementation has to be registered as a service manually or by using autoconfiguration. -The service has to use the tag `ibexa.cdp.export.content.field_value_processor`. -You can also provide `priority` property to override other Field Value Processors. - -- `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. -If the field type returns a single value, provides a `value` key in the array. -You can return multiple values. - -- `FieldValueProcessorInterface::supports` - decides whether `FieldValueProcessor` can work with the `Field`. -​ - -### Built in Field Value Processors for custom field types - -Several system Field Value Processors either work by default or can be registered for custom field types: - -#### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\CastToStringFieldValueProcessor` - -This Processor is a default one, as long as no other Processor with higher priority is registered. It makes `\Stringable` implementation of the field type `\Ibexa\Core\FieldType\Value` object to use it as a value in the final payload. - -#### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\JsonHashFieldValueProcessor` - -This Processor generates JSON data from hash representation of the field type (it uses `\Ibexa\Contracts\Core\FieldType\FieldType::toHash` method). - -!!! caution - - CDP doesn't support column mapping, which allows you to match records on JSON data directly. - -To use `JsonHashFieldValueProcessor`, you need to register a new service: -​ - -```yaml -custom_fieldtype.cdp.export.field_processor: - class: Ibexa\Cdp\Export\Content\FieldValueProcessor\JsonHashFieldValueProcessor - autoconfigure: false - arguments: - $fieldTypeIdentifier: custom_fieldtype - tags: - - { name: 'ibexa.cdp.export.content.field_value_processor', priority: 0 } -``` diff --git a/docs/raptor_cdp/raptor_cdp_guide.md b/docs/raptor_cdp/raptor_cdp_guide.md index a38a50fa0b..3915edbee4 100644 --- a/docs/raptor_cdp/raptor_cdp_guide.md +++ b/docs/raptor_cdp/raptor_cdp_guide.md @@ -83,8 +83,6 @@ For more information, see [CDP data export](raptor_cdp_data_export.md). With [[= product_name_cdp =]], you can export field types and field type values. They're exported with metadata and attributes, for example, ID, field definition name, type, or value. -For more information, see [data customization](raptor_cdp_data_customization.md) documentation in Developer Documentation. - ### Client-side Tracking The final step is setting up a tracking script. diff --git a/docs/search/criteria_reference/logicaland_criterion.md b/docs/search/criteria_reference/logicaland_criterion.md index 0faad50cc0..cf0249c795 100644 --- a/docs/search/criteria_reference/logicaland_criterion.md +++ b/docs/search/criteria_reference/logicaland_criterion.md @@ -6,7 +6,7 @@ description: LogicalAnd Search Criterion The `LogicalAnd` Search Criterion matches content if all provided Criteria match. -When querying for [products](product_api.md), use LogicalAnd instead. +When querying for products, use LogicalAnd instead. ## Arguments diff --git a/docs/search/criteria_reference/logicalor_criterion.md b/docs/search/criteria_reference/logicalor_criterion.md index 4ba749ca7d..759625214e 100644 --- a/docs/search/criteria_reference/logicalor_criterion.md +++ b/docs/search/criteria_reference/logicalor_criterion.md @@ -6,7 +6,7 @@ description: LogicalOr Search Criterion The `LogicalOr` Search Criterion matches content if at least one of the provided Criteria matches. -When querying for [products](product_api.md), use LogicalOr instead. +When querying for products, use LogicalOr instead. ## Arguments diff --git a/docs/search/criteria_reference/price_search_criteria.md b/docs/search/criteria_reference/price_search_criteria.md index b0b50c4c76..475485a865 100644 --- a/docs/search/criteria_reference/price_search_criteria.md +++ b/docs/search/criteria_reference/price_search_criteria.md @@ -5,7 +5,7 @@ page_type: reference # Price Search Criteria reference -Price Search Criteria are only supported by [Price Search (`ProductPriceServiceInterface::findPrices`)](price_api.md#prices). +Price Search Criteria are only supported by price search. With these Criteria you can filter prices by currency, customer group, product, and more. diff --git a/docs/search/criteria_reference/product_search_criteria.md b/docs/search/criteria_reference/product_search_criteria.md index e1bff9f7cd..a766ca2b2d 100644 --- a/docs/search/criteria_reference/product_search_criteria.md +++ b/docs/search/criteria_reference/product_search_criteria.md @@ -6,7 +6,7 @@ month_change: false # Product Search Criteria reference -Product Search Criteria are supported by [product and product variant search](product_api.md#products) with the following methods: +Product Search Criteria are supported by product and product variant search. - `ProductServiceInterface::findProducts()` - `ProductServiceInterface::findProductVariants()` @@ -16,7 +16,7 @@ Search Criterion let you filter product by specific attributes, for example, col ## Product Search Criteria -To query for products coming from [[= pim_product_name =]], see [[[= pim_product_name =]] Search API](/product_catalog/quable/quable_api.md#search-for-products) for details about the integration. +To query for products coming from [[= pim_product_name =]], see [[[= pim_product_name =]]](../../product_catalog/quable/quable.md) for details about the integration. |Search Criterion|Search based on|Local product catalog|[[= pim_product_name =]]| |-----|-----|-----|-----| diff --git a/docs/search/sort_clause_reference/product_sort_clauses.md b/docs/search/sort_clause_reference/product_sort_clauses.md index e4d146f0bc..27806cf51e 100644 --- a/docs/search/sort_clause_reference/product_sort_clauses.md +++ b/docs/search/sort_clause_reference/product_sort_clauses.md @@ -5,11 +5,11 @@ page_type: reference # Product Sort Clauses -Product Sort Clauses are only supported by [Product Search (`ProductServiceInterface::findProduct`)](product_api.md#products). +Product Sort Clauses are only supported by product search. By using Sort Clause you can filter product by specific attributes, for example: price, code, or availability. -To sort products coming from [[= pim_product_name =]], see [[[= pim_product_name =]] Search API](../../product_catalog/quable/quable_api.md#search-for-products) for details about the add-on. +To sort products coming from [[= pim_product_name =]], see [[[= pim_product_name =]]](../../product_catalog/quable/quable.md) for details about the add-on. | Sort Clause | Sorting based on | Local product catalog | [[= pim_product_name =]] | |-----|-----|-----|-----| diff --git a/docs/snippets/search_term_aggregation_settings.md b/docs/snippets/search_term_aggregation_settings.md deleted file mode 100644 index d2352a020e..0000000000 --- a/docs/snippets/search_term_aggregation_settings.md +++ /dev/null @@ -1,10 +0,0 @@ -## Settings - -You can define additional limits to the results using the `setLimit()` and `setMinCount()` methods. -The following example limits the number of terms returned to 5 and only considers terms that have 10 or more results: - -``` php {skip-validation} -$aggregation = new //... -$aggregation->setLimit(5); -$aggregation->setMinCount(10); -``` diff --git a/docs/users/segment_api.md b/docs/users/segment_api.md deleted file mode 100644 index b1aee5e58d..0000000000 --- a/docs/users/segment_api.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -description: You can use PHP API to get segment information, create and manage segments, and assign users to them. ---- - -# Segment API - -Segments enable you to profile the content displayed to specific users. - -To manage segments, use the `SegmentationService`. - -## Getting segment information - -To load a segment group, use `SegmentationService::loadSegmentGroupByIdentifier()`. -Get all segments assigned to the group with `SegmentationService::loadSegmentsAssignedToGroup()`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 49, 55, remove_indent=True) =]] -``` - -Similarly, you can load a segment by using `SegmentationService::loadSegmentByIdentifier()`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 57, 57, remove_indent=True) =]] -``` - -## Checking assignment - -You can check whether a user is assigned to a segment with `SegmentationService::isUserAssignedToSegment()`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 61, 65, remove_indent=True) =]] -``` - -## Assigning users - -To assign a user to a segment, use `SegmentationService::assignUserToSegment()`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 59, 59, remove_indent=True) =]] -``` - -## Creating segments - -Each segment must be assigned to a segment group. - -To create a segment group, use `SegmentationService::createSegmentGroup()` and provide it with a `SegmentGroupCreateStruct`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 33, 39, remove_indent=True) =]] -``` - -To add a segment, use `SegmentationService::createSegment()` and provide it with a `SegmentCreateStruct`, which takes an existing group as one of the parameters: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 41, 47, remove_indent=True) =]] -``` - -## Updating segments - -To update a segment or a segment group, use `SegmentationService::updateSegment()` or `SegmentationService::updateSegmentGroup()` and provide it with `SegmentUpdateStruct` or `SegmentGroupUpdateStruct`. - -## Deleting segments - -To delete a segment or a segment group, use `SegmentationService::removeSegment()` or `SegmentationService::removeSegmentGroup()`: - -``` php -[[= include_code('code_samples/api/public_php_api/src/Command/SegmentCommand.php', 67, 67, remove_indent=True) =]] -``` diff --git a/docs/users/user_authentication.md b/docs/users/user_authentication.md index 60039c3c00..c17f9be127 100644 --- a/docs/users/user_authentication.md +++ b/docs/users/user_authentication.md @@ -56,50 +56,3 @@ security: encoders: Symfony\Component\Security\Core\User\User: plaintext ``` - -### Implement the listener - -In the `config/services.yaml` file: - -``` yaml -services: - App\EventListener\InteractiveLoginListener: - arguments: ['@ibexa.api.service.user'] - tags: - - { name: kernel.event_subscriber } -``` - -Don't mix `MVCEvents::INTERACTIVE_LOGIN` event (specific to [[= product_name =]]) and `SecurityEvents::INTERACTIVE_LOGIN` event (fired by Symfony security component). - -``` php -[[= include_file('code_samples/user_management/in_memory/src/EventSubscriber/AuthenticationTokenCreatedSubscriber.php') =]] -``` - -In `config/packages/security.yaml`, add the `memory` and `chain` user providers, store some in-memory users with their passwords in plain text and a basic role, set a `plaintext` password encoder for the `memory` provider's `InMemoryUser`, and configure the firewall to use the `chain` provider: - -``` yaml hl_lines="4 9-14 18-20 26" -[[= include_file('code_samples/user_management/in_memory/config/packages/security.yaml') =]] -``` - -In the `config/services.yaml` file, declare the subscriber as a service to pass your user map. -Since it implements the `EventSubscriberInterface`, it's automatically tagged as a `kernel.event_subscriber`. -The config resolver and user service injections are auto-wired automatically. - -``` yaml -[[= include_file('code_samples/user_management/in_memory/config/services.yaml') =]] -``` - -You can list the subscribers with the following command to check their order: - -``` bash -php bin/console debug:event-dispatcher AuthenticationTokenCreatedEvent -``` - -Notice that the example subscriber priority is `11` so it's executed before the `Ibexa\Core\MVC\Symfony\Security\Authentication\EventSubscriber\OnAuthenticationTokenCreatedRepositoryUserSubscriber` which set the [[= product_name_base =]] user as the current user. - -From the back office, create the mapped users. -For this example, create a new user with the login `generic_customer` and a random password so the mapping works correctly. -This account can belong to either the **Customers** or the **Anonymous users** group. - -You can now log in with an in-memory user. -In the Symfony debug toolbar, you should see the in-memory user as this example uses `UserWrapped`. diff --git a/docs/users/users.md b/docs/users/users.md index b13bd4f3a2..58ae791ff3 100644 --- a/docs/users/users.md +++ b/docs/users/users.md @@ -29,5 +29,4 @@ All such user accounts have the same underlying mechanism and enable you to cont [[= cards([ "users/customer_groups", - "users/segment_api", ], columns=2) =]] diff --git a/mkdocs.yml b/mkdocs.yml index bb284b61db..bac2c00c67 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -157,18 +157,14 @@ nav: - Quable product guide: product_catalog/quable/quable_guide.md - Set up Quable synchronization: product_catalog/quable/install_quable.md - Configure Quable: product_catalog/quable/configure_quable_connector.md - - Quable API: product_catalog/quable/quable_api.md - Product catalog configuration: product_catalog/product_catalog_configuration.md - Products: product_catalog/products.md - Attributes: - Date and Time attribute: product_catalog/attributes/date_and_time.md - Symbol attribute type: product_catalog/attributes/symbol_attribute_type.md - - Product API: product_catalog/product_api.md - Catalogs: product_catalog/catalogs.md - - Catalog API: product_catalog/catalog_api.md - Enable purchasing products: product_catalog/enable_purchasing_products.md - Prices: product_catalog/prices.md - - Price API: product_catalog/price_api.md - Add remote PIM support: product_catalog/add_remote_pim_support.md - Customer management: - Customer Portal: customer_management/customer_portal.md @@ -188,7 +184,6 @@ nav: - SiteAccess: multisite/siteaccess/siteaccess.md - SiteAccess matching: multisite/siteaccess/siteaccess_matching.md - SiteAccess-aware configuration: multisite/siteaccess/siteaccess_aware_configuration.md - - Injecting SiteAccess: multisite/siteaccess/injecting_siteaccess.md - Set up campaign SiteAccess: multisite/set_up_campaign_siteaccess.md - Set up translation SiteAccess: multisite/set_up_translation_siteaccess.md - Site Factory: @@ -196,7 +191,6 @@ nav: - Site Factory configuration: multisite/site_factory/site_factory_configuration.md - Languages: - Languages: multisite/languages/languages.md - - Language API: multisite/languages/language_api.md - Back office translations: multisite/languages/back_office_translations.md - Translations management: - Translations management: multisite/translations_management/translations_management.md @@ -222,7 +216,6 @@ nav: - User authentication: users/user_authentication.md - User grouping: - Customer groups: users/customer_groups.md - - Segment API: users/segment_api.md - Recommendations: - Raptor integration: recommendations/raptor_integration/raptor_connector.md - Raptor integration guide: recommendations/raptor_integration/raptor_connector_guide.md @@ -236,7 +229,6 @@ nav: - Configure Raptor CDP: raptor_cdp/raptor_cdp_activation/raptor_cdp_configuration.md - Export Raptor CDP data: raptor_cdp/raptor_cdp_activation/raptor_cdp_data_export.md - Track with Raptor CDP: raptor_cdp/raptor_cdp_activation/raptor_cdp_add_tracking.md - - Customize Raptor CDP data: raptor_cdp/raptor_cdp_data_customization.md - Search: - Search: search/search.md - Search Criteria and Sort Clauses: search/search_criteria_and_sort_clauses.md diff --git a/tests/python/invariants-baseline.yaml b/tests/python/invariants-baseline.yaml index 960b561fdd..9b3a52b521 100644 --- a/tests/python/invariants-baseline.yaml +++ b/tests/python/invariants-baseline.yaml @@ -47,64 +47,6 @@ php_code_sample: - administration/configuration/repository_configuration.md - administration/dashboard/php_api_dashboard_service.md - administration/recent_activity/recent_activity.md - - ai/ai_actions/configure_ai_actions.md - - ai/ai_actions/extend_ai_actions.md - - ai/mcp/mcp_usage.md - - api/event_reference/event_reference.md - - api/graphql/graphql_custom_ft.md - - api/php_api/php_api.md - - api/rest_api/extending_rest_api/adding_custom_media_type.md - - api/rest_api/extending_rest_api/creating_new_rest_resource.md - - api/rest_api/rest_api_usage/rest_requests.md - - api/rest_api/rest_api_usage/testing_rest_api.md - - customer_management/cp_applications.md - - infrastructure_and_maintenance/background_tasks.md - - infrastructure_and_maintenance/cache/http_cache/content_aware_cache.md - - infrastructure_and_maintenance/cache/http_cache/context_aware_cache.md - - infrastructure_and_maintenance/cache/http_cache/reverse_proxy.md - - infrastructure_and_maintenance/cache/persistence_cache.md - - multisite/languages/back_office_translations.md - - multisite/languages/language_api.md - - multisite/siteaccess/injecting_siteaccess.md - - multisite/siteaccess/siteaccess_aware_configuration.md - - multisite/translations_management/extend_translations_management.md - - permissions/custom_policies.md - - permissions/permission_overview.md - - product_catalog/attributes/symbol_attribute_type.md - - product_catalog/catalog_api.md - - product_catalog/create_custom_attribute_type.md - - product_catalog/create_custom_availability_strategy.md - - product_catalog/create_custom_catalog_filter.md - - product_catalog/create_custom_name_schema_strategy.md - - product_catalog/create_product_code_generator.md - - product_catalog/price_api.md - - product_catalog/product_api.md - - product_catalog/quable/quable_api.md - - raptor_cdp/raptor_cdp_data_customization.md - - recommendations/raptor_integration/tracking_php_api.md - - snippets/search_term_aggregation_settings.md - - templating/components.md - - templating/embed_and_list_content/embed_content.md - - templating/layout/add_breadcrumbs.md - - templating/layout/add_login_form.md - - templating/layout/add_navigation_menu.md - - templating/queries_and_controllers/controllers.md - - templating/queries_and_controllers/create_custom_query_type.md - - templating/render_content/render_content_in_php.md - - templating/templates/create_custom_view_matcher.md - - tutorials/beginner_tutorial/5_display_a_list_of_content_items.md - - tutorials/beginner_tutorial/7_embed_content.md - - tutorials/generic_field_type/1_implement_the_point2d_value_class.md - - tutorials/generic_field_type/2_define_point2d_field_type.md - - tutorials/generic_field_type/3_create_form_for_point2d.md - - tutorials/generic_field_type/6_settings.md - - tutorials/generic_field_type/7_add_a_validation.md - - tutorials/generic_field_type/8_data_migration.md - - tutorials/page_and_form_tutorial/4_create_a_custom_block.md - - users/oauth_client.md - - users/oauth_server.md - - users/segment_api.md - - users/user_authentication.md # 0 page(s) carry the stale internal `delete:` marker. stale_delete_marker: []