README

The MyParcel PDK (Plugin Development Kit) is meant for developing entire plugins on PHP E-Commerce platforms. If you're just looking to connect to our API without creating an entire plugin, you should check out our php SDK.

Requirements

• PHP 7.4 – 8.5
• Composer

Documentation

For examples, guides and in-depth information, visit our Plugin Development Kit (PDK) documentation.

Support

Create an issue or contact us via our Developer Portal contact page.

Contributing

View our contribution guidelines for information on how to contribute to the PDK.

Prerequisites

• Node 18
• Yarn
• Docker

Installation

Create .env:

cp .env.template .env

Install Yarn dependencies:

yarn

Install Composer dependencies:

docker compose up php

Running tests

Run all tests:

docker compose run php composer test

Testing on a specific PHP version

The default PHP version is 7.4. To test on a different version, change PHP_VERSION in .env and rebuild:

docker compose build
docker compose run php composer test

Adding a shipment option

Shipment options are managed through the OrderOptionDefinitionInterface system. Each option is a single Definition class that declares all its keys (shipment, capabilities, carrier settings, product settings, allow, price). All models, views, and services build their attributes and form elements dynamically from these definitions.

To add a new option:

1. Create a Definition class in src/App/Options/Definition/ extending AbstractOrderOptionDefinition. Only two methods are required:
   • getShipmentOptionsKey() — the PDK-internal key, derived from Str::camel(RefShipmentShipmentOptions::attributeMap()['sdk_key'])
   • getCapabilitiesOptionsKey() — the V2 capabilities key, from RefCapabilitiesContractDefinitionsResponseOptionsOptionsV2::attributeMap()['capabilities_key']
2. Register it in the orderOptionDefinitions array in config/pdk-business-logic.php.
3. Optionally, add a deprecated constant to ShipmentOptions if platform integrations reference the key directly.

Everything else (carrier settings, product settings, allow/price toggles, validation, frontend form fields, API export/import) is derived automatically. Run yarn test:unit to verify the consistency tests pass.

If the option is not yet in the SDK types, update the SDK or regenerate the OpenAPI types first.

Using Claude Code? Run /add-shipment-option for a guided step-by-step walkthrough that asks the right questions and generates the code.

Writing a migration

Migrations are tracked by identity in an applied_migrations setting and run exactly once per install, independent of the plugin version. There are two kinds:

• Timestamped migrations (preferred) — a file named YYYY_MM_DD_HHMMSS_<slug>.php in a plugin's src/Migration/ that returns an anonymous class extending AbstractTimestampedMigration. The PDK auto-discovers them and runs each once regardless of version, so they fire even on release-candidate builds where version comparison is unreliable.
• Versioned migrations — classes implementing UpgradeMigrationInterface with a getVersion(). Deprecated: prefer a timestamped migration for new work.

To scaffold a timestamped migration, run this from a plugin checkout with the PDK dev-linked (pdk-dev-on):

composer console generate:migration <slug>

It creates src/Migration/YYYY_MM_DD_HHMMSS_<slug>.php with empty up()/down() methods — implement up(); down() is optional and defaults to a no-op. Run composer console help generate:migration for the available options.

Linting

We use Prettier to format .json, .yml, .md and .html files.

Make sure Prettier is enabled in your IDE and runs on the following files:

{**/*,*}.{md,html,yml,json}

Set up Git hooks to run Prettier on each commit, correcting any formatting issues.

yarn prepare

You can also run Prettier manually:

# Check formatting issues
yarn lint

# Fix formatting issues
yarn lint:fix