Install the Merchant Portal

Edit on GitHub

Environment requirements

  • Node.js: inimum version is 18.
  • npm: minimum version is 9.
  • Spryker supported PHP version 8.0
  • Host for Zed application

Install frontend dependencies

$ npm install

Build frontend

$ npm run mp:build

For production:

$ npm run mp:build:production

Install backend

Install the needed packages for the Merchant Portal with dependencies. For available list, in the Srpyker Git Hub repository, search for merchant-portal-gui.

NAME VERSION INSTALLATION GUIDE
Spryker Core 202404.0 Install the Spryker Core feature
Marketplace Merchant Portal Core 202404.0 Install the Marketplace Merchant Portal Core feature

Merchant Portal users

1) Create users

Create users for the Merchant Portal using Zed UI (Back Office), or if you need them out of the box, add them into \Pyz\Zed\User\UserConfig::getInstallerUsers()—for example:

src/Pyz/Zed/User/UserConfig.php

<?php

namespace Pyz\Zed\User;

use Spryker\Zed\User\UserConfig as SprykerUserConfig;

class UserConfig extends SprykerUserConfig
{
     /**
     * @return array
     */
    public function getInstallerUsers()
    {
        return [
            [
                'firstName' => 'Michele',
                'lastName' => 'Nemeth',
                'password' => 'change123',
                'username' => 'michele@sony-experts.com',
            ],
        ];
    }
}

2) Connect users and merchants

1.Connect users and merchants using Zed UI (the Back Office) or the following data import:

data/import/common/common/marketplace/merchant.csv

 merchant_key,merchant_reference,merchant_name,registration_number,status,email,is_active,url.de_DE,url.en_US
 sony-experts,MER000006,Sony Experts,HYY 134306,approved,michele@sony-experts.com,1,/de/merchant/sony-experts,/en/merchant/sony-experts
  1. To inegrate merchant user data import, see Install the Marketplace Merchant feature.

data/import/common/common/marketplace/merchant_user.csv

merchant_key,username
sony-experts,michele@sony-experts.com
  1. Import data:
console data:import merchant
console data:import merchant-user

3) ACL adjustments.

By default, all newly created merchants and merchant users automatically have a group, role, and segment with autogenerated names based on MerchantName, MerchantUserName, and MerchantPortalKey.

  1. To allow Merchant Portal pages (*-merchant-portal-gui) for merchant users (optionally deny access to them for Admin roles), adjust AclConfig respectively.

To check the available list of packages for the Merchant Portal, in the Srpyker Git Hub repository, search for merchant-portal-gui.

src/Pyz/Zed/Acl/AclConfig.php
<?php

namespace Pyz\Zed\Acl;

use Generated\Shared\Transfer\AclEntityRuleTransfer;
use Generated\Shared\Transfer\RuleTransfer;
use Spryker\Shared\Acl\AclConstants;
use Spryker\Zed\Acl\AclConfig as SprykerAclConfig;

class AclConfig extends SprykerAclConfig
{
    /**
     * @var string
     */
    protected const RULE_TYPE_DENY = 'deny';

    /**
     * @return array
     */
    public function getInstallerRules()
    {
        $installerRules = parent::getInstallerRules();
        $installerRules = $this->addMerchantPortalInstallerRules($installerRules);

        return $installerRules;
    }

     /**
     * @param array<array<string>> $installerRules
     *
     * @return array<array<string>>
     */
    protected function addMerchantPortalInstallerRules(array $installerRules): array
    {
        $bundleNames = [
            'dashboard-merchant-portal-gui',
            'merchant-profile-merchant-portal-gui',
            'product-merchant-portal-gui',
            'product-offer-merchant-portal-gui',
            'security-merchant-portal-gui',
            'sales-merchant-portal-gui',
            'user-merchant-portal-gui',
            'dummy-merchant-portal-gui',
        ];

        foreach ($bundleNames as $bundleName) {
            $installerRules[] = [
                'bundle' => $bundleName,
                'controller' => AclConstants::VALIDATOR_WILDCARD,
                'action' => AclConstants::VALIDATOR_WILDCARD,
                'type' => static::RULE_TYPE_DENY,
                'role' => AclConstants::ROOT_ROLE,
            ];
        }

        return $installerRules;
    }

    /**
     * @return array
     */
    public function getInstallerUsers()
    {
        return [
            'michele@sony-experts.com' => [],
            //this is related to existent username and will be searched into the database
        ];
    }
}
  1. Create users with ACL rules:
console setup:init-db

Extend ACL entity metadata configuration.

As an example of extending the AclEntityMetadata configuration, you can use the AclEntityDummyProduct module.

Install the module:

composer require spryker/acl-entity-dummy-product:"^0.2.0" --update-with-dependencies

As an example of the AclEntityMetadataCollection configuration, use \Spryker\Zed\AclEntityDummyProduct\Communication\DummyProductAclEntityMetadataConfigExpanderPlugin:

<?php
     namespace Pyz\Zed\AclEntity;

     use Spryker\Zed\Acl\AclDependencyProvider as SprykerAclDependencyProvider;
     use Spryker\Zed\AclEntityDummyProduct\Communication\DummyProductAclEntityMetadataConfigExpanderPlugin;

     class AclEntityDependencyProvider extends SprykerAclEntityDependencyProvider
     {
         /**
          * @return array<\Spryker\Zed\AclEntityExtension\Dependency\Plugin\AclEntityMetadataConfigExpanderPluginInterface>
          */
          protected function getAclEntityMetadataCollectionExpanderPlugins(): array
          {
              return [
                  new DummyProductAclEntityMetadataConfigExpanderPlugin(),
              ];
          }
     }
  1. To configure the Merchant Portal sidebar, add installed MP GUI modules to config/Zed/navigation.xml.
