README

This module provides:

a basic GraphQL implementation for the OXID eShop
authorization and authentication using JWT
a query to log you in and get a JWT for further authentication

Documentation

Full documentation, including GraphQL schema, can be found here.

Usage

This assumes you have OXID eShop (at least OXID-eSales/oxideshop_ce: v7.3.0 component, which is part of the 7.3.0 compilation) up and running.

Branch Compatibility

11.0.x versions (or b-7.3.x branch) are compatible with latest shop compilation 7.3.x resp. b-7.3.x shop compilation branches
10.0.x versions (or b-7.2.x branch) are compatible with latest shop compilation 7.2.x resp. b-7.2.x shop compilation branches
9.x versions (or b-7.1.x branch) are compatible with latest shop compilation 7.1.x resp. b-7.1.x shop compilation branches
8.x versions (or b-7.0.x branch) are compatible with latest shop compilation: 7.0.x resp. b-7.0.x shop compilation branches
7.x versions (or b-6.5.x branch) are compatible with latest shop compilations: 6.5.x resp. b-6.5.x shop compilation branches
6.x versions (or b-6.4.x branch) are compatible with latest shop compilations: 6.4.x resp. b-6.4.x shop compilation branches
5.x versions (or b-6.3.x branch) are compatible with latest shop compilations: 6.3.x resp. b-6.3.x shop compilation branches (NOTE: no support for PHP 8 yet)

Install

# Install desired version of oxid-esales/graphql-base module, in this case - latest released 9.x version, While updating the version you should add additional flag --with-all-dependencies with below command.
$ composer require oxid-esales/graphql-base ^9.0.0 --with-all-dependencies

You should run migrations both after installing the module and after each module update:

$ vendor/bin/oe-eshop-doctrine_migration migrations:migrate oe_graphql_base

After requiring the module, you need to activate it, either via OXID eShop admin or CLI.

$ bin/oe-console oe:module:activate oe_graphql_base

Update

If you when to update this module from older version to new version. Then run below command to ensure that all dependencies including in the composer.lock are updated that are compatible with each other.

$ composer update --with-all-dependencies

How to use

You can use your favourite GraphQL client to explore the API, if you do not already have one installed, you may use Altair GraphQL Client.

To login and retrieve a token send the following GraphQL query to the server

query {
    token (
        username: "noreply@oxid-esales.com",
        password: "admin"
    )
}

You could simply fire up your terminal and use curl to do a basic check if the GraphQL base module is up and running as expected. To retrieve a valid token you need to replace the username and password below with valid login credentials.

$ curl http://oxideshop.local/graphql/ \
  -H 'Content-Type: application/json' \
  --data-binary '{"query":"query {token(username: \"noreply@oxid-esales.com\", password: \"admin\")}"}'

You should see a response similar to this:

{
    "data": {
        "token": "a-very-long-jwt"
    }
}

This token is then to be send as your authorization with every request in the HTTP Authorization header like this:

Authorization: Bearer a-very-long-jwt

How to use refresh tokens

To login and retrieve a refresh and access token send the following GraphQL query to the server:

query {
    login (
        username: "noreply@oxid-esales.com",
        password: "admin"
    ) {
        refreshToken
        accessToken
    }
}

The response should contain both requested tokens:

{
    "data": {
        "login": {
            "accessToken": "the-same-long-jwt-token",
            "refreshToken": "a-255-character-long-string"
        }
    }
}

The request will set an HttpOnly cookie with unique fingerprint. The accessToken claims contain a hashed version of this fingerprint. The access token should be sent as Bearer type authorization as described above. After the access token's lifetime has elapsed, you will need to refresh it. To do this you will need to send the following query:

query {
    refresh (
        refreshToken: "your-refresh-token",
        fingerprintHash: "from-access-token-claims"
    )
}

If the token is valid and the hash matches the fingerprint sent as cookie, you will receive a fresh token as a response:

{
    "data": {
        "refresh": "a-new-long-jwt"
    }
}

And along with it, a new fingerprint cookie and fingerprintHash claim in the jwt token.

How to extend

The information on extending any module can be found in the OXID eSales documentation.

How to extend GraphQL module types and implement your new mutations and queries is shown in OXID GraphQL API documentation.

Testing

Syntax check and static analysis

$ composer static

Unit/Integration/Acceptance tests

install this module into a running OXID eShop
reset shop's database

$ bin/oe-console oe:database:reset --db-host=db-host --db-port=db-port --db-name=db-name --db-user=db-user --db-password=db-password --force

run Unit/Integration tests

$ ./vendor/bin/phpunit -c vendor/oxid-esales/graphql-base/tests/phpunit.xml

run Acceptance tests

$ SELENIUM_SERVER_HOST=selenium MODULE_IDS=oe_graphql_base vendor/bin/codecept run acceptance -c vendor/oxid-esales/graphql-base/tests/codeception.yml

Development installation

To be able running the tests and other preconfigured quality tools, please install the module as a root package.

The next section shows how to install the module as a root package by using the OXID eShop SDK.

In case of different environment usage, please adjust by your own needs.

Development installation on OXID eShop SDK

The installation instructions below are shown for the current SDK for shop 7.3. Make sure your system meets the requirements of the SDK.

Ensure all docker containers are down to avoid port conflicts
Clone the SDK for the new project

echo MyProject && git clone https://github.com/OXID-eSales/docker-eshop-sdk.git $_ && cd $_

Clone the repository to the source directory

git clone --recurse-submodules https://github.com/OXID-eSales/graphql-base-module.git --branch=b-7.3.x ./source

Run the recipe to setup the development environment, you can decide which shop edition to install. Omitting the flag installs EE.

./source/recipes/setup-development.sh -s CE

You should be able to access the shop with http://localhost.local and the admin panel with http://localhost.local/admin (credentials: noreply@oxid-esales.com / admin)

Running tests locally

Check the "scripts" section in the composer.json file for the available commands. Those commands can be executed by connecting to the php container and running the command from there, example:

make php
composer tests-coverage

Commands can be also triggered directly on the container with docker compose, example:

docker compose exec -T php composer tests-coverage

Issues

To report issues with GraphQL module please use the OXID eShop bugtracking system.

Contributing

You like to contribute? 🙌 AWESOME 🙌
Go and check the contribution guidelines

Build with

License

OXID Module and Component License, see LICENSE file.

oxid-esales / graphql-base

Maintainers

Details