From efe4c7b308bd5f99682545d10ca8b6bb075cba8e Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 22 May 2024 17:47:56 +0200 Subject: [PATCH 1/4] Rework "Using API services" --- docs/api/php_api/php_api.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/api/php_api/php_api.md b/docs/api/php_api/php_api.md index 8be5ebbf3a..e0456db43c 100644 --- a/docs/api/php_api/php_api.md +++ b/docs/api/php_api/php_api.md @@ -15,10 +15,7 @@ Using the API ensures that your code will be forward compatible with future rele ## Using API services -You can access the PHP API by injecting relevant services into your code. - The API provides access to Content, User, content types and other features through various services. -Those services are obtained using `get[ServiceName]()` methods: `getContentService()`, `getUserService()`, etc. The full list of available services covers: @@ -48,21 +45,29 @@ The full list of available services covers: - [UserPreferenceService](https://github.com/ibexa/core/blob/main/src/contracts/Repository/UserPreferenceService.php) - [UserService](https://github.com/ibexa/core/blob/main/src/contracts/Repository/UserService.php) +You can access the PHP API by injecting relevant services into your code. + +- Using [auto-wiring]([[=symfony_doc=]]/service_container/autowiring.html), and the service classname in the `Ibexa\Contracts` namespace (see `bin/console debug:autowiring | grep Ibexa.Contracts`). +- Using [service parameters]([[=symfony_doc=]]/service_container.html#service-parameters), and the service aliases (see `bin/console debug:autowiring | grep ibexa.api`). +- Using Repository's `get[ServiceName]()` methods: [`Repository::getContentService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L46), [`getUserService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L111), etc. + (Prefer injecting several Repository's dedicated services instead of the whole Repository if the Repository itself is not needed.) +- (Not recommended) Using `Ibexa\Bundle\Core\Controller::getRepository()` by extending it from your [custom controller](controllers.md#controllers). (Prefer dependency injection.) + ## Value objects -The services provide interaction with read-only value objects from the `Ibexa\Contracts\Core\Repository\Values` namespace. -Those objects are divided into sub-namespaces, such as `Content`, `User` or `ObjectState`. +The services provide interaction with read-only value objects from the [`Ibexa\Contracts\Core\Repository\Values`](https://github.com/ibexa/core/tree/v4.6.6/src/contracts/Repository/Values) namespace. +Those objects are divided into sub-namespaces, such as [`Content`](https://github.com/ibexa/core/tree/v4.6.6/src/contracts/Repository/Values/Content), [`User`](https://github.com/ibexa/core/tree/v4.6.6/src/contracts/Repository/Values/User) or [`ObjectState`](https://github.com/ibexa/core/tree/v4.6.6/src/contracts/Repository/Values/ObjectState). Each sub-namespace contains a set of value objects, such as [`Content\Content`](https://github.com/ibexa/core/blob/main/src/contracts/Repository/Values/Content/Content.php) or [`User\Role`](https://github.com/ibexa/core/blob/main/src/contracts/Repository/Values/User/Role.php). Value objects come with their own properties, such as `$content->id` or `$location->hidden`, as well as with methods that provide access to more related information, -such as `Relation::getSourceContentInfo()` or `Role::getPolicies()`. +such as [`Content\Relation::getSourceContentInfo()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Values/Content/Relation.php#L80) or [`User\Role::getPolicies()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Values/User/Role.php#L60). ### Creating and updating objects Value objects fetch data from the Repository and are read-only. -To create and modify Repository values you need to use structs, such as `getContentCreateStruct()` or `getContentUpdateStruct()`. +To create and modify Repository values you need to use data structures, such as [`ContentService::newContentCreateStruct()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/ContentService.php#L572) or [`LocationService::newLocationUpdateStruct()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/LocationService.php#L238). ### Value info objects From 9c90f00bb2d8d19374141b17f7b7bd6670fb199e Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Wed, 22 May 2024 17:54:23 +0200 Subject: [PATCH 2/4] php_api.md: Use magic link --- docs/api/php_api/php_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/php_api/php_api.md b/docs/api/php_api/php_api.md index e0456db43c..ab9b45c53d 100644 --- a/docs/api/php_api/php_api.md +++ b/docs/api/php_api/php_api.md @@ -51,7 +51,7 @@ You can access the PHP API by injecting relevant services into your code. - Using [service parameters]([[=symfony_doc=]]/service_container.html#service-parameters), and the service aliases (see `bin/console debug:autowiring | grep ibexa.api`). - Using Repository's `get[ServiceName]()` methods: [`Repository::getContentService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L46), [`getUserService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L111), etc. (Prefer injecting several Repository's dedicated services instead of the whole Repository if the Repository itself is not needed.) -- (Not recommended) Using `Ibexa\Bundle\Core\Controller::getRepository()` by extending it from your [custom controller](controllers.md#controllers). (Prefer dependency injection.) +- (Not recommended) Using `Ibexa\Bundle\Core\Controller::getRepository()` by extending it from your [custom controller](controllers.md). (Prefer dependency injection.) ## Value objects From dd6af11f150f86c636769b24529da32869b9f7f9 Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Thu, 23 May 2024 16:13:15 +0200 Subject: [PATCH 3/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tomasz Dąbrowski <64841871+dabrt@users.noreply.github.com> --- docs/api/php_api/php_api.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/api/php_api/php_api.md b/docs/api/php_api/php_api.md index ab9b45c53d..b5c37b2d7c 100644 --- a/docs/api/php_api/php_api.md +++ b/docs/api/php_api/php_api.md @@ -45,14 +45,16 @@ The full list of available services covers: - [UserPreferenceService](https://github.com/ibexa/core/blob/main/src/contracts/Repository/UserPreferenceService.php) - [UserService](https://github.com/ibexa/core/blob/main/src/contracts/Repository/UserService.php) -You can access the PHP API by injecting relevant services into your code. +You can access the PHP API by injecting relevant services into your code: -- Using [auto-wiring]([[=symfony_doc=]]/service_container/autowiring.html), and the service classname in the `Ibexa\Contracts` namespace (see `bin/console debug:autowiring | grep Ibexa.Contracts`). -- Using [service parameters]([[=symfony_doc=]]/service_container.html#service-parameters), and the service aliases (see `bin/console debug:autowiring | grep ibexa.api`). -- Using Repository's `get[ServiceName]()` methods: [`Repository::getContentService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L46), [`getUserService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L111), etc. +- By using [auto-wiring]([[=symfony_doc=]]/service_container/autowiring.html), and the service classname in the `Ibexa\Contracts` namespace (see `bin/console debug:autowiring | grep Ibexa.Contracts`). +- By using [service parameters]([[=symfony_doc=]]/service_container.html#service-parameters), and service aliases (see `bin/console debug:autowiring | grep ibexa.api`). +- By using the Repository's `get[ServiceName]()` methods: [`Repository::getContentService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L46), [`getUserService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L111), etc. (Prefer injecting several Repository's dedicated services instead of the whole Repository if the Repository itself is not needed.) -- (Not recommended) Using `Ibexa\Bundle\Core\Controller::getRepository()` by extending it from your [custom controller](controllers.md). (Prefer dependency injection.) +!!! caution + + The PHP API's services can be accessed with `Ibexa\Bundle\Core\Controller::getRepository()` by extending it from a [custom controller](controllers.md), but such approach is not recommended, and you should prefer dependency injection. ## Value objects The services provide interaction with read-only value objects from the [`Ibexa\Contracts\Core\Repository\Values`](https://github.com/ibexa/core/tree/v4.6.6/src/contracts/Repository/Values) namespace. @@ -67,7 +69,7 @@ such as [`Content\Relation::getSourceContentInfo()`](https://github.com/ibexa/co ### Creating and updating objects Value objects fetch data from the Repository and are read-only. -To create and modify Repository values you need to use data structures, such as [`ContentService::newContentCreateStruct()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/ContentService.php#L572) or [`LocationService::newLocationUpdateStruct()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/LocationService.php#L238). +To create and modify Repository values, use data structures, such as [`ContentService::newContentCreateStruct()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/ContentService.php#L572) or [`LocationService::newLocationUpdateStruct()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/LocationService.php#L238). ### Value info objects From a3850ef8327419e4ed905b072a05b576323c8b7c Mon Sep 17 00:00:00 2001 From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> Date: Tue, 28 May 2024 15:30:00 +0200 Subject: [PATCH 4/4] Update docs/api/php_api/php_api.md --- docs/api/php_api/php_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/php_api/php_api.md b/docs/api/php_api/php_api.md index b5c37b2d7c..7cf525edb8 100644 --- a/docs/api/php_api/php_api.md +++ b/docs/api/php_api/php_api.md @@ -52,7 +52,7 @@ You can access the PHP API by injecting relevant services into your code: - By using the Repository's `get[ServiceName]()` methods: [`Repository::getContentService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L46), [`getUserService()`](https://github.com/ibexa/core/blob/v4.6.6/src/contracts/Repository/Repository.php#L111), etc. (Prefer injecting several Repository's dedicated services instead of the whole Repository if the Repository itself is not needed.) -!!! caution +!!! caution The PHP API's services can be accessed with `Ibexa\Bundle\Core\Controller::getRepository()` by extending it from a [custom controller](controllers.md), but such approach is not recommended, and you should prefer dependency injection. ## Value objects