PrestaShop Development Guide

Complete guide for setting up and working with PrestaShop development environment.

Table of Contents

• Prerequisites
• Quick Start
• Architecture
• Makefile Commands
• Environment Configuration
• Development Workflow
• Troubleshooting

Prerequisites

• Docker Desktop (with Docker Compose)
• Git
• Make (usually pre-installed on macOS/Linux)

Quick Start

1. Clone and Start

git clone https://github.com/PrestaShop/PrestaShop.git
cd PrestaShop
make docker-start

2. Access Your Installation

• Frontend: http://localhost:8001
• Backend: http://localhost:8001/admin-dev
• MailDev: http://localhost:1080 (email testing)
• Database: localhost:3306

Default Admin Credentials:

• Email: [email protected]
• Password: Correct Horse Battery Staple

Architecture

The setup includes three services:

• prestashop-git: PHP 8.1 + Apache + Node.js 20
• mysql: MySQL 8 database
• maildev: Email testing service

File Structure

.docker/                         # Docker configuration
├── Dockerfile                   # PHP container definition
└── install/                     # Installation scripts

docker-compose.yml               # Base configuration
docker-compose.override.yml.dist # Development overrides
Makefile                         # Development commands

Makefile Commands

Quick Reference

make help # Show all available commands

Docker Commands

Asset Management

PrestaShop Installation

Composer & Symfony

Testing

Code Quality

Environment Configuration

Development Workflow

Initial Setup

make docker-start       # Build, start containers and install assets and database fixtures

Daily Development

make docker-up          # Start containers
make cc                 # Clear Symfony's cache
make test               # Run tests
make cs-fixer           # Fix code style

Asset Building

The asset build system provides a simple and reliable way to build all assets:

• Always Fresh: Assets are always rebuilt to ensure consistency
• Parallel Execution: Multiple assets build in parallel for faster builds
• Clean Builds: Node modules are cleaned and reinstalled for each build

Examples:

# Build all assets
make assets
# Build Admin default theme
make admin-default

# Direct script usage (dry-run by default. Use --force to force rebuild)

# All assets
./tools/assets/build.sh # dry-run
./tools/assets/build/sh --force

# Specific asset
./tools/assets/build.sh admin-default # dry-run
./tools/assets/build.sh admin-default --force

Performance Tips

• Use make test-unit for faster test runs during development
• Use make cs-fixer-dry to check code style without modifying files

Troubleshooting

Docker Issues

Container Won't Start

Solutions:

1. Clean Docker cache:

   bashCopy

   docker system prune -f
   docker volume prune -f
   

2. Rebuild from scratch:

   bashCopy

   make docker-down
   docker system prune -af
   make docker-start
   

Port Already in Use

Solutions:

1. Check what's using the port:

   bashCopy

   lsof -i :8001
   

2. Stop conflicting services:

   bashCopy

   docker ps
   docker stop <container-id>
   

Image Build Fails

Solutions:

1. Increase Docker resources:

   • Open Docker Desktop settings
   • Increase memory to at least 4GB

2. Check network connectivity:

   bashCopy

   curl -I https://deb.nodesource.com
   

Database Issues

Database Connection Failed

Solutions:

1. Check database container:

   bashCopy

   docker ps | grep mysql
   docker logs prestashop-mysql-1
   

2. Reset database:

   bashCopy

   make docker-down
   docker volume rm prestashop_db-data
   make docker-up
   

3. Check database credentials:

   bashCopy

   docker compose exec prestashop-git env | grep DB_
   

Database Data Lost

If your database is corrupted / data is lost, you can reset your data by running the following command:

make install-prestashop

Asset Build Issues

Node.js Dependencies Missing

Solutions:

1. Install Node.js dependencies:

   bashCopy

   make assets
   

2. Restart Docker containers:

   bashCopy

   make docker-restart
   

Asset Build Fails

Solutions:

1. Check for syntax errors:

   bashCopy

   make assets
   

2. Rebuild specific assets:

   bashCopy

   make admin-default
   make front-classic
   

3. Restart Docker containers:

   bashCopy

   make docker-restart
   

Permission Issues

File Permission Errors

Solutions:

1. Fix ownership:

   bashCopy

   sudo chown -R $USER:$USER .
   

2. Fix permissions:

   bashCopy

   find . -type d -exec chmod 755 {} \;
   find . -type f -exec chmod 644 {} \;
   chmod +x .docker/docker_run_git.sh
   

Cache Directory Issues

Solutions:

1. Clear cache:

   bashCopy

   make cc
   

2. Fix cache permissions:

   bashCopy

   make sh
   chmod -R 777 var/cache
   chmod -R 777 var/logs
   

Development Tools Issues

Xdebug Not Working

Solutions:

1. Enable Xdebug:

   bashCopy

   export INSTALL_XDEBUG=true
   make docker-start
   

2. Check Xdebug configuration:

   bashCopy

   make docker-sh
   php -i | grep xdebug
   

PHPUnit Test Issues

Solutions:

1. Run specific test groups:

   bashCopy

   make test-unit
   make test-integration
   

2. Check test database:

   bashCopy

   make docker-sh
   php bin/console doctrine:database:create --env=test
   

3. Run tests with custom options:

   bashCopy

   # Run specific test files or classes
   composer run unit-tests -- --filter=ClassName
   composer run integration-tests -- --filter=ClassName
   
   # Run with specific options
   composer run unit-tests -- --stop-on-failure
   composer run integration-tests -- --stop-on-failure
   

Getting Help

If you're still experiencing issues:

1. Check logs:

   bashCopy

   make docker-logs
   docker logs prestashop-prestashop-git-1
   docker logs prestashop-mysql-1
   

2. Search existing issues:

   • GitHub Issues
   • PrestaShop Forums

3. Ask for help:

   • PrestaShop Slack
   • GitHub Discussions