Guide

Prerequisites

Requirements and installation are described in Developer Tools page.

Ngrok (free public domain)

  1. Sign Up/Login: Start by creating a free account on the Ngrok website https://dashboard.ngrok.com/.
  2. Retrieve AuthToken Once you have logged in, navigate to Getting Started > Your Authtoken and retrieve your authtoken, which is essential for authenticating your session with Ngrok.
  3. Create New Domain: Navigate to Universal Gateway > Domains and proceed to create a new domain with default settings, which can be done on the domains page of the dashboard.
  4. Retrieve Static Public Domain: Finally, make sure to retrieve the generated static public domain as you will need it later in the setup process.

Initial Configuration

  1. Run Enterprise Tools: Execute the binary file by typing ps-enterprise (or ./ps-enterprise.exe if you are using Windows) in the terminal. This command will initiate the setup process.
  2. Authenticate: You will be prompted to authenticate using your Enterprise Platform credentials. Ensure you have your login information ready.
  3. Select Project: Once authenticated, you will be presented with a list of available projects. Choose the appropriate Enterprise Platform project by entering the corresponding number.
  4. Configure Shop Directory: You will need to specify the directory where your shop files will be synchronized. This step ensures that all necessary files are properly managed and updated during development.
    Take care to select an empty folder as git retrieval will delete any file.
  5. Enable Shop Debug Mode: Enable debug mode for the shop. Debug mode is essential for troubleshooting and ensuring that your development environment is correctly configured.
  6. Verify User Name: Verify the current user name by checking the user_id:group_id. This information is used to start the local environment and ensure that all permissions are correctly set.
  7. Activate XDEBUG: Activate XDEBUG by configuring its version. The recommended version is 3.3.2. This step is crucial for debugging and monitoring the performance of your development environment.
  8. Configure Ngrok Settings: Set up your Ngrok authtoken and static public domain. These settings are necessary for establishing a secure and stable tunneled connection.

Development & Changes

Disabling Maintenance Mode and Smarty Cache

Before testing any changes, it is essential to ensure to disable the maintenance mode and Smarty cache, allowing you to test modifications in real-time and ensure a smooth development process.

Disabling Maintenance Mode

  1. Log in to the BackOffice of your Prestashop Enterprise shop using your administrator credentials.
  2. In the top navigation bar, locate the “Maintenance Mode” option.
  3. Click on “Maintenance Mode” and disable it to make your shop accessible.

Disabling Smarty Cache

  1. Log in to the BackOffice of your Prestashop Enterprise shop.
  2. Navigate to Advanced Parameters > Performance in the menu.
  3. In the performance settings, disable the Smarty cache to ensure that any template changes are immediately visible on the frontend.

Making Changes

When making changes to your Prestashop Enterprise shop, follow these steps to ensure the changes are applied correctly and can be tested thoroughly.

Development Process

  1. Locate the Templates to Modify: Identify the specific templates that need modification. For example, if you want to update the “Contact Us” page, navigate to the corresponding template file in your local environment.
  2. Make the Necessary Modifications: Use your preferred code editor to make the desired changes to the template files. Ensure that the modifications align with your requirements and adhere to coding best practices.
  3. Save and Test Using Ngrok: Save the changes you have made. To test the modifications in real-time, use the URL generated by Ngrok. This allows you to see how the changes will appear in a live environment and make any necessary adjustments.

Using Xdebug

Xdebug is a powerful tool for debugging PHP applications.

Step 1: Configure Your IDE

Most modern IDEs, such as PHPStorm or Visual Studio Code, support Xdebug.
Below is a general configuration guide:

  1. PHPStorm:
    • Go to File > Settings > Languages & Frameworks > PHP > Debug.
    • Set the Debug port to 9003.
    • Enable the option Can accept external connections.
  2. Visual Studio Code:
    • Install the PHP Debug extension from the marketplace.
    • Add the following configuration to your launch.json file:
    {
  "name": "Debug shop",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html/": "${workspaceFolder}/",
  }
}

Step 2: Listen for Debug Connections

Start listening for Xdebug connections in your IDE:

  • PHPStorm: Click the “Start Listening for PHP Debug Connections” button in the toolbar.
  • Visual Studio Code: Click the debug icon in the sidebar and select “Listen for Xdebug” from the dropdown, then click the play button.

Step 3: Set Breakpoints in Your Code

Set breakpoints in your code where you want to pause execution.
In your IDE, click on the left margin next to the line number to set a breakpoint.
For example, in ./index.php file:


require dirname(__FILE__).'/config/config.inc.php'; 
Dispatcher::getInstance()->dispatch(); // Set a breakpoint here

Step 4: Trigger the Debug Session

Visit the page in your browser where the code with the breakpoint is executed.

  • Navigate to the URL where the code with the breakpoint is located.

Step 5: Debug Your Code

Once the breakpoint is hit, your IDE will pause execution and allow you to inspect variables, step through code, and evaluate expressions.
Use the debugging tools in your IDE to analyze and fix any issues.

Git & Deploy

Overview

The Enterprise Platform project can have up to 3 running environments: Development, Staging and Production.
Development environment is closely linked to a specific GitLab branch ensuring that all changes made within the environment are consistent with the branch to which it is connected. Staging and Production environment are updated cloning from another environment. This setup allows for precise tracking of code modifications and ensures that deployments are based on the most current version of the code.

Deployment Modes

A project environment deployment can use two modes: Manual or Automatic.

  • Manual Deployment: This mode gives you the flexibility to deploy undeployed commits manually, providing granular control over the deployment process. You can choose when to deploy specific commits, ensuring that only thoroughly reviewed and tested changes are moved to the project environment.

  • Automatic Deployment: In this mode, every commit pushed to the GitLab branch associated with the project environment is automatically deployed. This ensures that the project environment is always in sync with the latest changes, facilitating a continuous deployment workflow.

Switching GitLab Branches

You have the ability to switch the GitLab branch associated with a project development environment at any time.
This feature is particularly useful for testing new features or fixes developed on a test branch.
By switching branches, you can effectively test these changes in the project environment without disrupting the main branch.

Making Changes to the Project Environment

To implement changes within a project environment, you can create a new branch from the current project environment branch.
You can then commit your changes to this new branch and test them by switching the environment to the newly created branch.
Once you are satisfied with the changes, you can merge the new branch back into the original project environment branch, ensuring that all modifications are integrated and tested.

Deployment Process

The deployment process within the Platform project environment is designed to be intuitive and efficient, regardless of whether you are using manual or automatic deployment modes.

  • Manual Deployment:

    • Push your changes to the GitLab branch associated with the project environment.
    • Deploy the undeployed commits manually with Enterprise Platform.
    • Verify that the deployment was successful and thoroughly test the changes in the project environment.

  • Automatic Deployment:

    • Push your changes to the GitLab branch associated with the project environment.
    • The commits will be automatically deployed to the project environment.
    • Verify that the deployment was successful and thoroughly test the changes in the project environment.