Skip to content

Detecting and fixing incorrect YAML samples#3165

Draft
mnocon wants to merge 6 commits into5.0from
test-yamls
Draft

Detecting and fixing incorrect YAML samples#3165
mnocon wants to merge 6 commits into5.0from
test-yamls

Conversation

@mnocon
Copy link
Copy Markdown
Contributor

@mnocon mnocon commented Apr 23, 2026

This PR allows us to test all the YAML code samples in the doc - both in the code_samples directory (.yaml files) and the ones embedded directly in Markdown (by extracting the ``` yaml code blocks).

There are two checks:

  • YAML syntax check - makes sure that YAML is valid
  • Bundle configuration check - ibexa, security, ibexa_migrations etc.

Not everything is checked - for example, Ibexa Migration files are not validated.

To run the tests, run:

composer update
composer phpunit

There's a baseline for samples that should be ignored - to put something in the baseline, run phpunit-update-baseline

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 23, 2026

Preview of modified files

Preview of modified Markdown:

@mnocon mnocon changed the title Added code for testing YAML samples Detecting and fixing incorrect YAML samples Apr 23, 2026
@@ -1,13 +0,0 @@
ibexa:
Copy link
Copy Markdown
Contributor Author

@mnocon mnocon Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not used - but it should be toolbar, not toolbars

security:
firewalls:
# ...
ibexa_cdp:
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was outdated - stolen from configuration provided when installing the project

# Raptor Recommendations API URL, optional, set by default
recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'
# Raptor Recommendations API URI, optional, set by default
recommendations_api_uri: '%ibexa.connector.raptor.recommendations.api_uri%'
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo!

http:
enabled: true
batch_size: 64
enabled: true
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sample had mixed tabs and spaces

@github-actions
Copy link
Copy Markdown

code_samples/ change report

Before (on target branch)After (in current PR)

code_samples/back_office/components/twig_components.yaml

docs/templating/components.md@96:``` yaml
docs/templating/components.md@97:[[= include_file('code_samples/back_office/components/twig_components.yaml') =]]
docs/templating/components.md@98:```

001⫶ibexa_twig_components:
002⫶ admin-ui-user-menu:
003⫶ custom-controller-component:
004⫶ type: controller
005⫶ arguments:
006⫶ controller: '\App\Controller\MyController::requestAction'
007⫶ parameters:
008⫶ parameter1: 'custom'
009⫶ parameter2: true
010⫶ custom-html-component:
011⫶ type: html
012⫶ priority: 0
013⫶ arguments:
014⫶ content: '<b>Hello world!</b>'

code_samples/back_office/components/twig_components.yaml

docs/templating/components.md@96:``` yaml
docs/templating/components.md@97:[[= include_file('code_samples/back_office/components/twig_components.yaml') =]]
docs/templating/components.md@98:```

001⫶ibexa_twig_components:
002⫶ admin-ui-user-menu:
003⫶ custom-controller-component:
004⫶ type: controller
005⫶ arguments:
006⫶ controller: '\App\Controller\MyController::requestAction'
007⫶ parameters:
008⫶ parameter1: 'custom'
009⫶ parameter2: true
010⫶ custom-html-component:
011⫶ type: html
012⫶ priority: 0
013⫶ arguments:
014⫶ content: '<b>Hello world!</b>'
015⫶    admin-ui-user-menu:
016⫶ duplicated_user_menu:
017⫶ type: menu
018⫶ arguments:
019⫶ name: ezplatform_admin_ui.menu.user
020⫶ template: '@ibexadesign/ui/menu/user.html.twig'
021⫶ depth: 1
022⫶ admin-ui-script-head:
023⫶ custom-script-component:
024⫶ type: script
025⫶ arguments:
026⫶ src: 'https://doc.ibexa.co/en/latest/js/custom.js'
027⫶ crossorigin: anonymous
028⫶ defer: false
029⫶ async: true
030⫶ integrity: sha384-Ewi2bBDtPbbu4/+fs8sIbBJ3zVl0LDOSznfhFR/JBK+SzggdRdX8XQKauWmI9HH2
031⫶ type: text/javascript
032⫶ admin-ui-stylesheet-head:
033⫶ custom-link-component:
034⫶ type: stylesheet
035⫶ arguments:
036⫶ href: 'https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback'
037⫶ rel: stylesheet
038⫶ crossorigin: anonymous
039⫶ integrity: sha384-LN/mLhO/GN6Ge8ZPvI7uRsZpiXmtSkep+aFlJcHa8by4TvA34o1am9sa88eUzKTD
040⫶ type: text/css
041⫶ admin-ui-global-search:
042⫶ custom-template-component:
043⫶ type: template
044⫶ priority: 50
045⫶ arguments:
046⫶ template: '@ibexadesign/ui/component/user_thumbnail/user_thumbnail.html.twig'
047⫶ parameters:
048⫶ user_content:
049⫶ name: "Thumbnail"
050⫶ thumbnail:
051⫶ resource: https://placecats.com/100/100
015⫶        duplicated_user_menu:
016⫶ type: menu
017⫶ arguments:
018⫶ name: ezplatform_admin_ui.menu.user
019⫶ template: '@ibexadesign/ui/menu/user.html.twig'
020⫶ depth: 1
021⫶ admin-ui-script-head:
022⫶ custom-script-component:
023⫶ type: script
024⫶ arguments:
025⫶ src: 'https://doc.ibexa.co/en/latest/js/custom.js'
026⫶ crossorigin: anonymous
027⫶ defer: false
028⫶ async: true
029⫶ integrity: sha384-Ewi2bBDtPbbu4/+fs8sIbBJ3zVl0LDOSznfhFR/JBK+SzggdRdX8XQKauWmI9HH2
030⫶ type: text/javascript
031⫶ admin-ui-stylesheet-head:
032⫶ custom-link-component:
033⫶ type: stylesheet
034⫶ arguments:
035⫶ href: 'https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback'
036⫶ rel: stylesheet
037⫶ crossorigin: anonymous
038⫶ integrity: sha384-LN/mLhO/GN6Ge8ZPvI7uRsZpiXmtSkep+aFlJcHa8by4TvA34o1am9sa88eUzKTD
039⫶ type: text/css
040⫶ admin-ui-global-search:
041⫶ custom-template-component:
042⫶ type: template
043⫶ priority: 50
044⫶ arguments:
045⫶ template: '@ibexadesign/ui/component/user_thumbnail/user_thumbnail.html.twig'
046⫶ parameters:
047⫶ user_content:
048⫶ name: "Thumbnail"
049⫶ thumbnail:
050⫶ resource: https://placecats.com/100/100


code_samples/back_office/online_editor/config/packages/custom_plugin.yaml


code_samples/front/shop/order-management/config/packages/ibexa.yaml

docs/commerce/order_management/configure_order_management.md@36:``` yaml
docs/commerce/order_management/configure_order_management.md@37:[[= include_file('code_samples/front/shop/order-management/config/packages/ibexa.yaml', 0, 66) =]]
docs/commerce/order_management/configure_order_management.md@38:```

001⫶framework:
002⫶ workflows:
003⫶ custom_order_workflow:
004⫶ type: state_machine
005⫶ audit_trail:
006⫶ enabled: "%kernel.debug%"
007⫶ marking_store:
008⫶ type: method
009⫶ property: status
010⫶ supports:
011⫶ - Ibexa\Contracts\OrderManagement\Workflow\WorkflowSubjectInterface
012⫶ initial_marking: created
013⫶ places:
014⫶ created:
015⫶ metadata:
016⫶ reduce_stock: true
017⫶ label: 'order.status.label.created'
018⫶ translation_domain: 'order_management'
019⫶ primary_color: '#F4B65F'
020⫶ secondary_color: '#FEEED9'
021⫶ verified:
022⫶ metadata:
023⫶ label: 'order.status.label.verified'
024⫶ translation_domain: 'order_management'
025⫶ primary_color: '#2B6875'
026⫶ secondary_color: '#CCDBDE'
027⫶ in_progress:
028⫶ metadata:
029⫶ label: 'order.status.label.in_progress'
030⫶ translation_domain: 'order_management'
031⫶ primary_color: '#FF9071'
032⫶ secondary_color: '#FFDACF'
033⫶ completed:
034⫶ metadata:
035⫶ label: 'order.status.label.completed'
036⫶ translation_domain: 'order_management'
037⫶ primary_color: '#33B655'
038⫶ secondary_color: '#E5F5E9'
039⫶ dropped:
040⫶ metadata:
041⫶ restore_stock: true
042⫶ label: 'order.status.label.dropped'
043⫶ translation_domain: 'order_management'
044⫶ primary_color: '#5A5A5D'
045⫶ secondary_color: '#E6E6ED'
046⫶ transitions:
047⫶ verify:
048⫶ from:
049⫶ - created
050⫶ to:
051⫶ - verified
052⫶ advance:
053⫶ from:
054⫶ - verified
055⫶ to:
056⫶ - in_progress
057⫶ finish:
058⫶ from:
059⫶ - in_progress
060⫶ to:
061⫶ - completed
062⫶ drop:
063⫶ from:
064⫶ - created
065⫶ to:
066⫶ - dropped

docs/commerce/order_management/configure_order_management.md@42:``` yaml
docs/commerce/order_management/configure_order_management.md@43:[[= include_file('code_samples/front/shop/order-management/config/packages/ibexa.yaml', 69, 74) =]]
docs/commerce/order_management/configure_order_management.md@44:```

001⫶ibexa:
002⫶ repositories:
003⫶ default:
004⫶ order_management:
005⫶ workflow: custom_order_workflow


code_samples/front/shop/payment/src/bundle/Resources/config/services/payment_method.yaml

docs/commerce/payment/payment_method_filtering.md@22:``` yaml
docs/commerce/payment/payment_method_filtering.md@23:[[= include_file('code_samples/front/shop/payment/src/bundle/Resources/config/services/payment_method.yaml', 0, 10) =]]
docs/commerce/payment/payment_method_filtering.md@24:```

001⫶services:
002⫶ app.payment.type.new_payment_method_type:
003⫶ class: Ibexa\Contracts\Payment\PaymentMethod\Type\TypeInterface
004⫶ factory: ['@Ibexa\Contracts\Payment\PaymentMethod\Type\TypeFactoryInterface', 'createType']
005⫶ arguments:
006⫶ $identifier: new_payment_method_type
007⫶ $name: New Payment Method Type
008⫶ $domain: <translation_domain>
009⫶ tags:
010⫶ - { name: ibexa.payment.payment_method.type, alias: new_payment_method_type }

docs/commerce/payment/payment_method_filtering.md@44:``` yaml
docs/commerce/payment/payment_method_filtering.md@45:[[= include_file('code_samples/front/shop/payment/src/bundle/Resources/config/services/payment_method.yaml', 11, 14) =]]
docs/commerce/payment/payment_method_filtering.md@46:```

001⫶ App\Payment\PaymentMethod\Voter\NewPaymentMethodTypeVoter:
002⫶ tags:
003⫶ - { name: ibexa.payment.payment_method.voter, type: new_payment_method_type }


code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml

docs/recommendations/raptor_integration/connector_installation_configuration.md@28:``` yaml
docs/recommendations/raptor_integration/connector_installation_configuration.md@29:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 0, 13) =]]
docs/recommendations/raptor_integration/connector_installation_configuration.md@30:```

001⫶ibexa:
002⫶ system:
003⫶ <scope>:
004⫶ connector_raptor:
005⫶ enabled: true


code_samples/back_office/online_editor/config/packages/custom_plugin.yaml


code_samples/front/shop/order-management/config/packages/ibexa.yaml

docs/commerce/order_management/configure_order_management.md@36:``` yaml
docs/commerce/order_management/configure_order_management.md@37:[[= include_file('code_samples/front/shop/order-management/config/packages/ibexa.yaml', 0, 66) =]]
docs/commerce/order_management/configure_order_management.md@38:```

001⫶framework:
002⫶ workflows:
003⫶ custom_order_workflow:
004⫶ type: state_machine
005⫶ audit_trail:
006⫶ enabled: "%kernel.debug%"
007⫶ marking_store:
008⫶ type: method
009⫶ property: status
010⫶ supports:
011⫶ - Ibexa\Contracts\OrderManagement\Workflow\WorkflowSubjectInterface
012⫶ initial_marking: created
013⫶ places:
014⫶ created:
015⫶ metadata:
016⫶ reduce_stock: true
017⫶ label: 'order.status.label.created'
018⫶ translation_domain: 'order_management'
019⫶ primary_color: '#F4B65F'
020⫶ secondary_color: '#FEEED9'
021⫶ verified:
022⫶ metadata:
023⫶ label: 'order.status.label.verified'
024⫶ translation_domain: 'order_management'
025⫶ primary_color: '#2B6875'
026⫶ secondary_color: '#CCDBDE'
027⫶ in_progress:
028⫶ metadata:
029⫶ label: 'order.status.label.in_progress'
030⫶ translation_domain: 'order_management'
031⫶ primary_color: '#FF9071'
032⫶ secondary_color: '#FFDACF'
033⫶ completed:
034⫶ metadata:
035⫶ label: 'order.status.label.completed'
036⫶ translation_domain: 'order_management'
037⫶ primary_color: '#33B655'
038⫶ secondary_color: '#E5F5E9'
039⫶ dropped:
040⫶ metadata:
041⫶ restore_stock: true
042⫶ label: 'order.status.label.dropped'
043⫶ translation_domain: 'order_management'
044⫶ primary_color: '#5A5A5D'
045⫶ secondary_color: '#E6E6ED'
046⫶ transitions:
047⫶ verify:
048⫶ from:
049⫶ - created
050⫶ to:
051⫶ - verified
052⫶ advance:
053⫶ from:
054⫶ - verified
055⫶ to:
056⫶ - in_progress
057⫶ finish:
058⫶ from:
059⫶ - in_progress
060⫶ to:
061⫶ - completed
062⫶ drop:
063⫶ from:
064⫶ - created
065⫶ to:
066⫶ - dropped

docs/commerce/order_management/configure_order_management.md@42:``` yaml
docs/commerce/order_management/configure_order_management.md@43:[[= include_file('code_samples/front/shop/order-management/config/packages/ibexa.yaml', 69, 74) =]]
docs/commerce/order_management/configure_order_management.md@44:```

001⫶ibexa:
002⫶ repositories:
003⫶ default:
004⫶ order_management:
005⫶ workflow: custom_order_workflow


code_samples/front/shop/payment/src/bundle/Resources/config/services/payment_method.yaml

docs/commerce/payment/payment_method_filtering.md@22:``` yaml
docs/commerce/payment/payment_method_filtering.md@23:[[= include_file('code_samples/front/shop/payment/src/bundle/Resources/config/services/payment_method.yaml', 0, 10) =]]
docs/commerce/payment/payment_method_filtering.md@24:```

001⫶services:
002⫶ app.payment.type.new_payment_method_type:
003⫶ class: Ibexa\Contracts\Payment\PaymentMethod\Type\TypeInterface
004⫶ factory: ['@Ibexa\Contracts\Payment\PaymentMethod\Type\TypeFactoryInterface', 'createType']
005⫶ arguments:
006⫶ $identifier: new_payment_method_type
007⫶ $name: New Payment Method Type
008⫶ $domain: <translation_domain>
009⫶ tags:
010⫶ - { name: ibexa.payment.payment_method.type, alias: new_payment_method_type }

docs/commerce/payment/payment_method_filtering.md@44:``` yaml
docs/commerce/payment/payment_method_filtering.md@45:[[= include_file('code_samples/front/shop/payment/src/bundle/Resources/config/services/payment_method.yaml', 11, 14) =]]
docs/commerce/payment/payment_method_filtering.md@46:```

001⫶ App\Payment\PaymentMethod\Voter\NewPaymentMethodTypeVoter:
002⫶ tags:
003⫶ - { name: ibexa.payment.payment_method.voter, type: new_payment_method_type }


code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml

docs/recommendations/raptor_integration/connector_installation_configuration.md@28:``` yaml
docs/recommendations/raptor_integration/connector_installation_configuration.md@29:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml', 0, 13) =]]
docs/recommendations/raptor_integration/connector_installation_configuration.md@30:```

001⫶ibexa:
002⫶ system:
003⫶ <scope>:
004⫶ connector_raptor:
005⫶ enabled: true
006⫶                customer_id:          ~ # Required
006⫶                customer_id:          "12345" # Required
007⫶                tracking_type:        client # One of: "client" or "server"
008⫶
009⫶ # Raptor Recommendations API key
007⫶                tracking_type:        client # One of: "client" or "server"
008⫶
009⫶ # Raptor Recommendations API key
010⫶                recommendations_api_key: ~ # Required
010⫶                recommendations_api_key: "your_api_key_here" # Required
011⫶
011⫶
012⫶                # Raptor Recommendations API URL, optional, set by default
013⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'
012⫶                # Raptor Recommendations API URI, optional, set by default
013⫶ recommendations_api_uri: '%ibexa.connector.raptor.recommendations.api_uri%'

docs/recommendations/raptor_integration/connector_installation_configuration.md@76:``` yaml hl_lines="14-17"
docs/recommendations/raptor_integration/connector_installation_configuration.md@77:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]]
docs/recommendations/raptor_integration/connector_installation_configuration.md@78:```

001⫶ibexa:
002⫶ system:
003⫶ <scope>:
004⫶ connector_raptor:
005⫶ enabled: true

docs/recommendations/raptor_integration/connector_installation_configuration.md@76:``` yaml hl_lines="14-17"
docs/recommendations/raptor_integration/connector_installation_configuration.md@77:[[= include_file('code_samples/recommendations/config/packages/ibexa_connector_raptor.yaml') =]]
docs/recommendations/raptor_integration/connector_installation_configuration.md@78:```

001⫶ibexa:
002⫶ system:
003⫶ <scope>:
004⫶ connector_raptor:
005⫶ enabled: true
006⫶                customer_id:          ~ # Required
006⫶                customer_id:          "12345" # Required
007⫶                tracking_type:        client # One of: "client" or "server"
008⫶
009⫶ # Raptor Recommendations API key
007⫶                tracking_type:        client # One of: "client" or "server"
008⫶
009⫶ # Raptor Recommendations API key
010⫶                recommendations_api_key: ~ # Required
010⫶                recommendations_api_key: "your_api_key_here" # Required
011⫶
011⫶
012⫶                # Raptor Recommendations API URL, optional, set by default
013⫶ recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'
012⫶                # Raptor Recommendations API URI, optional, set by default
013⫶ recommendations_api_uri: '%ibexa.connector.raptor.recommendations.api_uri%'
014❇️ibexa_connector_raptor:
015❇️ # When enabled, tracking exceptions are thrown instead of being silently handled
016❇️ strict_exceptions: true

014❇️ibexa_connector_raptor:
015❇️ # When enabled, tracking exceptions are thrown instead of being silently handled
016❇️ strict_exceptions: true

Download colorized diff

-
path: docs/users/user_authentication.md
line: 41
message: '~Unrecognized option "encoders" under "security"\. Available options are "access_control", "access_decision_manager", "access_denied_url", "erase_credentials", "expose_security_errors", "firewalls", "hide_user_not_found", "password_hashers", "providers", "role_hierarchy", "session_fixation_strategy"\.~'
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is valid (incorrect code sample), but I want to tackle this in a follow-up

@sonarqubecloud
Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
B Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

-
path: docs/release_notes/ez_platform_v2.4.md
line: 221
message: '~Unrecognized option "require_previous_session" under "security\.firewalls\.ezpublish_front\.form_login"\. Available options are "always_use_default_target_path", "check_path", "csrf_parameter", "csrf_token_id", "default_target_path", "enable_csrf", "failure_forward", "failure_handler", "failure_path", "failure_path_parameter", "form_only", "login_path", "password_parameter", "post_only", "provider", "remember_me", "success_handler", "target_path_parameter", "use_forward", "use_referer", "username_parameter"\.~'
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is valid (incorrect code sample), but I want to tackle this in a follow-up

Copy link
Copy Markdown
Contributor

@adriendupuis adriendupuis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I focused on everything not in docs/ dir for this first pass

content:
tree_root:
location_id: location_id_of_customer_portals_root_folder
location_id: 9999 # location_id_of_customer_portals_root_folder
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consistency with the changes above and below:

location_id_of_customer_portal = 9999
location_id_of_customer_portals_root_folder = 999

Suggested change
location_id: 9999 # location_id_of_customer_portals_root_folder
location_id: 999 # location_id_of_customer_portals_root_folder

run: |
curl -H "Authorization: token $TOKEN" -L https://github.com/ibexa/vale-styles/archive/refs/heads/main.zip -o vale.zip
rm -rf tests
unzip vale.zip
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep archive removal

Suggested change
unzip vale.zip
unzip vale.zip
rm vale.zip

Comment on lines +143 to +146
```yaml
--8<--
some/file.yaml
```
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to mimic the real syntax:

Suggested change
```yaml
--8<--
some/file.yaml
```
```yaml
--8<--
some/file.yaml
--8<--
```

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants