ECShopX: a multi model marketplace platform on PHP and Lumen

One backend for business models that usually get separate stacks

ECShopX is described as a powerful and flexibly architected enterprise grade trading marketplace platform, natively supporting over 10 business models including B2C, B2B2C, S2B2C and O2O. The project was developed by ShopeX, and the README credits it with 23 years of practical experience in digital project implementation.

The architectural claim is the interesting one: a unified backend to manage multi-storefront operations, so a company does not run a separate system for its direct to consumer mall, its merchant platform and its store network. The core feature list names Unified Backend Management for models such as B2C, B2B2C and S2B2C, Omni-Channel & Multi-Terminal Adaptation across Mini Programs, apps, H5 pages and PC endpoints with synchronised data, and Multi-Tenant Isolation for independent operation of multiple merchants with strict data and permission isolation.

The use cases in the README show what that means in practice. A B2C brand private domain mall covering official Mini Programs, apps, PC sites and H5. A B2C employee purchase and welfare platform for multi-brand groups. A B2B2C platform with the self-operated plus merchant settlement model. An S2B2C supply chain collaboration platform linking brands, distributors and terminal stores. And two O2O variants, a brand cloud store with instant retail covering online ordering, click-and-collect and instant delivery, and a distributor cloud store for brand owners.

The primary language is PHP, the licence is Apache-2.0, and the repository description states the system is free for commercial use subject to that licence.

The four repository split that defines the project

ECShopX is not a single deployable application, and understanding the split is the first thing an evaluator needs to do.

The project adopts a front-end and back-end separated architecture, consisting of multiple repositories: the PHP backend service, the admin panel frontend, the mobile storefront frontend, and the PC storefront frontend. The README links the three front ends to separate repositories, ECShopX_admin-frontend for the admin panel, ECShopX_mobile-frontend for the WeChat Mini Program and H5, and ECShopX_web-frontend for the web storefront.

That is a deliberate trade-off. Separating the front ends means the storefront code can be rewritten in a different framework without touching the API, and it is the only way to serve a Mini Program, an H5 page and a PC site from one backend with synchronised data. The cost is that a deployment is now several builds rather than one, and the front-end repositories version independently of the backend.

The backend repository itself is a conventional PHP application with a lot of surface. Beyond the usual Laravel-style directories there is `api/`, `app/`, `artisan`, `config/`, `database/`, `public/`, `routes/`, `src/`, `storage/` and `tests/`, plus a set of directories that show how the project is run: `docker-dev/`, `docker-lite/`, `docker-new/`, `baota/` for BaoTa panel deployment, `gitlab-ci/`, and `xhprof/` for profiling. There is a `composer.json` and two bundled composer phar files, `composer.phar` and `composer82.phar`, a `phpunit.xml`, `phpstan.neon` and `psalm.xml` for static analysis, `.php-cs-fixer.dist.php` and `.styleci.yml` for style, and a `tdd-guard/` directory.

The `.env.full` file at the root is the template for configuration, and the CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT-style files and docs directory round out a project with a real development process.

The one command install, and what it actually does

Docker deployment is the recommended path, and the quick install is a single line:

curl -fsSL https://oss.shopex.cn/ecx/install.sh | bash

The prerequisites are Docker and Docker Compose, with Docker Desktop recommended on macOS, and macOS or Linux as the system. The README says to follow the script prompts to deploy the system.

What the script does is listed in five steps. It checks the Docker environment, clones the frontend projects if they are not already present, starts Docker containers for PHP, Nginx, MySQL and Redis, configures the PHP application by installing dependencies, running database migrations and initialising the admin password, and finally builds the frontend projects for the admin panel, H5 and PC storefront.

That list is worth reading closely, because it shows the shape of the deployment. You get four services, a migration step and three frontend builds. The frontend clones land in a directory at the same level as the current project, so the layout of the parent directory matters, and you are prompted to set an admin password during the script execution.

The script also takes options for partial builds:

bash dev-setup.sh --rebuild    # Rebuild images
bash dev-setup.sh --skip-admin # Skip admin panel build
bash dev-setup.sh --skip-vshop # Skip mobile storefront (H5) build
bash dev-setup.sh --skip-pc    # Skip PC storefront build

Skipping builds is what you would use to iterate on one part of the system, and --rebuild is what you need after changing the PHP side.

The time cost is stated: the initial deployment may take 10 to 30 minutes for downloading images, installing dependencies and building the frontend. The port requirements are listed too, with 8080, 8081, 8082, 3306 and 6379 needing to be free.

One practical note about the install command itself. Piping a script from a vendor host into bash means the code that sets up your development machine is fetched at the moment you run it and is not in your checkout. The repository itself contains install.sh and dev-setup.sh, so reading the local copy before running anything is the sensible first step.

Four ports, three front ends, one API

The deployed development environment exposes a fixed set of endpoints:

- Admin Panel: http://localhost:8080 - H5 Frontend: http://localhost:8081 - PC Frontend: http://localhost:8082 - API Endpoint: http://localhost:8080/api/

So the admin panel and the API share port 8080, which means the admin front end is served by the same Nginx that routes API requests, and the two storefronts sit on their own ports.

The operating commands for the running stack are the standard Compose and Docker ones, with the development compose file named explicitly:

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Check service status
docker exec ecshopx-dev supervisorctl status

# Enter container
docker exec -it ecshopx-dev sh

# Stop services
docker-compose -f docker-compose.dev.yml down

# Restart services
docker-compose -f docker-compose.dev.yml restart

