diff --git a/README.md b/README.md index 8bf8187c17..868ae6b876 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,25 @@ Regenerate the baseline by running: 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: diff --git a/docs/administration/back_office/browser/browser.md b/docs/administration/back_office/browser/browser.md index e574cab7ad..b006ff18c3 100644 --- a/docs/administration/back_office/browser/browser.md +++ b/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'; diff --git a/docs/multisite/languages/back_office_translations.md b/docs/multisite/languages/back_office_translations.md index c8f2d10332..3b1a05680a 100644 --- a/docs/multisite/languages/back_office_translations.md +++ b/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; diff --git a/docs/product_catalog/quable/quable_api.md b/docs/product_catalog/quable/quable_api.md index a6891ceb74..586c8b5f43 100644 --- a/docs/product_catalog/quable/quable_api.md +++ b/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) =]] ``` diff --git a/docs/search/criteria_reference/ancestor_criterion.md b/docs/search/criteria_reference/ancestor_criterion.md index d8d6854443..5dca5b8d46 100644 --- a/docs/search/criteria_reference/ancestor_criterion.md +++ b/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]); diff --git a/docs/search/criteria_reference/contenttypegroupid_criterion.md b/docs/search/criteria_reference/contenttypegroupid_criterion.md index 62534ef5bc..09c216b92d 100644 --- a/docs/search/criteria_reference/contenttypegroupid_criterion.md +++ b/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); diff --git a/docs/search/criteria_reference/datemetadata_criterion.md b/docs/search/criteria_reference/datemetadata_criterion.md index 587ab4342b..92f39d711e 100644 --- a/docs/search/criteria_reference/datemetadata_criterion.md +++ b/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([ diff --git a/docs/search/criteria_reference/field_criterion.md b/docs/search/criteria_reference/field_criterion.md index 6e4d7ff79f..efc6f727bf 100644 --- a/docs/search/criteria_reference/field_criterion.md +++ b/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'), diff --git a/docs/search/criteria_reference/isfieldempty_criterion.md b/docs/search/criteria_reference/isfieldempty_criterion.md index 17203ebc4a..d0d30af98a 100644 --- a/docs/search/criteria_reference/isfieldempty_criterion.md +++ b/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'), diff --git a/docs/search/criteria_reference/languagecode_criterion.md b/docs/search/criteria_reference/languagecode_criterion.md index fd44222e9d..27baf898e3 100644 --- a/docs/search/criteria_reference/languagecode_criterion.md +++ b/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'), diff --git a/docs/search/criteria_reference/parentlocationid_criterion.md b/docs/search/criteria_reference/parentlocationid_criterion.md index ebc087a61f..057143b5ae 100644 --- a/docs/search/criteria_reference/parentlocationid_criterion.md +++ b/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), diff --git a/docs/search/criteria_reference/usermetadata_criterion.md b/docs/search/criteria_reference/usermetadata_criterion.md index 61c8fdd236..08608746c9 100644 --- a/docs/search/criteria_reference/usermetadata_criterion.md +++ b/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; diff --git a/docs/search/extensibility/index_custom_elasticsearch_data.md b/docs/search/extensibility/index_custom_elasticsearch_data.md index fae2c8442f..4263639cfc 100644 --- a/docs/search/extensibility/index_custom_elasticsearch_data.md +++ b/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<-- diff --git a/docs/search/extensibility/manipulate_elasticsearch_query.md b/docs/search/extensibility/manipulate_elasticsearch_query.md index 06df646272..8f6da29118 100644 --- a/docs/search/extensibility/manipulate_elasticsearch_query.md +++ b/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<-- diff --git a/docs/search/search_api.md b/docs/search/search_api.md index 498e040df8..dc986ec57a 100644 --- a/docs/search/search_api.md +++ b/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) =]] // ... diff --git a/docs/templating/layout/add_login_form.md b/docs/templating/layout/add_login_form.md index 0195badcff..d50de16709 100644 --- a/docs/templating/layout/add_login_form.md +++ b/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"}