sylius/shop-api-plugin

Shop API for Sylius E-Commerce.

Installs: 44 506

Dependents: 1

Suggesters: 0

Security: 0

Stars: 108

Watchers: 25

Forks: 85

Open Issues: 43

Type:sylius-plugin


README

68747470733a2f2f64656d6f2e73796c6975732e636f6d2f6173736574732f73686f702f696d672f6c6f676f2e706e67

Sylius Shop API

License Build Status Scrutinizer Quality Score

68747470733a2f2f73796c6975732e636f6d2f6173736574732f62616467652d6f6666696369616c2d73796c6975732d706c7567696e2e706e67

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.

Documentation

The latest documentation is available here. If you are looking for more information how the system works have a look at the cookbook

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:

    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 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,

      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.md#installation

Sample configuration of Shop API can be found here: https://github.com/Sylius/SyliusDemo/commit/4872350dcd6c987d54dec1f365b4bb890d7183c9

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.

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.

Testing

The application can be tested with API Test Case. In order to run test suite execute the following commands:

$ 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:

$ 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.

Maintenance

This library is officially maintained by Sylius together with the following contributors outside of the organization:

Release cycle

This projects follows Semantic Versioning. Shop API release cycle is independent from Sylius release cycle.

Next major releases are not planned yet. Minor and patch releases will be published as needed.

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.

Example (with arbitrary dates):

  • v1.0.0 is released on 23.11.2019
  • v1.0.1 with a bugfix is provided on 03.02.2020
  • v1.1.0 is released on 15.02.2020:
    • 1.0 branch will not get bugfixes anymore
    • 1.0 security support will end on 15.02.2021