The service status command is the one to notice. It runs supervisorctl inside the container, which tells you the state of the individual processes inside the PHP container rather than of the container itself. A container can be up while the application inside it has failed to start, and that is exactly the situation where `docker exec ecshopx-dev supervisorctl status` is the difference between debugging and guessing.

The compose file name in these commands, `docker-compose.dev.yml`, is the development variant, and the repository also ships `docker-dev/`, `docker-lite/` and `docker-new/` directories alongside `deploy.sh`, `pack.sh` and the `baota/` panel configuration. That spread of deployment artefacts is a signal about who this is for: teams that expect to run the system in a Chinese hosting environment with a control panel, not only in a container on a laptop.

Manual deployment and the runtime floor

For self-hosted deployment the README is much briefer. It says you need to set up the backend service and deploy the required frontend applications from their respective repositories, and points back at the project structure section for where those repositories are. The system requirements are listed as PHP 8.2 or newer, Lumen 8.3, MySQL 5.7 or newer and Redis 4.0 or newer.

Lumen is the framework in use, and the version pin of 8.3 is specific enough to matter, since Lumen tracks Laravel's major versions. The PHP 8.2 floor rules out a good deal of older hosting. MySQL 5.7 as a minimum rather than 8.0 is a common choice for a system that supports a range of Chinese hosting providers, and it is worth checking against your provider's default.

The configuration step is a .env file, and the README lists what to update: database settings, Redis settings, and other settings. The repository ships `.env.full` as the template, so the workflow is to copy it, fill in the database and Redis values, and adjust the rest.

The installation section of the README is cut off in what is available here, so the exact command sequence for the manual path is not visible. What is visible is enough to establish the shape: this is a Laravel-flavoured application on Lumen with MySQL and Redis, deployed either through the Docker script or by hand, with the front ends built separately from their own repositories.

Domain modules and the extension surface

The feature list is organised around the parts of a commerce business, and the granularity tells you how much of the domain is already covered.

Store management covers store name, address, store number, self-pickup availability, express delivery availability, merchant self-delivery and store status, plus store code, store payment configuration and store decoration. Product management lists title, SKU code, gift item status, product type, inventory, market price, selling price, store sales status, shelving status and sales category, with batch modification supported. Order management filters by status, covering pending payment, pending delivery, pending refund, pending pickup, cancelled and completed.

Marketing is a set of built-in tools: coupons, points, member levels, group buying and flash sales. Content management provides image, text and video community posting for a private domain social feed, and template management supports custom scenarios and industry templates.

Membership and permissions are handled as two separate concerns. Unified membership marketing integrates membership systems across channels so points, tiers and assets work throughout. Fine-grained permission management covers roles such as platform operators, suppliers, stores and sales advisors, which is a substantial list of actor types and matches the multi-tenant model.

For integration, the README promises a rich set of RESTful APIs for third-party systems such as ERP, WMS and CRM, and a modular design where core functions are highly modular to allow secondary development. There is also an `api/` directory, a `salesperson-api/` directory, a `routes/` directory and a `shop_menu.json`, which suggests the API surface is defined centrally rather than ad hoc per controller.

One file worth a look for anyone evaluating the extension story is `invoice-mig.md`, a document on invoice migration, and `hooks/` for what look like extension points.

Where ECShopX is the wrong choice

The clearest wrong-tool case is a simple single-product storefront. The product is a multi-model, multi-tenant platform with a large admin surface, and running that to sell a small catalogue is a lot of machinery for the job. A hosted platform with a fixed monthly cost and none of this administration would be cheaper in every sense.

The second is multi-tenant isolation as a requirement you assumed. The README says the platform supports independent operations for multiple merchants with strict data and permission isolation, and the module layout backs that up with role types for platform operators, suppliers, stores and sales advisors. But the phrase is a claim, not a specification in the documentation available here. If merchant isolation is contractual for you, that claim needs testing with real data and real roles before you commit, because in a single codebase, one missing tenant filter in one query is enough.

The third is the operational model. This is a self-hosted PHP application with MySQL, Redis, Nginx, three front-end builds and a migration step, and the quick install is a shell script from a vendor host. There is no hosted tier described here, no multi-tenant SaaS control plane, and the guidance in the README is aimed at someone with a server. If nobody on your team is going to own that stack, the operational cost will exceed the licence savings, which are nil either way given the Apache-2.0 grant.

The fourth is the front-end build. Three separate front-end repositories, cloned by the install script and built during it, mean a deployment is only as reliable as three upstream branches. For a team that wants to control its storefront code, that means either forking all three or working within their release cadence, and the version compatibility between the front ends and the backend API is something you will discover at integration time rather than from the README.

The alternative worth naming is the single-model, API-first approach: pick one commerce model, build a small backend with the Open API ECShopX already exposes, and keep the storefront entirely under your own control. The difference in approach is that you give up the admin panel, the ten business models and the multi-tenant machinery, and in exchange you own the whole stack and its shape.

Editorial conclusion

Adopt ECShopX when your business genuinely needs several commerce models running on one backend, when you want multi tenant isolation between merchants rather than separate deployments, and when your team can work in PHP with a Lumen backend. Do not adopt it for a single simple storefront, since the multi model machinery and the admin surface are the product and not incidental, and do not adopt it if you need to avoid running infrastructure yourself, because the quick install is a script from a vendor host that stands up PHP, Nginx, MySQL and Redis on fixed ports. Before deploying, read install.sh and dev-setup.sh before piping them into bash, check that ports 8080, 8081, 8082, 3306 and 6379 are free, and confirm the PHP 8.2 and Lumen 8.3 requirements match your runtime plan.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. ShopeX/ECShopX on GitHub