NEXT-18821 - Add generated HookReference & ServicesReference document…

…ation

.gitlab/stages/02-unit.yml

@@ -98,7 +98,7 @@ PHP coverage:
             cobertura: cobertura.xml
     parallel:
         matrix:
-            - TESTSUITE: ["framework", "checkout", "storefront,administration,system,elasticsearch,profiling,maintenance", "migration"]
+            - TESTSUITE: ["framework", "checkout", "storefront,administration,system,elasticsearch,profiling,maintenance,docs", "migration"]
             - TESTSUITE: "content"
               RUNNER_INSTANCE_TYPE: m5.large
 

composer.json

@@ -151,6 +151,7 @@
         "mbezhanov/faker-provider-collection": "~2.0.1",
         "nikic/php-parser": "~4.10.4",
         "opis/json-schema": "~1.0.19",
+        "phpdocumentor/reflection-docblock": "^5.3.0",
         "phpstan/extension-installer": "^1.1.0",
         "phpstan/phpstan": "0.12.90",
         "phpstan/phpstan-doctrine": "0.12.39",
@@ -195,7 +196,7 @@
             "@npm:storefront clean-install"
         ],
         "setup": [
-            "@composer install",
+            "@composer install -o",
             "@composer install -d src/Recovery",
             "mkdir -p config/jwt || true",
             "mkdir -p custom/plugins || true",

ecs.php

@@ -16,6 +16,8 @@
 use PhpCsFixer\Fixer\Operator\OperatorLinebreakFixer;
 use PhpCsFixer\Fixer\Phpdoc\GeneralPhpdocAnnotationRemoveFixer;
 use PhpCsFixer\Fixer\Phpdoc\NoSuperfluousPhpdocTagsFixer;
+use PhpCsFixer\Fixer\Phpdoc\PhpdocAlignFixer;
+use PhpCsFixer\Fixer\Phpdoc\PhpdocAnnotationWithoutDotFixer;
 use PhpCsFixer\Fixer\Phpdoc\PhpdocIndentFixer;
 use PhpCsFixer\Fixer\Phpdoc\PhpdocLineSpanFixer;
 use PhpCsFixer\Fixer\Phpdoc\PhpdocOrderFixer;
@@ -122,6 +124,8 @@
         StandaloneLineInMultilineArrayFixer::class => null,
         AssignmentInConditionSniff::class => null,
         PhpdocToCommentFixer::class => null,
+        PhpdocAlignFixer::class => null,
+        PhpdocAnnotationWithoutDotFixer::class => null,
         // would otherwise destroy the example in the annotation
         NoUselessCommentFixer::class => ['src/Core/System/Annotation/Concept/DeprecationPattern/ReplaceDecoratedInterface.php'],
         // Would otherwise fix the blocking whitespace in the currency formatter tests

src/Core/Checkout/Cart/Hook/CartHook.php

@@ -8,10 +8,16 @@
 use Shopware\Core\System\SalesChannel\SalesChannelContext;
 
 /**
+ * Triggered during the cart calculation process.
+ *
+ * @hook-use-case cart_manipulation
+ *
  * @internal (flag:FEATURE_NEXT_17441)
  */
 class CartHook extends Hook implements CartAware
 {
+    public const HOOK_NAME = 'cart';
+
     private Cart $cart;
 
     private SalesChannelContext $salesChannelContext;
@@ -31,7 +37,7 @@ public function getCart(): Cart
         return $this->cart;
     }
 
-    public function getServiceIds(): array
+    public static function getServiceIds(): array
     {
         return [
             CartFacadeHookFactory::class,
@@ -40,7 +46,7 @@ public function getServiceIds(): array
 
     public function getName(): string
     {
-        return 'cart';
+        return self::HOOK_NAME;
     }
 
     public function getSalesChannelContext(): SalesChannelContext

src/Core/Checkout/Test/Cart/Facade/CartTestHook.php

@@ -17,7 +17,7 @@ class CartTestHook extends Hook implements CartAware
 
     private string $name;
 
-    private array $serviceIds;
+    private static array $serviceIds;
 
     private Cart $cart;
 
@@ -26,7 +26,7 @@ public function __construct(string $name, Cart $cart, SalesChannelContext $conte
         parent::__construct($context->getContext());
         $this->salesChannelContext = $context;
         $this->name = $name;
-        $this->serviceIds = $serviceIds;
+        static::$serviceIds = $serviceIds;
         $this->cart = $cart;
 
         foreach ($data as $key => $value) {
@@ -39,9 +39,9 @@ public function getCart(): Cart
         return $this->cart;
     }
 
-    public function getServiceIds(): array
+    public static function getServiceIds(): array
     {
-        return $this->serviceIds;
+        return static::$serviceIds;
     }
 
     public function getName(): string

src/Core/Framework/DataAbstractionLayer/Facade/RepositoryFacade.php

@@ -12,6 +12,12 @@
 use Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult;
 use Shopware\Core\Framework\DataAbstractionLayer\Search\RequestCriteriaBuilder;
 
+/**
+ * The `repository` service allows you to query data, that is stored inside shopware.
+ * Keep in mind that your app needs to have the correct permissions for the data it queries through this service.
+ *
+ * @script-service data_loading
+ */
 class RepositoryFacade
 {
     private DefinitionInstanceRegistry $registry;
@@ -34,6 +40,14 @@ public function __construct(
         $this->context = $context;
     }
 
+    /**
+     * The `search()` method allows you to search for Entities that match a given criteria.
+     *
+     * @param string $entityName The name of the Entity you want to search for, e.g. `product` or `media`.
+     * @param array $criteria The criteria used for your search.
+     *
+     * @return EntitySearchResult A `EntitySearchResult` including all entities that matched your criteria.
+     */
     public function search(string $entityName, array $criteria): EntitySearchResult
     {
         $criteriaObject = $this->prepareCriteria($entityName, $criteria);
@@ -43,6 +57,14 @@ public function search(string $entityName, array $criteria): EntitySearchResult
         return $repository->search($criteriaObject, $this->context);
     }
 
+    /**
+     * The `ids()` method allows you to search for the Ids of Entities that match a given criteria.
+     *
+     * @param string $entityName The name of the Entity you want to search for, e.g. `product` or `media`.
+     * @param array $criteria The criteria used for your search.
+     *
+     * @return IdSearchResult A `IdSearchResult` including all entity-ids that matched your criteria.
+     */
     public function ids(string $entityName, array $criteria): IdSearchResult
     {
         $criteriaObject = $this->prepareCriteria($entityName, $criteria);
@@ -52,6 +74,14 @@ public function ids(string $entityName, array $criteria): IdSearchResult
         return $repository->searchIds($criteriaObject, $this->context);
     }
 
+    /**
+     * The `aggregate()` method allows you to execute aggregations specified in the given criteria.
+     *
+     * @param string $entityName The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
+     * @param array $criteria The criteria that define your aggregations.
+     *
+     * @return AggregationResultCollection A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.
+     */
     public function aggregate(string $entityName, array $criteria): AggregationResultCollection
     {
         $criteriaObject = $this->prepareCriteria($entityName, $criteria);

src/Core/Framework/DataAbstractionLayer/Facade/SalesChannelRepositoryFacade.php

@@ -10,6 +10,16 @@
 use Shopware\Core\System\SalesChannel\Entity\SalesChannelDefinitionInstanceRegistry;
 use Shopware\Core\System\SalesChannel\SalesChannelContext;
 
+/**
+ * The `store` service can be used to access publicly available `store-api` data.
+ * As the data is publicly available your app does not need any additional permissions to use this service,
+ * however querying data and also loading associations is restricted to the entities that are also available through the `store-api`.
+ *
+ * Notice that the returned entities are already processed for the storefront,
+ * this means that e.g. product prices are already calculated based on the current context.
+ *
+ * @script-service data_loading
+ */
 class SalesChannelRepositoryFacade
 {
     private SalesChannelDefinitionInstanceRegistry $registry;
@@ -28,6 +38,14 @@ public function __construct(
         $this->context = $context;
     }
 
+    /**
+     * The `search()` method allows you to search for Entities that match a given criteria.
+     *
+     * @param string $entityName The name of the Entity you want to search for, e.g. `product` or `media`.
+     * @param array $criteria The criteria used for your search.
+     *
+     * @return EntitySearchResult A `EntitySearchResult` including all entities that matched your criteria.
+     */
     public function search(string $entityName, array $criteria): EntitySearchResult
     {
         $criteriaObject = $this->prepareCriteria($entityName, $criteria);
@@ -37,6 +55,14 @@ public function search(string $entityName, array $criteria): EntitySearchResult
         return $repository->search($criteriaObject, $this->context);
     }
 
+    /**
+     * The `ids()` method allows you to search for the Ids of Entities that match a given criteria.
+     *
+     * @param string $entityName The name of the Entity you want to search for, e.g. `product` or `media`.
+     * @param array $criteria The criteria used for your search.
+     *
+     * @return IdSearchResult A `IdSearchResult` including all entity-ids that matched your criteria.
+     */
     public function ids(string $entityName, array $criteria): IdSearchResult
     {
         $criteriaObject = $this->prepareCriteria($entityName, $criteria);
@@ -46,6 +72,14 @@ public function ids(string $entityName, array $criteria): IdSearchResult
         return $repository->searchIds($criteriaObject, $this->context);
     }
 
+    /**
+     * The `aggregate()` method allows you to execute aggregations specified in the given criteria.
+     *
+     * @param string $entityName The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
+     * @param array $criteria The criteria that define your aggregations.
+     *
+     * @return AggregationResultCollection A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.
+     */
     public function aggregate(string $entityName, array $criteria): AggregationResultCollection
     {
         $criteriaObject = $this->prepareCriteria($entityName, $criteria);

src/Core/Framework/Script/Execution/Hook.php

@@ -20,7 +20,7 @@ public function __construct(Context $context)
      * The services returned here must all implement the HookAwareService interface.
      * These are then available in the script under the variable `services`.
      */
-    abstract public function getServiceIds(): array;
+    abstract public static function getServiceIds(): array;
 
     /**
      * The name returned here serves as an accessor in the script for the service.

src/Core/Framework/Script/ServiceStubs.php

@@ -2,21 +2,16 @@
 
 namespace Shopware\Core\Framework\Script;
 
-use Shopware\Core\Checkout\Cart\Facade\CartFacade;
-use Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryFacade;
-use Shopware\Core\Framework\DataAbstractionLayer\Facade\SalesChannelRepositoryFacade;
-use Shopware\Core\System\SystemConfig\Facade\SystemConfigFacade;
-
 /**
  * This class is intended for auto completion in twig templates. So the developer can
  * set a doc block to get auto completion for all services.
  *
  * @example: {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
  *
- * @method CartFacade                   cart()
- * @method RepositoryFacade             repository()
- * @method SystemConfigFacade           config()
- * @method SalesChannelRepositoryFacade store()
+ * @method \Shopware\Core\Checkout\Cart\Facade\CartFacade                                    cart()
+ * @method \Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryFacade             repository()
+ * @method \Shopware\Core\System\SystemConfig\Facade\SystemConfigFacade                      config()
+ * @method \Shopware\Core\Framework\DataAbstractionLayer\Facade\SalesChannelRepositoryFacade store()
  */
 abstract class ServiceStubs
 {

src/Core/Framework/Test/Script/Execution/SalesChannelTestHook.php

@@ -16,23 +16,23 @@ class SalesChannelTestHook extends Hook implements SalesChannelContextAware
 
     private string $name;
 
-    private array $serviceIds;
+    private static array $serviceIds;
 
     public function __construct(string $name, SalesChannelContext $context, array $data = [], array $serviceIds = [])
     {
         parent::__construct($context->getContext());
         $this->salesChannelContext = $context;
         $this->name = $name;
-        $this->serviceIds = $serviceIds;
+        self::$serviceIds = $serviceIds;
 
         foreach ($data as $key => $value) {
             $this->$key = $value;
         }
     }
 
-    public function getServiceIds(): array
+    public static function getServiceIds(): array
     {
-        return $this->serviceIds;
+        return self::$serviceIds;
     }
 
     public function getName(): string

src/Core/Framework/Test/Script/Execution/TestHook.php

@@ -12,22 +12,22 @@ class TestHook extends Hook
 {
     private string $name;
 
-    private array $serviceIds;
+    private static array $serviceIds;
 
     public function __construct(string $name, Context $context, array $data = [], array $serviceIds = [])
     {
         parent::__construct($context);
         $this->name = $name;
-        $this->serviceIds = $serviceIds;
+        self::$serviceIds = $serviceIds;
 
         foreach ($data as $key => $value) {
             $this->$key = $value;
         }
     }
 
-    public function getServiceIds(): array
+    public static function getServiceIds(): array
     {
-        return $this->serviceIds;
+        return self::$serviceIds;
     }
 
     public function getName(): string

src/Core/System/SystemConfig/Facade/SystemConfigFacade.php

@@ -7,6 +7,11 @@
 use Shopware\Core\Framework\Uuid\Uuid;
 use Shopware\Core\System\SystemConfig\SystemConfigService;
 
+/**
+ * The `config` service allows you to access the shop's and your app's configuration values.
+ *
+ * @script-service miscellaneous
+ */
 class SystemConfigFacade
 {
     private const PRIVILEGE = 'system_config:read';
@@ -30,6 +35,12 @@ public function __construct(SystemConfigService $systemConfigService, Connection
     }
 
     /**
+     * The `get()` method allows you to access all config values of the store.
+     * Notice that your app needs the `system_config:read` privilege to use this method.
+     *
+     * @param string $key The key of the configuration value e.g. `core.listing.defaultSorting`.
+     * @param string|null $salesChannelId The SalesChannelId if you need the config value for a specific SalesChannel, if you don't provide a SalesChannelId, the one of the current Context is used as default.
+     *
      * @return array|bool|float|int|string|null
      */
     public function get(string $key, ?string $salesChannelId = null)
@@ -50,6 +61,12 @@ public function get(string $key, ?string $salesChannelId = null)
     }
 
     /**
+     * The `app()` method allows you to access the config values your app's configuration.
+     * Notice that your app does not need any additional privileges to use this method, as you can only access your own app's configuration.
+     *
+     * @param string $key The name of the configuration value specified in the config.xml e.g. `exampleTextField`.
+     * @param string|null $salesChannelId The SalesChannelId if you need the config value for a specific SalesChannel, if you don't provide a SalesChannelId, the one of the current Context is used as default.
+     *
      * @return array|bool|float|int|string|null
      */
     public function app(string $key, ?string $salesChannelId = null)

src/Docs/Command/App/DocsAppEventCommand.php

@@ -69,6 +69,7 @@ public function render(): string
 
         $this->collectEntityWrittenEvent($eventsDoc);
 
+        $originalLoader = $this->twig->getLoader();
         $this->twig->setLoader(new ArrayLoader([
             'hookableEventsList.md.twig' => file_get_contents($this->templateEvents),
         ]));
@@ -79,7 +80,9 @@ public function render(): string
                 ['eventDocs' => $eventsDoc]
             );
         } catch (LoaderError | RuntimeError | SyntaxError $e) {
-            throw new \RuntimeException('Can not render Webhook Events');
+            throw new \RuntimeException('Can not render Webhook Events', $e->getCode(), $e);
+        } finally {
+            $this->twig->setLoader($originalLoader);
         }
     }