Merge branch '8.0-en-configuration_docs-OXDEV-7354' into 8.0-en

.github/workflows/schema.yml

@@ -66,6 +66,7 @@ jobs:
       - name: Install module and dependencies
         run: |
           docker-compose exec -T php composer require oxid-esales/graphql-storefront --no-update
+          docker-compose exec -T php composer require oxid-esales/graphql-configuration-access --no-update
           docker-compose exec -T php composer update --no-interaction
 
       - name: Reset shop
@@ -78,6 +79,7 @@ jobs:
         run: |
           docker-compose exec -T php php bin/oe-console oe:module:activate oe_graphql_base
           docker-compose exec -T php php bin/oe-console oe:module:activate oe_graphql_storefront
+          docker-compose exec -T php php bin/oe-console oe:module:activate oe_graphql_configuration_access 
 
       - name: Generate documentation
         run: |

authorization.rst

@@ -84,6 +84,10 @@ In case you need to have more control on how the authorization service decides,
 you may register a handler for the ``OxidEsales\GraphQL\Base\Event\BeforeAuthorization``
 event and oversteer the result in your event subscriber, see :ref:`events-BeforeAuthorization`.
 
+.. note::
+   If the admin is created, it isn't assigned to the ``oxidadmin`` group by default. As the rights are
+   dependent on the group, the user would have no special rights. Be sure the group is set.
+
 .. important::
 
    We decided to show queries and mutations in the schema even if the user is unauthorized.

consuming/Configurations.rst

@@ -0,0 +1,133 @@
+Read and update configurations
+==============================
+
+.. important::
+   To read and update configurations you need the  `GraphQL Configuration Access module
+   <https://github.com/OXID-eSales/graphql-configuration-access/>`_ installed and activated.
+
+List configurations
+-------------------
+
+To read or update configurations it's important to know which type the configuration has, you want to modify
+or read to.
+Three list queries are available to figure that out. One for module- (``moduleSettings``), one for theme- (``themeSettings``)
+and one for shop-configurations (``shopSettings``).
+
+Here is one example how to use it:
+
+.. code-block:: graphql
+   :caption: call to ``moduleSettings`` query
+
+    query settings {
+        moduleSettings(
+            moduleId: "awesomeModule"
+        )
+    }
+
+.. code-block:: json
+   :caption: ``moduleSettings`` query response
+
+    {
+        "data": {
+            "moduleSettings": [
+                {
+                    "name": "intSetting",
+                    "type": "num",
+                    "supported": true
+                },
+                {
+                    "name": "floatSetting",
+                    "type": "num",
+                    "supported": true
+                },
+                {
+                    "name": "boolSetting",
+                    "type": "bool",
+                    "supported": true
+                },
+                {
+                    "name": "stringSetting",
+                    "type": "str",
+                    "supported": true
+                },
+                {
+                    "name": "arraySetting",
+                    "type": "arr",
+                    "supported": true
+                }
+            ]
+        }
+    }
+
+The returned data is showing the ``name`` of the setting, the ``type``, to know how to fetch or change the
+setting and whether the type is ``supported`` by the module queries and mutations at all.
+
+Read configurations
+-------------------
+
+If the type is known, you can read the setting by using one of the type separated queries.
+The ``name`` of the setting and in our case the corresponding ``module`` is necessary to explicitly
+select the configuration.
+
+.. code-block:: graphql
+   :caption: call to ``moduleSettingBoolean`` query
+
+    query booleanSetting {
+        moduleSettingBoolean(
+            name: "booleanSetting",
+            moduleId: "awesomeModule"
+        ) {
+            name
+            value
+        }
+    }
+
+.. code-block:: json
+   :caption: ``moduleSettingBoolean`` query response
+
+    {
+        "data": {
+            "moduleSettingBoolean": {
+                "name": "booleanSetting",
+                "value": false,
+            }
+        }
+    }
+
+Update configurations
+---------------------
+
+To update a setting, the ``name``, the new ``value`` and in our case the ``module`` is necessary.
+
+.. code-block:: graphql
+   :caption: call to ``moduleSettingBooleanChange`` query
+
+    mutation changeBooleanSetting {
+        moduleSettingBooleanChange(
+            name: "booleanSetting",
+            value: true
+            moduleId: "awesomeModule"
+        ) {
+            name
+            value
+        }
+    }
+
+.. code-block:: json
+   :caption: ``moduleSettingBooleanChange`` query response
+
+    {
+        "data": {
+            "moduleSettingsBooleanChange": {
+                "name": "booleanSetting",
+                "value": true,
+            }
+        }
+    }
+
+
+.. important::
+   Pay attention that the types for module/theme/shop-queries or mutations can be different.
+   Also the handling of the values depends on the implementation in the shop.
+   Only the handling of Theme-configurations are currently implemented by the module itself.
+

consuming/index.rst

@@ -9,3 +9,4 @@ Consuming the API
         BrowseStorefront
         AdministrateCustomer
         PlaceOrder
+        Configurations

development.rst

@@ -32,6 +32,9 @@ prepacked and configured, but please feel free to use anything that fits your ne
 For PHPStan to work, we added a preconfigured ``phpstan.neon`` configuration file,
 as well as the OXID eShop as a dev dependency.
 
