Test and fix embedded PHP snippets

.gitignore

@@ -13,3 +13,4 @@ yarn.lock
 docs/css/*.map
 .deptrac.cache
 .phpunit.result.cache
+code_samples/_inline_php/

composer.json

@@ -101,18 +101,18 @@
         "ibexa/fastly": "~5.0.x-dev"
     },
     "scripts": {
-        "fix-cs": "php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots",
+        "fix-cs": "php tools/extract-inline-php.php && php-cs-fixer fix --config=.php-cs-fixer.php -v --show-progress=dots",
         "check-cs": "@fix-cs --dry-run",
-        "phpstan": "phpstan analyse",
-        "deptrac": "deptrac analyse",
-        "check-rector": "rector process --dry-run --ansi",
+        "phpstan": "php tools/extract-inline-php.php && phpstan analyse",
+        "deptrac": "php tools/extract-inline-php.php && deptrac analyse",
+        "check-rector": "php tools/extract-inline-php.php && rector process --dry-run --ansi",
         "phpunit": "phpunit",
         "phpunit-update-baseline": "php tests/generate-yaml-baseline.php"
     },
     "scripts-descriptions": {
         "fix-cs": "Automatically fixes code style in all files",
         "check-cs": "Run code style checker for all files",
-        "phpstan": "Run static code analysis",
+        "phpstan": "Run static code analysis (extracts inline PHP snippets from docs/ first)",
         "deptrac": "Run Deptrac architecture testing",
         "check-rector": "Check for code refactoring opportunities",
         "phpunit": "Run PHPUnit tests (YAML validation)",

docs/administration/back_office/back_office_elements/formatting_date_and_time.md

@@ -40,7 +40,7 @@ class MyService
         // your code
     }
 
-    public function foo()
+    public function foo(): void
     {
         // your code
 

docs/administration/back_office/back_office_menus/back_office_menus.md

@@ -86,6 +86,7 @@ The following method adds a new menu section under **Content**, and under it, a
 You can also pass parameters to templates used to render menu items with `template_parameters`:
 
 ``` php
+/** @var \Knp\Menu\ItemInterface $menu */
 $menu->addChild(
     'all_content_list',
     [
@@ -106,6 +107,7 @@ You can then use the variable `custom_parameter` in `templates/themes/admin/list
 To have translatable labels, use `translation.key` from the `messages` domain:
 
 ``` php
+/** @var \Knp\Menu\ItemInterface $menu */
 $menu->addChild(
     'all_content_list',
     [

docs/administration/back_office/browser/browser.md

@@ -147,26 +147,28 @@ 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 hl_lines="29 30 31"
+<?php
+
+use Ibexa\AdminUi\UniversalDiscovery\Event\ConfigResolveEvent;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
 class JohnDoeCanSelectMore implements EventSubscriberInterface
 {
     private const CONFIGURATION_NAME = 'my_custom_udw';
 
     /**
      * Returns an array of event names this subscriber wants to listen to.
      *
-     * @return array The event names to listen to
+     * @return array<string, string> The event names to listen to
      */
-    public static function getSubscribedEvents()
+    public static function getSubscribedEvents(): array
     {
         return [
             ConfigResolveEvent::NAME => 'onUdwConfigResolve',
         ];
     }
 
-    /**
-     * @param \Ibexa\AdminUi\UniversalDiscovery\Event $event
-     */
-    public function onUdwConfigResolve(ConfigResolveEvent $event)
+    public function onUdwConfigResolve(ConfigResolveEvent $event): void
     {
         if ($event->getConfigName() !== self::CONFIGURATION_NAME) {
 		    return;

docs/administration/back_office/customize_calendar.md

@@ -81,10 +81,15 @@ To add an in-memory collection as an event source, create `src/Calendar/Holidays
     For example:
 
     ``` php
+    use Ibexa\Contracts\Calendar\EventCollection;
+    use Ibexa\Contracts\Calendar\EventInterface;
+
+    /** @var \App\Calendar\Holidays\EventSourceFactory $this */
     $collection = new EventCollection([
-        $this->createEvent("Event 1", new DateTime("2024-01-01")),
-        $this->createEvent("Event 2", new DateTime("2024-01-02")),
+        $this->createEvent("Event 1", new DateTime("2024-01-01")), // @phpstan-ignore method.private
+        $this->createEvent("Event 2", new DateTime("2024-01-02")), // @phpstan-ignore method.private
         // ...
+    ]);
     ```
 
 Next, register the event source as a service:

docs/administration/back_office/notifications.md

@@ -27,7 +27,8 @@ There are four types of notifications: `info`, `success`, `warning` and `error`.
 To send a notification from PHP, inject the `TranslatableNotificationHandlerInterface` into your class.
 
 ``` php
-$this->notificationHandler->info(
+/** @var \Ibexa\Contracts\AdminUi\Notification\TranslatableNotificationHandlerInterface $notificationHandler */
+$notificationHandler->info(
     /** @Desc("Notification text") */
     'example.notification.text',
     [],

docs/administration/configuration/configuration.md

@@ -74,7 +74,8 @@ parameters:
 
 ``` php
 // Usage inside a controller
-$myParameter = $this->container->getParameter( 'myapp.parameter.name' );
+/** @var \Symfony\Component\DependencyInjection\ContainerInterface $container */
+$myParameter = $container->getParameter( 'myapp.parameter.name' );
 ```
 
 ## Configuration settings

docs/administration/configuration/dynamic_configuration.md

@@ -29,9 +29,9 @@ parameters:
 
 Inside a controller, in `site_group` SiteAccess, you can use the parameters in the following way (the same applies for `hasParameter()`):
 
-``` php
+``` php skip-validation
 $configResolver = $this->getConfigResolver();
- 
+
 // ibexa.site_access.config is the default namespace, so no need to specify it
 // The following will resolve ibexa.site_access.config.<siteaccessName>.content.default_ttl
 // In the case of site_group, it will return 3600.
@@ -81,20 +81,20 @@ For more information about dependency injection, see [Service container](php_api
 namespace App;
 
 use Ibexa\Contracts\Core\SiteAccess\ConfigResolverInterface;
- 
+
 class Service
 {
-    /**
+    /**
      * @var \Ibexa\Contracts\Core\SiteAccess\ConfigResolverInterface
      */
     private $configResolver;
- 
-    public function __construct( ConfigResolverInterface $configResolver )
+
+    public function __construct(ConfigResolverInterface $configResolver)
     {
         $this->configResolver = $configResolver;
     }
 
-    public function someMethodThatNeedConfig()
+    public function someMethodThatNeedConfig(): void
     {
         $configValue = $this->configResolver->getParameter('my_param', 'myapp');
     }

docs/administration/configuration/repository_configuration.md

@@ -327,6 +327,9 @@ final class CustomRepositoryConfigParser implements RepositoryConfigParserInterf
 You need to register this configuration extension in the following way:
 
 ``` php
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\HttpKernel\Bundle\Bundle;
+
 final class AcmeFeatureBundle extends Bundle
 {
     public function build(ContainerBuilder $container): void
@@ -343,5 +346,7 @@ final class AcmeFeatureBundle extends Bundle
 To access the configuration settings, use the `Ibexa\Bundle\Core\ApiLoader\RepositoryConfigurationProvider::getRepositoryConfig` method:
 
 ``` php
+/** @var \Ibexa\Bundle\Core\ApiLoader\RepositoryConfigurationProvider $repositoryConfigProvider */
+/** @phpstan-ignore-next-line */
 $acmeConfig = $repositoryConfigProvider->getRepositoryConfig()['acme'];
 ```

docs/ai_actions/configure_ai_actions.md

@@ -92,7 +92,10 @@ composer require ibexa/connector-gemini
 Then, you **must** add the bundle to the list in `config/bundles.php` manually:
 
 ``` php
+return [
+    // ...
     Ibexa\Bundle\ConnectorGemini\IbexaConnectorGeminiBundle::class => ['all' => true],
+];
 ```
 
 This command adds the feature code, including basic handlers that let you refine text or generate alternative text for images.

docs/api/graphql/graphql_custom_ft.md

@@ -78,7 +78,7 @@
 When a mapper method is decorated, you need to call the decorated service method for unsupported types.
 To do that, you need to replace `mapXXX` by the method it's in:
 
-```php
+```php skip-validation
         if (!$this->canMap($fieldDefinition)) {
              return parent::mapToFieldValueType($fieldDefinition);
          }
@@ -88,7 +88,7 @@
 
 The [`RelationFieldDefinitionMapper`](https://github.com/ibexa/graphql/blob/main/src/lib/Schema/Domain/Content/Mapper/FieldDefinition/RelationFieldDefinitionMapper.php) example:
 
-```php hl_lines="14"
+```php hl_lines="14" skip-validation
 class RelationFieldDefinitionMapper extends DecoratingFieldDefinitionMapper implements FieldDefinitionMapper
 {
     public function mapToFieldValueType(FieldDefinition $fieldDefinition): ?string
@@ -149,7 +149,7 @@
 
 Example of a `MyCustomFieldDefinitionMapper` mapper for a complex field type:
 
-```php
+```php skip-validation
 class MyFieldDefinitionMapper extends DecoratingFieldDefinitionMapper implements FieldDefinitionMapper
 {
     public function mapToFieldValueInputType(ContentType contentType, FieldDefinition fieldDefinition): ?string
@@ -172,4 +172,4 @@
 - `location` is the content item's resolved location. For more information, see [Querying Locations](graphql_queries.md#querying-locations)
 - `item` is the content together with its location `\Ibexa\GraphQL\Value\Item`
 
-`RelationFieldValueBuilder` or `SelectionFieldValueBuilder` can be used as examples.
+`RelationFieldValueBuilder` or `SelectionFieldValueBuilder` can be used as examples.

docs/api/php_api/php_api.md

@@ -110,10 +110,13 @@ For example, to [hide a Location](managing_content.md#hiding-and-revealing-locat
 
 ``` php
 use Ibexa\Contracts\Core\Repository\Repository;
+use Ibexa\Contracts\Core\Repository\Values\Content\Location;
 
 //...
 
-$hiddenLocation = $repository->sudo(function (Repository $repository) use ($location) {
+/** @var Repository $repository */
+/** @var Location $location */
+$hiddenLocation = $repository->sudo(function (Repository $repository) use ($location): Location {
     return $repository->getLocationService()->hideLocation($location);
 });
 ```
@@ -150,9 +153,9 @@ Both cases should be covered with error messages:
 ``` php
 try {
     // ...
-} catch (\Ibexa\Contracts\Core\Repository\Exceptions\NotFoundException $e) {
+} catch (\Ibexa\Contracts\Core\Repository\Exceptions\NotFoundException $e) { // @phpstan-ignore catch.neverThrown
     $output->writeln("<error>No content with id $contentId found</error>");
-} catch (\Ibexa\Contracts\Core\Repository\Exceptions\UnauthorizedException $e) {
+} catch (\Ibexa\Contracts\Core\Repository\Exceptions\UnauthorizedException $e) { // @phpstan-ignore catch.neverThrown
     $output->writeln("<error>Permission denied on content with id $contentId</error>");
 }
 ```

docs/api/rest_api/extending_rest_api/creating_new_rest_resource.md

@@ -69,8 +69,12 @@ If the returned value was depending on a location, it could have been wrapped in
 `CachedValue` is used in the following way:
 
 ```php
+use Ibexa\Rest\Server\Values\CachedValue;
+
+/** @var array<string, mixed> $args */
+/** @var int $locationId */
 return new CachedValue(
-    new MyValue($args…),
+    new MyValue($args), // @phpstan-ignore class.notFound
     ['locationId'=> $locationId]
 );
 ```

docs/commerce/cart/cart_api.md

@@ -69,6 +69,9 @@ use Ibexa\Contracts\Cart\Value\CartMetadataUpdateStruct;
 
 // ...
 
+/** @var \Ibexa\Contracts\Core\Repository\UserService $userService */
+/** @var \Ibexa\Contracts\Cart\CartServiceInterface $cartService */
+/** @var \Ibexa\Contracts\Cart\Value\CartInterface $cart */
 $updateMetadataStruct = new CartMetadataUpdateStruct();
 $updateMetadataStruct->setOwner($userService->loadUserByLogin('user'));
 
@@ -151,7 +154,13 @@ It can include any relevant information that you want to associate with a partic
 To add context data to a cart, follow this example:
 
 ```php
-$createStruct = new CartCreateStruct(...);
+use Ibexa\Contracts\Cart\Value\CartCreateStruct;
+use Ibexa\Contracts\Core\Collection\ArrayMap;
+use Ibexa\Contracts\ProductCatalog\Values\CurrencyInterface;
+
+/** @var \Ibexa\Contracts\Cart\CartServiceInterface $cartService */
+/** @var CurrencyInterface $currency */
+$createStruct = new CartCreateStruct('My Cart', $currency);
 $createStruct->setContext(new ArrayMap([
     'coupon_code' => 'X1MF7699',
 ]));
@@ -167,7 +176,14 @@ You also add "X1MF7699" coupon code as context data to the cart.
 To attach context data to a cart entry, proceed as follows:
 
 ```php
-$entryAddStruct = new EntryAddStruct(...);
+use Ibexa\Contracts\Cart\Value\EntryAddStruct;
+use Ibexa\Contracts\Core\Collection\ArrayMap;
+use Ibexa\Contracts\ProductCatalog\Values\ProductInterface;
+
+/** @var \Ibexa\Contracts\Cart\CartServiceInterface $cartService */
+/** @var \Ibexa\Contracts\Cart\Value\CartInterface $cart */
+/** @var ProductInterface $product */
+$entryAddStruct = new EntryAddStruct($product); // @phpstan-ignore argument.type
 $entryAddStruct->setContext(new ArrayMap([
     'tshirt_text' => 'EqEqEqEq',
 ]));

docs/commerce/shopping_list/install_shopping_list.md

@@ -18,7 +18,10 @@
 
 Check that the following line has been added by the recipe to `config/bundles.php` file's array:
 ```php
+return [
+    // ...
     Ibexa\Bundle\ShoppingList\IbexaShoppingListBundle::class => ['all' => true],
+];  
 ```
 
 And that you have a `config/routes/ibexa_shopping_list.yaml` file configuring the following routes:

docs/commerce/shopping_list/shopping_list_api.md

@@ -41,7 +41,11 @@ and with sort clauses from the [`SortClause` namespace](/api/php_api/php_api_ref
 To get all shopping lists (of the current user or of the whole repository depending on the current user limitation), use the search method without criterion:
 
 ```php
-$lists = $this->shoppingListService->findShoppingLists(new ShoppingListQuery());
+use Ibexa\Contracts\ShoppingList\ShoppingListServiceInterface;
+use Ibexa\Contracts\ShoppingList\Value\ShoppingListQuery;
+
+/** @var ShoppingListServiceInterface $shoppingListService */
+$lists = $shoppingListService->findShoppingLists(new ShoppingListQuery());
 ```
 
 For more information about the shopping list search,
@@ -57,11 +61,16 @@ In the following example, if some assignments (`$list =`) are removed, the dumpe
 If only the middle assignment is removed, the last dumped variable contains the up-to-date shopping list.
 
 ```php
-$list = $this->shoppingListService->getOrCreateDefaultShoppingList();
+use Ibexa\Contracts\ShoppingList\ShoppingListServiceInterface;
+use Ibexa\Contracts\ShoppingList\Value\EntryAddStruct;
+
+/** @var ShoppingListServiceInterface $shoppingListService */
+/** @var string $productCode */
+$list = $shoppingListService->getOrCreateDefaultShoppingList();
 dump($list);
-$list = $this->shoppingListService->clearShoppingList($list);
+$list = $shoppingListService->clearShoppingList($list);
 dump($list);
-$list = $this->shoppingListService->addEntries($list, [new EntryAddStruct($productCode)]);
+$list = $shoppingListService->addEntries($list, [new EntryAddStruct($productCode)]);
 dump($list);
 ```
 When adding array of entries with `ShoppingListService::addEntries()`,

docs/commerce/storefront/extend_storefront.md

@@ -100,6 +100,12 @@ Define your own logic in a custom controller.
 Refer to the code snippet below and create your own file, for example, `CustomProductRenderController.php`:
 
 ``` php
+use Ibexa\Contracts\ProductCatalog\Values\ProductInterface;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Response;
+
+class CustomProductRenderController extends AbstractController
+{
     public function renderAction(ProductInterface $product): Response
     {
         return $this->render('@ibexadesign/storefront/product_card.html.twig', [
@@ -109,4 +115,5 @@ Refer to the code snippet below and create your own file, for example, `CustomPr
             'is_relative' => true,
         ]);
     }
+}
 ```

docs/commerce/transactional_emails/extend_transactional_emails.md

@@ -102,8 +102,9 @@ final class TransactionalMailFactoryEventSubscriber implements EventSubscriberIn
     {
         $recipient = $event->getRecipient();
         $profile = $event->getProfile();
+        // @phpstan-ignore-next-line
       	$user = $recipient->getUser();
-				
+
       	// Provide additional data if your profile has more attributes:
         $attributes = $profile->getAttributes();
         $attributes[] = new Attribute('name', $user->getName());
@@ -120,8 +121,8 @@ final class TransactionalMailFactoryEventSubscriber implements EventSubscriberIn
         $profile->setSegmentations($segmentations);
 
         // Use the same mechanism to pass other profile data
-        $profile->setSubscriptions(...);
-        $profile->setDataCollection(...);
+        // $profile->setSubscriptions($subscriptions);
+        // $profile->setDataCollection($dataCollection);
     }
 }
 ```