Code samples usage

.github/workflows/build.yaml

@@ -104,3 +104,100 @@ jobs:
 
             - name: Run PHPStan analysis
               run: composer phpstan
+
+    code-samples-inclusion-check:
+        name: Check code samples inclusion
+        runs-on: ubuntu-latest
+        if: github.event_name == 'pull_request'
+        permissions:
+            # Needed to manage the comment
+            pull-requests: write
+
+        steps:
+            -   name: List modified files
+                id: list
+                run: |
+                    URL="https://api.github.com/repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files"
+                    echo 'CODE_SAMPLES_CHANGE<<CODE_SAMPLES_CHANGE_DELIMITER' >> "$GITHUB_OUTPUT"
+                    curl -s -X GET -G $URL | jq -r '.[] | .filename,.previous_filename' | grep '^code_samples/' | tr '\n' ' ' >> "$GITHUB_OUTPUT"
+                    echo '' >> "$GITHUB_OUTPUT"
+                    echo 'CODE_SAMPLES_CHANGE_DELIMITER' >> "$GITHUB_OUTPUT"
+
+            -   name: Checkout target branch (base_ref)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                uses: actions/checkout@v3
+                with:
+                    ref: ${{ github.base_ref }}
+            -   name: Log target branch code_samples usage
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                run: |
+                    git fetch origin
+                    git checkout origin/${{ github.head_ref }} -- tools/code_samples/code_samples_usage.php
+                    php tools/code_samples/code_samples_usage.php ${{ steps.list.outputs.CODE_SAMPLES_CHANGE }} > $HOME/code_samples_usage_target.txt
+
+            -   name: Checkout source branch (head_ref)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                uses: actions/checkout@v3
+                with:
+                    ref: ${{ github.head_ref }}
+            -   name: Log source branch code_samples usage
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                run: php tools/code_samples/code_samples_usage.php ${{ steps.list.outputs.CODE_SAMPLES_CHANGE }} > $HOME/code_samples_usage_source.txt
+
+            -   name: Compare code_samples usages (diff --unified)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                # diff returns 1 if there is a difference, this is normal but seen as an error by the job.
+                continue-on-error: true
+                run: |
+                    source_length=`wc -l < $HOME/code_samples_usage_source.txt`
+                    target_length=`wc -l < $HOME/code_samples_usage_target.txt`
+                    diff -U $(( source_length > target_length ? source_length : target_length )) $HOME/code_samples_usage_target.txt $HOME/code_samples_usage_source.txt > $HOME/code_samples_usage.diff
+            -   name: Check for differences
+                id: diff
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != ''
+                run: |
+                    echo "CODE_SAMPLES_DIFF=$(wc -l < $HOME/code_samples_usage.diff | xargs)" >> "$GITHUB_OUTPUT"
+            -   name: Convert code_samples usages differences (diff2html)
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                run: |
+                    npm install -g diff2html-cli
+                    diff2html -f html -s side -t 'code_samples/ changes report' --su hidden --fct false -o stdout -i file -- $HOME/code_samples_usage.diff > $HOME/code_samples_usage.diff.html
+            -   name: Upload code_samples usages differences artifact
+                id: artifact
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                uses: actions/upload-artifact@v4
+                with:
+                    name: code_samples_usage.diff.html
+                    path: ~/code_samples_usage.diff.html
+                    overwrite: true
+            -   name: Convert code_samples usages for comment
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                run: |
+                    echo '# code_samples/ change report' >> code_samples_usage.diff.md
+                    echo '' >> code_samples_usage.diff.md
+                    php tools/code_samples/code_samples_usage_diff2html.php $HOME/code_samples_usage.diff >> code_samples_usage.diff.md
+                    echo '<a href="${{ steps.artifact.outputs.artifact-url }}">Download colorized diff</a>' >> code_samples_usage.diff.md
+            -   name: Find Comment
+                id: find-comment
+                uses: peter-evans/find-comment@v3
+                with:
+                    issue-number: ${{ github.event.pull_request.number }}
+                    comment-author: 'github-actions[bot]'
+                    body-includes: 'code_samples/ change report'
+            -   name: Delete comment
+                if: steps.find-comment.outputs.comment-id != ''
+                uses: actions/github-script@v6
+                with:
+                    script: |
+                        github.rest.issues.deleteComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          comment_id: ${{ steps.find-comment.outputs.comment-id }}
+                        })
+            -   name: Create comment
+                if: steps.list.outputs.CODE_SAMPLES_CHANGE != '' && steps.diff.outputs.CODE_SAMPLES_DIFF != '0'
+                uses: peter-evans/create-or-update-comment@v4
+                with:
+                    issue-number: ${{ github.event.pull_request.number }}
+                    body-path: code_samples_usage.diff.md
+                    edit-mode: replace

code_samples/api/product_catalog/src/Command/AttributeCommand.php