+In the ``GraphQL Configuration Access`` module the static code analysis can be simply
+done with composer scripts using ``composer static``.
+
 Dependencies between software layers
 ------------------------------------
 
@@ -60,6 +63,12 @@ You can run them via
 or (for Codeception) via
 ``vendor/bin/codecept run acceptance -c vendor/oxid-esales/graphql-base/tests/codeception.yml``.
 
+In ``GraphQL Configuration Access`` module we use composer scripts to execute tests.
+Unit and Integration tests are executed with
+``composer phpunit``
+and codeception tests with
+``composer codeception``.
+
 Using PHPUnit
 ^^^^^^^^^^^^^
 

exceptions/Exceptions.rst

@@ -16,6 +16,19 @@ Exists        requesterror     Thrown when a record exists (when we want to regi
 OutOfBounds   requesterror     Thrown when values are out of bounds
 ============  ===============  ==================================================================================
 
+The ``graphql-configuration-access`` module provides the following exceptions
+
+================================  ==================================================================================
+Class                             Description
+================================  ==================================================================================
+CollectionEncodingException       Thrown when collection couldn't be encoded into string for database
+InvalidCollectionException        Thrown when a database string can't be decoded into an array
+WrongSettingValueException        Thrown if the returned value doesn't fit to the requested setting type (e.g.: float was requested but integer was returned)
+NoSettingsFoundForShopException   Thrown when requesting all Settings for a shop, but none exist
+WrongSettingTypeException         Thrown if the returned setting type doesn't fit to the requested setting type
+NoSettingsFoundForThemeException  Thrown when requesting all Settings for a theme, but none exist
+================================  ==================================================================================
+
 Exception to GraphQL Error
 --------------------------
 

install.rst

@@ -18,7 +18,13 @@ Then you can simply install the module(s) by using ``composer require`` command.
 
     composer require oxid-esales/graphql-storefront
 
-This will automatically install the **OXID GraphQL Base** module, which is needed for general GraphQL integration into the OXID eShop. In case you only need the basic GraphQL integration and want to implement your own queries and mutations, you can also install the **GraphQL Base** module exclusively:
+If you want to read and update configurations you should also install the **OXID GraphQL Configuration Access** module:
+
+.. code-block:: bash
+
+    composer require oxid-esales/graphql-configuration-access
+
+Both modules will automatically install the **OXID GraphQL Base** module, which is needed for general GraphQL integration into the OXID eShop. In case you only need the basic GraphQL integration and want to implement your own queries and mutations, you can also install the **GraphQL Base** module exclusively:
 
 .. code-block:: bash
 
@@ -39,11 +45,12 @@ Now you need to activate the modules. You can do this in the OXID eShop administ
 
     vendor/bin/oe-console oe:module:activate oe_graphql_base
     vendor/bin/oe-console oe:module:activate oe_graphql_storefront
+    vendor/bin/oe-console oe:module:activate oe_graphql_configuration_access
 
 .. important::
 
     Keep in mind the **GraphQL Base** module should be activated first, before activating dependent modules
-    like GraphQL Storefront. Also before deactivating GraphQL Base module please ensure dependent modules are
+    like GraphQL Storefront or GraphQL Configuration Access. Also before deactivating GraphQL Base module please ensure dependent modules are
     deactivated first.
 
     In case you are using the OXID eShop Enterprise Edition, it is important for **GraphQL Base** module to be active

modules.rst

@@ -28,3 +28,16 @@ mission is to
 * support placing new orders. It is possible to manage multiple userbaskets, add/remove products
   from those baskets, query and chose delivery address, shipping method and payment and in the end
   place the order. See :doc:`Consuming the API - Place an Order <./consuming/PlaceOrder>`.
+
+GraphQL-Configuration Access module
+-----------------------------------
+
+`GraphQL-Configuration module <https://github.com/OXID-eSales/graphql-configuration-access/>`_
+is needed if you want to
+
+* read configurations
+* update configurations
+* list existing configurations.
+
+All functionality is possible for module/theme and shop-configurations.
+See :doc:`Consuming the API - Read and update configurations <./consuming/Configurations>`.

troubleshooting.rst

@@ -75,11 +75,13 @@ Graphql schema appears incomplete
 
 Your client's introspection requests get the available schema based upon your access rights. Make sure you are logged in and using the correct token in the ``Authorization`` header.
 
-If you're having trouble finding admin panel requests, this could also be caused by insufficient account rights.
+The rights are depending on the user group. If you're having trouble finding admin panel requests, this could also be caused by insufficient account rights.
+If queries or mutations are missing, please check the user groups and the depending rights in the PermissionProvider-Classes of the modules.
 
-.. note::
+.. important::
 
-    You may want to doublecheck this in the database, as the administrative dashboard setting name could be different. E.g. it could say a user has been granted ``admin`` rights, but actually they are a ``malladmin``. It is not the same and does not give enough access to query, as an example, the shop version
+    You may want to doublecheck this in the database, as the administrative dashboard setting name could be different. E.g. it could say a user has been granted ``admin`` rights, but actually they are a ``malladmin``. It is not the same and does not give enough access to query, as an example, the shop version.
+    To gain admin rights, the user group ``oxidadmin`` needs to be assigned.
 
 Installation issues for dev environment
 ---------------------------------------