Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 30 ยท Getting Started

Setting Up a Development Environment

Set up a local PrestaShop with Docker or a classic stack, turn on dev mode and debugging, clear caches and use the console. Includes a requirements checker.

To write modules you need a PrestaShop that you can break. Never develop on a live shop: a typo in a hook can take the whole storefront down, and the products and orders there belong to real people. A local installation costs nothing, lets you reset the database whenever you like, and makes the error messages visible instead of hiding them.

In this lesson you will see two ways to get a local PrestaShop (Docker, or a classic PHP and MySQL stack), how to switch on the developer settings, how the caches behave, and how to use the console. Since the real installation cannot run on this site, the commands are shown read-only, and the runnable parts are stand-ins: a requirements checker and a small cache simulator that shows why "my change does not appear" is so common.

What you need

A PrestaShop installation needs:

  • PHP in a version supported by your PrestaShop release, with several extensions (typically curl, dom, fileinfo, gd, intl, json, mbstring, openssl, pdo_mysql, simplexml, zip and iconv).
  • MySQL or MariaDB, again in a version from the compatibility chart.
  • A web server: Apache or nginx. Apache with mod_rewrite is the easiest, because PrestaShop writes an .htaccess file for friendly URLs.
  • Enough PHP memory, with memory_limit of at least 256 MB (more when you import data) and a sensible max_execution_time.

Exact version ranges change with each release, so do not memorize them. The official compatibility chart in the documentation lists, for every PrestaShop version, the supported PHP and database versions. Check it before you pick your tools. A common mistake is to run the newest PHP release with an older shop: the install may run, but a module error then looks like your bug when it is really a version mismatch.

Develop against the same PHP major and minor version as the production server. Many "works on my machine" bugs come from type, deprecation and extension differences between PHP versions.

Option 1: Docker

Docker is the quickest way to get a clean setup that is identical on every computer. The PrestaShop project publishes an official image. A minimal docker-compose.yml looks like this (real configuration, shown read-only; pick an image tag from the list on Docker Hub that matches the version you want to learn):

YAML
# docker-compose.yml
services:
  db:
    image: mysql:8.0            # use a version from the compatibility chart
    environment:
      MYSQL_ROOT_PASSWORD: admin
      MYSQL_DATABASE: prestashop
    volumes:
      - db_data:/var/lib/mysql

  prestashop:
    image: prestashop/prestashop:<tag>
    depends_on:
      - db
    ports:
      - "8080:80"
    environment:
      DB_SERVER: db
      DB_NAME: prestashop
      DB_USER: root
      DB_PASSWD: admin
      PS_DOMAIN: localhost:8080
      PS_INSTALL_AUTO: "1"      # run the installer on first start
      PS_FOLDER_ADMIN: admin-dev
      ADMIN_MAIL: [email protected]
      ADMIN_PASSWD: change-this-password
    volumes:
      - ps_data:/var/www/html
      - ./modules/hellomodule:/var/www/html/modules/hellomodule

volumes:
  db_data:
  ps_data:

Then start it:

Terminal
docker compose up -d
docker compose logs -f prestashop     # watch the automatic installation

After a minute or two, the shop is at http://localhost:8080 and the back office at http://localhost:8080/admin-dev. The last volume line mounts a folder of your computer into the shop's modules directory, so you edit the code in your editor and PrestaShop sees it at once.

Notes that save time:

  • The email and password are for your local shop only. Use throwaway values; never reuse a real password.
  • The image's variables and defaults can change between releases. Read the image's page on Docker Hub for the current list.
  • The admin folder name is part of your security. The installer picks a random one unless you set it, and production shops should never use a guessable name such as admin.

Option 2: a classic stack

If you prefer a PHP and MySQL stack you already have (for example a local Apache with PHP, or a development tool that provides them), the steps are:

  1. Create an empty database and a user for it.
  2. Download the release ZIP of PrestaShop from the project's download page. It contains an installer ZIP; unpack it into the web root.
  3. Open the site in the browser and follow the installation wizard (language, requirements check, database, shop details).
  4. When it finishes, delete the install folder as the wizard tells you. The shop refuses to work while it exists.

The wizard has a built-in requirements check, which is a good first debugging tool when something is wrong with your PHP configuration.

Developer settings

A fresh PrestaShop is configured for production: it hides errors and caches aggressively. For development you want the opposite. There are two places.

Dev mode in the configuration file. In config/defines.inc.php there is a constant that controls the mode (shown read-only; in your version the line may sit in a slightly different place, so search the file for it):

PHP
// config/defines.inc.php
define('_PS_MODE_DEV_', true);   // show PHP errors and enable the Symfony debug toolbar

With dev mode on, PHP errors and exceptions are displayed instead of a bland "an error occurred" page, and the Symfony part of the back office switches to its development environment, including the debug toolbar at the bottom of Symfony pages with request, database and event details.

The Performance page in the back office. Under Advanced Parameters > Performance you will find:

  • Smarty cache and compilation: set "Force compilation" so template edits take effect on every request, and turn the template cache off while you work.
  • Debug mode toggle, which does what the constant above does (in a database-backed way, depending on the version).
  • CCC (combine, compress, cache) options for CSS and JavaScript. Keep these off in development, otherwise your edited CSS file is hidden behind a combined cached copy.

Never enable dev mode on a live shop. Error pages can expose file paths, SQL statements and configuration to visitors. If you must debug production, log to a file and read it from the server.

Caches: the usual suspect

When you change a template and the page looks the same, a cache is almost always the reason. PrestaShop has several layers:

  • Smarty compiled templates (var/cache/<env>/smarty/compile), regenerated when a template changes, if the settings allow.
  • Smarty cache of rendered output.
  • Symfony cache (var/cache/dev or var/cache/prod), which holds compiled routes, service containers and Twig templates. Changing service definitions or YAML routing files needs this cache cleared.
  • Database query cache and a possible object cache (Redis and similar) in production.
  • Browser and CDN caches for CSS and JavaScript.

You clear them from the back office (Advanced Parameters > Performance > Clear cache) or from the console:

Terminal
php bin/console cache:clear          # the Symfony cache for the current environment
php bin/console cache:clear --env=prod

In the Docker setup, run it inside the container:

Terminal
docker compose exec prestashop php bin/console cache:clear

A practical habit: when a change does not show, clear the cache first, then check the browser cache with a hard reload, and only then suspect your code.

The simulator below makes the effect visible. It is a stand-in with an invented "render with cache" function, not PrestaShop code.

PHP Why an edit seems to have no effect

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The console and logs

PrestaShop ships a Symfony console at bin/console. Beyond clearing the cache, it can manage modules, which is the quickest way to reinstall your module while testing (these are real commands, read-only here):

Terminal
php bin/console prestashop:module list
php bin/console prestashop:module install hellomodule
php bin/console prestashop:module uninstall hellomodule
php bin/console prestashop:module reset hellomodule

Run php bin/console list to see everything available in your version; the exact set differs between releases. Logs live under var/logs/. When a blank page appears, read the newest log file there and your web server's error log before anything else.

You also want some tooling around the shop: Composer (for module dependencies and autoloading), Xdebug (a step debugger), and a code editor with PHP support. We return to quality tools in Testing Modules.

A requirements check you can run

The installer checks PHP and extensions before it lets you continue. The stand-in below does the same kind of check on data you supply. In the real world, you would read PHP_VERSION and get_loaded_extensions(); here the environment is a plain array, so that the output is the same every time. The required versions are invented for the example; always use the chart for your release.

PHP A requirements checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

A good daily workflow

  1. Keep the module in its own folder (ideally its own Git repository) and mount or symlink it into modules/.
  2. Edit code, then reload. If nothing changes, clear the cache.
  3. Reinstall the module (prestashop:module reset) when you change what install() does, because install code runs only once.
  4. Read var/logs/ and the PHP error log, not only the browser.
  5. Keep dev mode on locally, off in production, and test with it off before you ship.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you develop modules on a local installation instead of a live shop?

    A broken hook or a bad query on a live shop hurts real customers. A local copy can be reset at any time.
  2. 2. A template edit does not appear in the browser. What should you check first?

    Several cache layers sit between your file and the page. Clearing them and bypassing the browser cache solves most cases.
  3. 3. Which statement about dev mode is correct?

    Dev mode exposes errors and internals, which is useful locally and dangerous on the public internet.
  4. 4. After installing the PrestaShop wizard on a classic stack, what must you do?

    PrestaShop will not work while the install folder exists. Removing it is part of finishing the setup.

Summary

  • Develop locally, with the PHP and database versions from the compatibility chart.
  • Docker gives a repeatable setup; a classic stack works too. Delete the install folder after the wizard.
  • Turn on dev mode (_PS_MODE_DEV_) and disable template caching and asset combining while you work; never do so in production.
  • Several caches exist; php bin/console cache:clear and the Performance page clear them.
  • bin/console prestashop:module installs, uninstalls and resets modules; logs are under var/logs/.

Next: Anatomy of a Module