config/Zed/navigation.xml
<?xml version="1.0"?>
<config>
    <merchant-portal-dashboard>
        <label>Dashboard</label>
        <title>Merchant Dashboard</title>
        <icon>dashboard</icon>
        <bundle>dashboard-merchant-portal-gui</bundle>
        <controller>dashboard</controller>
        <action>index</action>
    </merchant-portal-dashboard>
    <merchant-portal-profile>
        <label>Profile</label>
        <title>Profile</title>
        <icon>profile</icon>
        <bundle>merchant-profile-merchant-portal-gui</bundle>
        <controller>profile</controller>
        <action>index</action>
    </merchant-portal-profile>
    <product-offer-merchant-portal-gui>
        <label>Offers</label>
        <title>Offers</title>
        <icon>offers</icon>
        <bundle>product-offer-merchant-portal-gui</bundle>
        <controller>product-offers</controller>
        <action>index</action>
        <pages>
            <create-offer>
                <label>Create Offer</label>
                <title>Create Offer</title>
                <bundle>product-offer-merchant-portal-gui</bundle>
                <controller>product-list</controller>
                <action>index</action>
                <visible>0</visible>
            </create-offer>
        </pages>
    </product-offer-merchant-portal-gui>
    <sales-merchant-portal-gui>
        <label>Orders</label>
        <title>Orders</title>
        <icon>orders</icon>
        <bundle>sales-merchant-portal-gui</bundle>
        <controller>orders</controller>
        <action>index</action>
    </sales-merchant-portal-gui>
    <product-merchant-portal-gui>
        <label>Products</label>
        <title>Products</title>
        <icon>offers</icon>
        <bundle>product-merchant-portal-gui</bundle>
        <controller>products</controller>
        <action>index</action>
    </product-merchant-portal-gui>
    <security-merchant-portal-gui>
        <label>Logout</label>
        <title>Logout</title>
        <icon>logout</icon>
        <bundle>security-merchant-portal-gui</bundle>
        <controller>logout</controller>
        <action>index</action>
    </security-merchant-portal-gui>
</config>
  1. Build navigation cache:
console navigation:build-cache
Verification

Make sure the following is true:

  • All configured items are present in the Merchant Portal Sidebar and route you accordingly.
  • In \Pyz\Zed\ZedNavigation\ZedNavigationDependencyProvider, \Spryker\Zed\Acl\Communication\Plugin\Navigation\AclNavigationItemCollectionFilterPlugin is enabled:
<?php

namespace Pyz\Zed\ZedNavigation;

use Spryker\Zed\Acl\Communication\Plugin\Navigation\AclNavigationItemCollectionFilterPlugin;
use Spryker\Zed\ZedNavigation\ZedNavigationDependencyProvider as SprykerZedNavigationDependencyProvider;

class ZedNavigationDependencyProvider extends SprykerZedNavigationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ZedNavigationExtension\Dependency\Plugin\NavigationItemCollectionFilterPluginInterface>
     */
    protected function getNavigationItemCollectionFilterPlugins(): array
    {
        return [
            new AclNavigationItemCollectionFilterPlugin(),
        ];
    }
}

5) Separate login feature setup (security firewalls).

It requires upgrading spryker/smyfony:3.5.0 and applying some changes on the project. For details, see Symfony 5 integration.

  1. Install the required modules using Composer:
composer remove spryker/auth spryker/auth-mail-connector spryker/auth-mail-connector-extension spryker/authentication-merchant-portal-gui
composer require spryker/security-gui:"^1.0.0" spryker/security-merchant-portal-gui:"^1.0.0" spryker/security-system-user:"^1.0.0" spryker/user-password-reset:"^1.0.0" spryker/user-password-reset-extension:"^1.0.0" spryker/user-password-reset-mail:"^1.0.0" --update-with-dependencies
  1. Update the following modules to the latest minors.
MODULE DIRECTORY
Application vendor/spryker/application
MerchantUser vendor/spryker/merchant-user
Security vendor/spryker/security
Session vendor/spryker/session
User vendor/spryker/user
ZedUi vendor/spryker/zed-ui
  1. Apply changes from https://github.com/spryker-shop/suite/pull/681/files.
Verification

Go to http://mp.de.spryker.local/security-merchant-portal-gui/login and ensure that the Merchant Portal looks as follows:

Merchant Portal login

After loging in, you are redirected to the dashboard. The contents of the sidebar depend on the installed features and their configuration.

Merchant Portal dashboard

Integrate the following related features:

FEATURE REQUIRED FOR THE CURRENT FEATURE INSTALLATION GUIDE
Merchant Portal - Marketplace Merchant Install the Merchant Portal - Marketplace Merchant feature
Merchant Portal - Marketplace Product Install the Merchant Portal - Marketplace Product feature
Merchant Portal - Marketplace Order Management Install the Merchant Portal - Marketplace Order Management feature
Merchant Portal - Marketplace Merchant Portal Product Offer Management + Merchant Portal Order Management Install the Merchant Portal - Marketplace Merchant Portal Product Offer Management + Merchant Portal Order Management feature
Merchant Portal - Marketplace Product + Inventory Management Merchant Portal - Install the Marketplace Product + Inventory Management feature
Merchant Portal - Marketplace Product Options Management Merchant Portal - Marketplace Product Options Management integration
Merchant Portal - Marketplace Product + Tax Install the Merchant Portal - Marketplace Product + Tax feature