Skip to main content
You may need to change or test behavior in one of the Unleash Commerce packages, such as Core or Admin, while working on your Laravel application. This page explains how to run your app against local package checkouts so you can iterate, verify, and ship those package changes safely.

​
Prerequisites

  • A Laravel application using ddev
  • Local checkouts of unleash-commerce-core and unleash-commerce-admin
Keep your application and packages as siblings:
workspace
your-laravel-app
composer.json
composer.local.json
.ddev
docker-compose.packages.yaml
packages
unleash-commerce-core
unleash-commerce-admin
The starter kit already includes local package support out of the box (ddev volume mount + Composer merge setup). To opt in to local package development, you only need these steps:
  1. Copy the local Composer overrides file:
cp composer.local.json.example composer.local.json
  1. Update the package dependencies:
ddev composer update esign/unleash-commerce-core esign/unleash-commerce-admin
If you hit a Composer repository-priority error while using local path repositories, check composer.local.json. In this setup, Core is aliased to satisfy Admin’s current Core requirement:
{
  "require": {
    "esign/unleash-commerce-core": "dev-master as 0.1.1",
    "esign/unleash-commerce-admin": "dev-master"
  }
}
This can still happen even when using ranges like ^0.1.1 if the path repository is canonical and exposes only a dev-* version that does not match the requested constraint. Keep the alias in sync with Admin’s Core constraint when that constraint changes.
Do not commit a composer.lock that includes local path references (for example /packages/...). Those references are local-only and will break installs in CI, staging, and production. See Make package changes available beyond local development for safe alternatives.

​
Make package changes available beyond local development

When you want to validate your package changes outside your local machine (for example in CI, staging, or production), switch from local path references to a Git-based package version. First, if you enabled local overrides through composer.local.json, remove that file: 
rm composer.local.json
You have two options:
  1. Use a feature branch
ddev composer require esign/unleash-commerce-core:dev-feature/my-change
ddev composer require esign/unleash-commerce-admin:dev-feature/my-change
  1. Use a tagged release
ddev composer require esign/unleash-commerce-core:^0.1.3
ddev composer require esign/unleash-commerce-admin:^0.1.4
After switching, run ddev composer update esign/unleash-commerce-core esign/unleash-commerce-admin and commit the resulting composer.lock.

​
Not using the starter kit?

If your project is not based on the starter kit, follow the full setup below.

​
Configure ddev volume mounting

Because ddev cannot follow symlinks that point outside the container, expose your packages directory inside the container. Create .ddev/docker-compose.packages.yaml in your Laravel app: 
services:
  web:
    volumes:
      - "../../packages:/packages"
Then restart ddev: 
ddev restart

​
Register local path repositories

Update your Laravel app composer.json with path repositories: 
{
  "repositories": {
    "esign/unleash-commerce-core": {
      "type": "path",
      "url": "/packages/unleash-commerce-core",
      "options": {
        "symlink": true
      }
    },
    "esign/unleash-commerce-admin": {
      "type": "path",
      "url": "/packages/unleash-commerce-admin",
      "options": {
        "symlink": true
      }
    }
  },
  "minimum-stability": "dev",
  "prefer-stable": true
}

​
Require local package versions

Install both packages from your local checkouts: 
ddev composer update esign/unleash-commerce-core esign/unleash-commerce-admin
If you are setting up unleash-commerce-admin itself for local package development, you can also run: 
bash setup.sh

​
IDE support (VS Code + Intelephense)

Because path-repository symlinks are created inside the ddev container (and not on your local filesystem), your IDE may not detect classes from the Core or Admin packages. Add the package source paths explicitly to restore indexing and autocomplete. In your Laravel application project, create or update .vscode/settings.json and configure both package source paths: 
{
  "intelephense.environment.includePaths": [
    "/path/to/your/packages/unleash-commerce-core/src",
    "/path/to/your/packages/unleash-commerce-admin/src"
  ]
}

​
Next steps

After installation, continue with package-specific setup: