Fixed rendering of code samples with skip-validation and hl_lines

README.md

@@ -91,6 +91,25 @@
 composer phpstan -- --generate-baseline
 ```
 
+#### Skipping validation of inline PHP snippets
+
+PHP code blocks embedded directly in Markdown files are extracted and tested with PHPStan.
+To exclude a snippet from validation (for example, for an intentionally incomplete fragment), add the `skip-validation` marker to its opening fence:
+
+````markdown
+``` php {skip-validation}
+```
+````
+
+If the code block uses other options, such as `hl_lines`, they must be placed **inside the same curly-brace group** as the marker:
+
+````markdown
+``` php {skip-validation hl_lines="6 14"}
+```
+````
+
+Both `php {skip-validation} hl_lines="6 14"` and `php hl_lines="6 14" {skip-validation}` are rejected by the Markdown parser, and the whole code block is rendered as plain paragraph text.
+
 ### Deptrac
 
 This repository uses Deptrac to test the code samples. To run the tests locally execute the commands below:

docs/administration/back_office/browser/browser.md

@@ -146,7 +146,7 @@ If an event listener catches additional parameters passed with context, it uses
 
 In the example below, the `johndoe` parameter enables the user to choose multiple items from a **Browser window** by changing `multiple: false` from `my_custom_udw` configuration to `multiple: true`.
 
-``` php {skip-validation} hl_lines="29 30 31"
+``` php {skip-validation hl_lines="29 30 31"}
 class JohnDoeCanSelectMore implements EventSubscriberInterface
 {
     private const CONFIGURATION_NAME = 'my_custom_udw';

docs/multisite/languages/back_office_translations.md

@@ -59,7 +59,7 @@ The method takes as arguments:
 
 Here's an example:
 
-``` php {skip-validation} hl_lines="13 14 15"
+``` php {skip-validation hl_lines="13 14 15"}
 use Symfony\Component\Translation\TranslatorInterface;
 
 private $translator;

docs/product_catalog/quable/quable_api.md

@@ -37,7 +37,7 @@ The following example shows how you can retrieve a single product:
 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, 68, remove_indent=True) =]]
+[[= 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:
@@ -66,9 +66,10 @@ The following sort clauses are supported:
 
 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 {skip-validation} hl_lines="6 14"
+``` php {skip-validation hl_lines="6 14"}
 // Manage availability
-[[= include_file('code_samples/api/product_catalog/src/Command/ProductCommand.php', 84, 89, remove_indent=True) =]]
+[[= 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) =]]
 ```

docs/search/criteria_reference/ancestor_criterion.md

@@ -44,7 +44,7 @@ $query->query = new Criterion\Ancestor([$this->locationService->loadLocation(62)
 
 You can use the Ancestor Search Criterion to create a list of breadcrumbs leading to the Location:
 
-``` php {skip-validation} hl_lines="2"
+``` php {skip-validation hl_lines="2"}
 $query = new LocationQuery();
 $query->query = new Criterion\Ancestor([$this->locationService->loadLocation($locationId)->pathString]);
 

docs/search/criteria_reference/contenttypegroupid_criterion.md

@@ -45,7 +45,7 @@ $query->query = new Criterion\ContentTypeGroupId([1, 2]);
 You can use the `ContentTypeGroupId` Criterion to query all Media content items
 (the default ID for the Media content type group is 3):
 
-``` php {skip-validation} hl_lines="1"
+``` php {skip-validation hl_lines="1"}
         $query->query = new Criterion\ContentTypeGroupId([3]);
 
         $results = $this->searchService->findContent($query);

docs/search/criteria_reference/datemetadata_criterion.md

@@ -58,7 +58,7 @@ $query->query = new Criterion\DateMetadata(
 
 You can use the `DateMetadata` Criterion to search for blog posts that have been created within the last week:
 
-``` php {skip-validation} hl_lines="5"
+``` php {skip-validation hl_lines="5"}
 $query = new LocationQuery;
 $date = strtotime("-1 week");
 $query->query = new Criterion\LogicalAnd([

docs/search/criteria_reference/field_criterion.md

@@ -65,7 +65,7 @@ $query->query = new Criterion\Field('name', Criterion\Operator::CONTAINS, 'Platf
 
 You can use the `Field` Criterion to search for articles that contain the word "featured":
 
-``` php {skip-validation} hl_lines="4"
+``` php {skip-validation hl_lines="4"}
 $query = new LocationQuery();
 $query->query = new Criterion\LogicalAnd([
         new Criterion\ContentTypeIdentifier('article'),

docs/search/criteria_reference/isfieldempty_criterion.md

@@ -33,7 +33,7 @@ $query->query = new Criterion\IsFieldEmpty('title');
 
 You can use the `IsFieldEmpty` Criterion to search for articles that don't have an image:
 
-``` php {skip-validation} hl_lines="4"
+``` php {skip-validation hl_lines="4"}
 $query = new LocationQuery;
 $query->query = new Criterion\LogicalAnd([
         new Criterion\ContentTypeIdentifier('article'),

docs/search/criteria_reference/languagecode_criterion.md

@@ -46,7 +46,7 @@ $query->query = new Criterion\LanguageCode('ger-DE', false);
 You can use the `LanguageCode` Criterion to search for articles that are lacking a translation
 into a specific language:
 
-``` php {skip-validation} hl_lines="5"
+``` php {skip-validation hl_lines="5"}
 $query = new LocationQuery;
 $query->query = new Criterion\LogicalAnd([
     new Criterion\ContentTypeIdentifier('article'),

docs/search/criteria_reference/parentlocationid_criterion.md

@@ -45,7 +45,7 @@ $query->query = new Criterion\ParentLocationId([54, 58]);
 
 You can use the `ParentLocationId` Search Criterion to list blog posts contained in a blog:
 
-``` php {skip-validation} hl_lines="4"
+``` php {skip-validation hl_lines="4"}
 $query = new LocationQuery();
 $query->query = new Criterion\LogicalAnd([
     new Criterion\Visibility(Criterion\Visibility::VISIBLE),

docs/search/criteria_reference/usermetadata_criterion.md

@@ -56,7 +56,7 @@ $query->query = new Criterion\UserMetadata(Criterion\UserMetadata::GROUP, Criter
 
 You can use the `UserMetadata` Criterion to search for blog posts created by the Contributor user group:
 
-``` php {skip-validation} hl_lines="7"
+``` php {skip-validation hl_lines="7"}
 // ID of your custom Contributor User Group
 $contributorGroupId = 32;
 

docs/search/extensibility/index_custom_elasticsearch_data.md

@@ -18,7 +18,7 @@ You can pass the event to a subscriber which gives you access to the document th
 
 In the following example, when an index in created for a content or a location document, the event subscriber adds a `custom_field` of the type [`StringField`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Search-FieldType-StringField.html) to the index:
 
-``` php {skip-validation} hl_lines="19 20 21"
+``` php {skip-validation hl_lines="19 20 21"}
 --8<--
 code_samples/search/custom/src/EventSubscriber/CustomIndexDataSubscriber.php
 --8<--

docs/search/extensibility/manipulate_elasticsearch_query.md

@@ -11,7 +11,7 @@ The following example shows how to add a Search Criterion to all queries.
 
 Depending on your configuration, this might impact all search queries, including those used for search and content tree in the back office.
 
-``` php {skip-validation} hl_lines="34"
+``` php {skip-validation hl_lines="34"}
 --8<--
 code_samples/search/custom/src/EventSubscriber/CustomQueryFilterSubscriber.php
 --8<--

docs/search/search_api.md

@@ -27,7 +27,7 @@ For example, to search for all content of a selected content type, use one Crite
 
 The following command takes the content type identifier as an argument and lists all results:
 
-``` php {skip-validation} hl_lines="14 16"
+``` php {skip-validation hl_lines="14 16"}
 // ...
 [[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 5, 7) =]]
 // ...
@@ -132,7 +132,7 @@ It doesn't use the `SearchService` and isn't based on indexed data.
 
 For example, the following command lists all content items under the specified parent location and sorts them by name in descending order:
 
-``` php {skip-validation} hl_lines="15-18"
+``` php {skip-validation hl_lines="15-18"}
 // ...
 [[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 5, 9) =]]
 
@@ -143,7 +143,7 @@ For example, the following command lists all content items under the specified p
 
 The same Filter can be applied to find locations instead of content items, for example:
 
-``` php {skip-validation} hl_lines="20"
+``` php {skip-validation hl_lines="20"}
 // ...
 [[= include_code('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 5, 9) =]]
 
@@ -199,7 +199,7 @@ $filter
 You can use the `SearchService` or repository filtering in a controller, as long as you provide the required parameters.
 For example, in the code below, `locationId` is provided to list all children of a location by using the `SearchService`.
 
-``` php {skip-validation} hl_lines="22-24"
+``` php {skip-validation hl_lines="22-24"}
 // ...
 [[= include_code('code_samples/api/public_php_api/src/Controller/CustomController.php', 5, 12) =]]
     // ...
@@ -210,7 +210,7 @@ The rendering of results is then relegated to [templates](templates.md) (lines 2
 
 When using Repository filtering, provide the results of `ContentService::find()` as parameters to the view:
 
-``` php {skip-validation} hl_lines="19"
+``` php {skip-validation hl_lines="19"}
 // ...
 [[= include_code('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 5, 12) =]]
     // ...

docs/templating/layout/add_login_form.md

@@ -56,7 +56,7 @@ You can use a custom template for example to display information about password
 
 In case of more advanced template customization, you can use a subscriber, for example in `src/EventSubscriber/LoginFormViewSubscriber.php`:
 
-``` php {skip-validation} hl_lines="23 35 40 42"
+``` php {skip-validation hl_lines="23 35 40 42"}
 <?php
 
 declare(strict_types=1);

docs/tutorials/beginner_tutorial/5_display_a_list_of_content_items.md

@@ -57,7 +57,7 @@ For more information, see [Built-In Query Types](built-in_query_types.md).
 Here, you need to display `ride` objects that have been published (are visible).
 Create a `RideQueryType.php` file in `src/QueryType`:
 
-``` php {skip-validation} hl_lines="21 22"
+``` php {skip-validation hl_lines="21 22"}
 <?php
 
 namespace App\QueryType;