@@ -29,8 +29,15 @@ final class AttributeCommand extends Command
 
     private PermissionResolver $permissionResolver;
 
-    public function __construct(LocalAttributeDefinitionServiceInterface $localAttributeDefinitionService, AttributeDefinitionServiceInterface $attributeDefinitionService, AttributeGroupServiceInterface $attributeGroupService, LocalAttributeGroupServiceInterface $localAttributeGroupService, AttributeTypeServiceInterface $attributeTypeService, UserService $userService, PermissionResolver $permissionResolver)
-    {
+    public function __construct(
+        LocalAttributeDefinitionServiceInterface $localAttributeDefinitionService,
+        AttributeDefinitionServiceInterface $attributeDefinitionService,
+        AttributeGroupServiceInterface $attributeGroupService,
+        LocalAttributeGroupServiceInterface $localAttributeGroupService,
+        AttributeTypeServiceInterface $attributeTypeService,
+        UserService $userService,
+        PermissionResolver $permissionResolver
+    ) {
         $this->localAttributeGroupService = $localAttributeGroupService;
         $this->attributeGroupService = $attributeGroupService;
         $this->attributeTypeService = $attributeTypeService;

code_samples/api/product_catalog/src/Command/ProductCommand.php

@@ -32,8 +32,14 @@ final class ProductCommand extends Command
 
     private ProductAvailabilityServiceInterface $productAvailabilityService;
 
-    public function __construct(UserService $userService, PermissionResolver $permissionResolver, ProductTypeServiceInterface $productTypeService, ProductServiceInterface $productService, LocalProductServiceInterface $localProductService, ProductAvailabilityServiceInterface $productAvailabilityService)
-    {
+    public function __construct(
+        UserService $userService,
+        PermissionResolver $permissionResolver,
+        ProductTypeServiceInterface $productTypeService,
+        ProductServiceInterface $productService,
+        LocalProductServiceInterface $localProductService,
+        ProductAvailabilityServiceInterface $productAvailabilityService
+    ) {
         $this->userService = $userService;
         $this->permissionResolver = $permissionResolver;
         $this->productService = $productService;

docs/pim/price_api.md

@@ -48,7 +48,6 @@ To load price definitions that match given criteria, use `ProductPriceServiceInt
 
 ``` 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', 100, 110) =]]
 ```
@@ -81,7 +80,6 @@ To resolve a price of a product in the currency for the current context, use eit
 
 ``` 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', 111, 115) =]]
 ```

docs/pim/product_api.md

@@ -20,36 +20,36 @@ description: Use PHP API to manage products in PIM, their attributes, availabili
 Get an individual product by using the `productService::getProduct()` method:
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 62, 65) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 68, 71) =]]
 ```
 
 Find multiple products with `productService::findProducts()`.
 Provide the method with optional filter, query or Sort Clauses.
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 66, 76) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 72, 82) =]]
 ```
 
 ### Modifying products
 
 To create, update and delete products, use the `LocalProductServiceInterface`.
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 87, 91) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 93, 97) =]]
 ```
 
 To create a product, use `LocalProductService::newProductCreateStruct()`.
 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_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 77, 84) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 83, 90) =]]
 ```
 
 To delete a product, use `LocalProductService::deleteProduct()`:
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 114, 115) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 120, 121) =]]
 ```
 
 ### Product variants
@@ -125,15 +125,15 @@ Get the availability object with `getAvailability()`.
 You can then use `ProductAvailabilityServiceInterface::getStock` to get the stock number for the product:
 
 ```php
-[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 98, 103) =]]        }
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 104, 109) =]]        }
 ```
 
 To change availability for a product, use `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_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 106, 109) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 112, 115) =]]
 ```
 
 ## Attributes
@@ -145,27 +145,27 @@ or `LocalAttributeGroupServiceInterface` to modify attribute groups.
 `AttributeGroupServiceInterface::findAttributeGroups()` get all attribute groups, base on optional query:
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 64, 65) =]]
-[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 85, 90) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 71, 72) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 92, 97) =]]
 ```
 
 To create an attribute group, use `LocalAttributeGroupServiceinterface::createAttributeGroup`
 and provide it with an `AttributeGroupCreateStruct`:
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 59, 63) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 66, 70) =]]
 ```
 
 To get information about product attributes, use the `AttributeDefinitionServiceInterface`,
 or `LocalAttributeDefinitionServiceInterface` to modify attributes.
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 71, 73) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 78, 80) =]]
 ```
 
 To create an attribute, use `LocalAttributeGroupServiceinterface::createAttributeDefinition`
 and provide it with an `AttributeDefinitionCreateStruct`:
 
 ``` php
-[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 76, 82) =]]
+[[= include_file('code_samples/api/product_catalog/src/Command/AttributeCommand.php', 83, 89) =]]
 ```