Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
449 lines (339 loc) · 11.4 KB

DEVELOPMENT.md

File metadata and controls

449 lines (339 loc) · 11.4 KB
Raw

PrestaShop Development Guide

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

Table of Contents

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

Default Admin Credentials:

  • Email: demo@prestashop.com
  • Password: Pr3st4Sh0P

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

Command Description
make docker-build Build Docker images from scratch
make docker-up Start containers in detached mode
make docker-start Build and start containers
make docker-restart Restart the docker hub
make docker-down Stop and remove containers
make docker-logs Show live container logs
make docker-bash Connect to PHP container via bash

Asset Management

Command Description
make assets Build all assets (admin + front)
make assets-clean Build all assets, forcing a clean reinstall of node_modules
make wait-assets Wait for assets to finish building
make admin Build admin assets (default + new theme)
make front Build front assets (core + classic + hummingbird)
make admin-default Build default admin theme assets
make admin-new-theme Build new admin theme assets
make front-core Build core front theme assets
make front-classic Build classic front theme assets
make front-hummingbird Build hummingbird theme assets
make watch-admin-default Watch and rebuild default admin theme assets
make watch-admin-new-theme Watch and rebuild new admin theme assets
make watch-front-core Watch and rebuild core front theme assets
make watch-front-classic Watch and rebuild classic front theme assets
make watch-front-hummingbird Watch and rebuild hummingbird theme assets

The watch-* targets rebuild one theme on every change and stay in the foreground until you stop them with Ctrl+C. They write unminified development assets, and leave a .ps-dev-build marker in the theme so the next build knows the assets on disk are not a finished build: run the matching build target before committing or releasing.

Stop a watch with Ctrl+C from the terminal that started it. docker exec does not forward signals, so interrupting a watch started without a terminal attached (CI, an IDE task runner) leaves the watcher running inside the container, where it will keep overwriting the built assets.

PrestaShop Installation

Command Description
make install Install PHP dependencies and build assets
make install-prestashop Install fresh PrestaShop database

Composer & Symfony

Command Description
make composer Install PHP dependencies
make cc Clear Symfony cache

Testing

Command Description
make test Run all tests (unit + integration)
make test-unit Run unit tests
make test-integration Run integration tests
make test-integration-behaviour Run integration behaviour tests
make test-api-module Run API module tests

Code Quality

Command Description
make cs-fixer Run PHP CS Fixer
make cs-fixer-dry Run PHP CS Fixer (dry run)
make phpstan Run PHPStan analysis
make scss-fixer Fix SCSS files
make es-linter Fix ESLint issues

Environment Configuration

Category Variable Default Description
Database DB_PASSWD prestashop Database password
DB_NAME prestashop Database name
DB_SERVER mysql Database host
DB_PREFIX ps_ Database table prefix
PrestaShop PS_INSTALL_AUTO 1 Auto-install PrestaShop
PS_DOMAIN localhost:8001 Shop domain
PS_FOLDER_INSTALL install-dev Install folder
PS_FOLDER_ADMIN admin-dev Admin folder
PS_COUNTRY fr Shop country
PS_LANGUAGE en Installation language
PS_DEV_MODE 1 Development mode
PS_ENABLE_SSL 0 Enable SSL
PS_ERASE_DB 0 Erase database on install
PS_USE_DOCKER_MAILDEV 1 Use MailDev for emails
Admin ADMIN_MAIL demo@prestashop.com Admin email
ADMIN_PASSWD Pr3st4Sh0P Admin password
Development VERSION 8.1-apache PHP version
NODE_VERSION 20.19.5 Node.js version
INSTALL_XDEBUG false Install Xdebug
BLACKFIRE_ENABLE 0 Enable Blackfire profiling
BLACKFIRE_SERVER_ID 0 Blackfire server ID
BLACKFIRE_SERVER_TOKEN 0 Blackfire server token
USER_ID 1000 User ID for container
GROUP_ID 1000 Group ID for container
DISABLE_MAKE 0 Disable make commands
PS_HOSTNAME localhost Container hostname

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
  • Incremental Installs: npm ci only runs when a theme's dependencies actually changed, so repeated builds are much faster

Examples:

# Build all assets
make assets
# Build all assets, forcing a clean reinstall of node_modules
make assets-clean
# Build Admin default theme
make admin-default
# Watch and rebuild the core front theme on every change (Ctrl+C to stop)
make watch-front-core

# 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

# Force a clean reinstall of node_modules (implies --force)
./tools/assets/build.sh --force-install
./tools/assets/build.sh admin-default --force-install

# Watch a single asset (development build)
./tools/assets/build.sh admin-default --watch

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:

    docker system prune -f
docker volume prune -f

  2. Rebuild from scratch:

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

Port Already in Use

Solutions:

  1. Check what's using the port:

    lsof -i :8001

  2. Stop conflicting services:

    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:

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

Database Issues

Database Connection Failed

Solutions:

  1. Check database container:

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

  2. Reset database:

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

  3. Check database credentials:

    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:

    make assets

  2. Restart Docker containers:

    make docker-restart

Asset Build Fails

Solutions:

  1. Check for syntax errors:

    make assets

  2. Rebuild specific assets:

    make admin-default
make front-classic

  3. Restart Docker containers:

    make docker-restart

Permission Issues

File Permission Errors

Solutions:

  1. Fix ownership:

    sudo chown -R $USER:$USER .

  2. Fix permissions:

    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:

    make cc

  2. Fix cache permissions:

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

Development Tools Issues

Xdebug Not Working

Solutions:

  1. Enable Xdebug:

    export INSTALL_XDEBUG=true
make docker-start

  2. Check Xdebug configuration:

    make docker-sh
php -i | grep xdebug

PHPUnit Test Issues

Solutions:

  1. Run specific test groups:

    make test-unit
make test-integration

  2. Check test database:

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

  3. Run tests with custom options:

    # 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:

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

  2. Search existing issues:

  3. Ask for help: