sylius/shop-api-plugin

Shop API for Sylius E-Commerce.

, _(*1)

Sylius Shop API

, _(*2)

, _(*3)

This repository contains a plugin that extends the Sylius eCommerce platform with an API in JSON that allows performing all standard shop operations from the customer perspective., _(*4)

Documentation

The latest documentation is available here. If you are looking for more information how the system works have a look at the cookbook, _(*5)

Installation

IMPORTANT NOTE: Before installing SyliusShopApiPlugin, you should disable all SyliusShopBundle's dependencies. You cannot use these packages together.

1. Run composer require sylius/shop-api-plugin and, when asked if you want to execute the Flex recipe, answer 'Yes'.

2. Extend config files:, _(*6)

   1. Add SyliusShopApi to config/bundles.php.

   // config/bundles.php
   
       return [
           Sylius\ShopApiPlugin\SyliusShopApiPlugin::class => ['all' => true],
       ];
   

   1. Add - { path: '^/shop-api', priorities: ['json'], fallback_format: json, prefer_extension: true } to fos_rest.format_listener.rules section in config/packages/fos_rest.yaml file and import config from Plugin.

   # config/packages/_sylius_shop_api.yaml
   
   imports: # <-- Add this section if it does not already exist and add the lines below
       # ...
       - { resource: "@SyliusShopApiPlugin/Resources/config/app/config.yml" }
       - { resource: "@SyliusShopApiPlugin/Resources/config/app/sylius_mailer.yml" }
   
   # config/packages/fos_rest.yaml
   
   fos_rest:
       # ...
   
       format_listener:
           rules:
               - { path: '^/shop-api', priorities: ['json'], fallback_format: json, prefer_extension: true } # <-- Add this
               - { path: '^/api', priorities: ['json', 'xml'], fallback_format: json, prefer_extension: true }
               - { path: '^/', stop: true }
   
   

   1. Add new routes file to import routes from the SyliusShopApiPlugin

   # config/routes/sylius_shop_api.yaml
   
   sylius_shop_api:
       resource: "@SyliusShopApiPlugin/Resources/config/routing.yml"
   

   1. Configure firewall
      1. Change sylius.security.shop_regex parameter to exclude shop-api prefix also
      2. Add ShopAPI regex parameter sylius_shop_api.security.regex: "^/shop-api"
      3. Add ShopAPI firewall config:

   # config/packages/security.yaml
   
   parameters:
       # ...
   
       sylius.security.shop_regex: "^/(?!admin|api/.*|api$|shop-api|media/.*)[^/]++" # shop-api has been added inside the brackets
       sylius_shop_api.security.regex: "^/shop-api"
   
   # ... 
   
   security:
       firewalls:
           // ...
   
           sylius_shop_api:
               pattern: "%sylius_shop_api.security.regex%"
               stateless: true
               anonymous: true
               provider: sylius_shop_user_provider
               json_login:
                   check_path: /shop-api/login
                   username_path: email
                   password_path: password
                   success_handler: lexik_jwt_authentication.handler.authentication_success
                   failure_handler: lexik_jwt_authentication.handler.authentication_failure
               guard:
                   authenticators:
                       - lexik_jwt_authentication.jwt_token_authenticator
      access_control:
      - { path: "%sylius_shop_api.security.regex%/address-book", role: ROLE_USER}
      - { path: "%sylius_shop_api.security.regex%/me", role: ROLE_USER}
   
   

   1. (optional) if you have installed nelmio/NelmioCorsBundle for Support of Cross-Origin Ajax Request,, _(*7)

      1. Add the NelmioCorsBundle to the AppKernel

      // config/bundles.php
      
      return [
          Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true],
      ];
      
      

      1. Add the new configuration file

      # config/packages/nelmio_cors.yml
      
      # ...
      
      nelmio_cors:
          defaults:
              allow_credentials: false
              allow_origin: []
              allow_headers: []
              allow_methods: []
              expose_headers: []
              max_age: 0
              hosts: []
              origin_regex: false
              forced_allow_origin_value: ~
          paths:
              '^/shop-api/':
                  allow_origin: ['*']
                  allow_headers: ['Content-Type', 'authorization']
                  allow_methods: ['POST', 'PUT', 'GET', 'DELETE', 'PATCH', 'OPTIONS']
                  max_age: 3600
      

3. Follow https://github.com/lexik/LexikJWTAuthenticationBundle/blob/master/Resources/doc/index.rst#installation, _(*8)

Sample configuration of Shop API can be found here: https://github.com/Sylius/SyliusDemo/commit/4872350dcd6c987d54dec1f365b4bb890d7183c9, _(*9)

Additional features

Attributes

If you would like to receive serialized attributes you need to define an array of theirs codes under sylius_shop_api.included_attributes key. E.g., _(*10)

# config/packages/sylius_shop_api.yml
sylius_shop_api:
    included_attributes:
        - "MUG_MATERIAL_CODE"

This plugin comes with an integration with LexikJWTAuthenticationBundle. More information about security customizations may be found there., _(*11)

Testing

The application can be tested with API Test Case. In order to run test suite execute the following commands:, _(*12)

$ cp tests/Application/.env.test.dist tests/Application/.env.test
$ set -a && source tests/Application/.env.test && set +a
$ (cd tests/Application && bin/console doctrine:database:create -e test)
$ (cd tests/Application && bin/console doctrine:schema:create -e test)

$ vendor/bin/phpunit

The application can be also tested with PHPSpec:, _(*13)

$ vendor/bin/phpspec run

Security issues

If you think that you have found a security issue, please do not use the issue tracker and do not post it publicly. Instead, all security issues must be sent to security@sylius.com., _(*14)

Maintenance

This library is officially maintained by Sylius together with the following contributors outside of the organization: * Maximilian Pesch, _(*15)

Release cycle

This projects follows Semantic Versioning. Shop API release cycle is independent from Sylius release cycle., _(*16)

Next major releases are not planned yet. Minor and patch releases will be published as needed., _(*17)

We provide bug fixes only for the most recent minor release. We provide security fixes for one year since the release of subsequent minor release., _(*18)

Supported versions