Skip to main content
Version: next

Set-up Magento Module

Front-Commerce applications requires a Front-Commerce module to be installed in Magento1 / OpenMage. This guide explains how to install it.

Module compatibility​

We recommend to use OpenMage LTS (1.9.4.x - v19.x) with at least PHP 7.3 (with OpenSSL) and MySQL 8.0. It is also compatible with Magento CE >= 1.7 and Magento EE 1.12.x.

Installation​

You can use 2 ways for installation, we recommend to use composer.

Install with composer​

Prerequisites​

  • Have a working install of composer.
  • You need to create a (or retrieve an existing) token from your Gitlab account and replace $FC_GITLAB_TOKEN by your token on the next step.

Composer usage​

For a community edition version:

composer config minimum-stability dev
composer config repositories.front-commerce git https://gitlab.blackswift.cloud/front-commerce/magento1-module-front-commerce.git
composer config repositories.front-commerce-restful git https://github.com/PH2M/Magento-Extra-RESTful
composer config http-basic.gitlab.blackswift.cloud token $FC_GITLAB_TOKEN
composer require front-commerce/magento1-module:"^1.3"

For an enterprise edition version:

composer config minimum-stability dev
composer config repositories.front-commerce-ee git https://gitlab.blackswift.cloud/front-commerce/magento1-module-enterprise-front-commerce
composer config repositories.front-commerce git https://gitlab.blackswift.cloud/front-commerce/magento1-module-front-commerce.git
composer config repositories.front-commerce-restful git https://github.com/PH2M/Magento-Extra-RESTful
composer config http-basic.gitlab.blackswift.cloud token $FC_GITLAB_TOKEN
composer require front-commerce/magento1-module-enterprise:"dev-master"
note

front-commerce/magento1-module-enterprise is currently in beta, requiring dev-master allows to get the last version. After this beta phase, it is strongly recommended to use a fixed version. (see available release for Enterprise Edition)

Install directly in your Magento app folder​

Configuration​

note

If the installation is successful, in Magento's administration panel, you will have a new entry "Front-Commerce" in the top menu and a new tab "Front-Commerce" in System > Configuration.

Check install​

Go to the Front-Commerce > Configuration admin menu entry. You should see an "Installer checker" that will ensure that everything is configured correctly in your shop.

Right after your first installation, most of the checks should be invalid. Please refer to the next steps to validate them.

REST roles​

Front-Commerce requires you to define 3 roles.

Here are the main steps:

  • Go to admin menu entry System > Web services > REST Roles
  • You need to have 3 roles, Guest, Customer, and Admin. If you don't, create them.
  • Set all roles access to all resources (Role API Resources tab > Resource Access "All").

See the official documentation for detailed information about how to achieve this with Magento.

REST attributes​

Front-Commerce roles must have access to several data on each entities, so it can expose them in GraphQL. You must allow each role to read these information.

  • Go to admin menu entry System > Web services > REST Attributes
  • You can see 3 user types Guest, Customer, and Admin.
  • Set all ACL attributes rules to all resource access (ACL Attribute Rules tab > Resource Access "All").

REST OAuth Consumer​

Front-Commerce must be able to create tokens for users when they log-in. You should ensure there is a Front-Commerce consumer configured in your install.

  • Go to admin menu entry System > Web services > REST OAuth Consumers
  • Add New OAuth Consumer:
    • Name: Front-Commerce
    • Callback URL: http://local.host <- is useless but can't be empty

The Key/Secret values should be used to configure your Front-Commerce, with the FRONT_COMMERCE_MAGENTO1_CONSUMER_KEY and FRONT_COMMERCE_MAGENTO1_CONSUMER_SECRET environment variables in your .env file.

Admin user​

Advanced features such as Embedded Payments have to use an admin user with REST access. You must ensure it exists, by doing the following steps.

  • Go to admin menu entry System > Permissions > User
  • Create a new user (only used for Front-Commerce's embedded payments feature, users will never interact with your shop using this account)
    • User Name: Front-Commerce
    • First Name: Front-Commerce
    • Last Name Front-Commerce
    • Email: enter an administrator email
    • Password: enter a password
    • REST Role: Admin

REST admin token​

You must generate admin tokens to configure Front-Commerce.

  • Go to admin menu entry Front-Commerce > Configuration
  • Click on "Generate Token" link in installer checker section (This should be the same key as FRONT_COMMERCE_MAGENTO1_ACCESS_TOKEN and FRONT_COMMERCE_MAGENTO1_ACCESS_TOKEN_SECRET in your Front-Commerce .env)

Magento core patch​

If the OAuth Zend Patch is not valid in the installer checker, please follow these steps:

  • Copy the fix-sort-params-core.patch file in your root directory
  • Past it on your root Magento directory
  • Apply them
    • With GIT: git apply fix-sort-params-core.patch
    • Without GIT: patch -p1 < fix-sort-params-core.patch

URLs settings​

  • Go to System > Configuration > Front-Commerce General > URLs Settings
  • Add your Front-Commerce Front URL. In development environment, it should be http://localhost:4000/. In production environment, it is the URL of your main store.
  • Go to System > Configuration > General > Web
  • Make sure Add Store Code to Urls is disabled
  • Set your base URL (secure + unsecure) with your Front-Commerce front URL (http://localhost:4000/ in development environment) for each store view value. You can keep your admin URL for the default value.

Cache settings​

  • Go to System > Configuration > Front-Commerce General > Cache Settings
  • Add random Key (This should be the same key as FRONT_COMMERCE_CACHE_API_TOKEN in your Front-Commerce .env)

Front-Commerce secret key​

For more security add a random key on frontcommerce_secret_key in your app/etc/local.xml

<config>
  <global>
    <frontcommerce_secret_key>{REPLACE_ME_BY_STRING_VALUE}</frontcommerce_secret_key>
    // ...

Reviews configuration​

info

This feature requires Front-Commerce Magento 1 module version 1.6.0 or higher.

Front-Commerce, by default, uses only one review "rating", named "main". Those are configured in Magento1's back office under Catalog > Reviews and Ratings > Manage Ratings. If your project uses more than one rating, or one with a different name, you will have to configure them.

In order to do so, you need to override magento1ReviewsConfigProvider's ratingTypes default value. To learn more on how to do this, follow the override an existing configuration guide. In this config provider, you will need to add each the name and id of each provider you want your customer to see.

Configure facet order​

If you want to be able to organize your facets' order, you will need to enable it in the magentoProvider (see code). In this provider, override magento.attributes.useFacetSortOrder to set it to true.

tip

To learn more about how to override configuration provider, see our guide on overriding an existing provider.

Once that's done, all facets will be sorted by their "position" attribute that is defined in the Magento's back office.

Clean Magento cache​

Ensure it works​

Once this is done, all the checks should be green in your installer checker and you should be good to go. You can check that the guest permissions are correctly configured by accessing this URL:

{MAGENTO_BASE_URL}/api/rest/frontcommerce/urls/match?urls[0]=/about-magento-demo-store

Common issues​

URL Rewrite​

The entry point of the API is the file api.php. In order to work, you need to have the following rules:

For Apache in an .htaccess or in the server configuration:

RewriteRule ^api/rest api.php?type=rest [QSA,L]

For nginx in server configuration:

location /api {
    rewrite ^/api/rest /api.php?type=rest last;
    rewrite ^/api/v2_soap /api.php?type=v2_soap last;
    rewrite ^/api/soap /api.php?type=soap last;
}

Mistake in ACL access​

Double check that you have followed REST roles and REST attributes sections carefully.