DOCS / TUTORIAL

Getting started in PHP

Install packvium/packvium, build items and containers as immutable value objects, call Packer::pack(), and read why an item was left out.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

Runs on PHP 7.3 through 8.5. One package name selects the right internals for your PHP_VERSION_ID — there is no separate legacy package to choose.

composer require packvium/packvium

02Build items and containers#

Item::create and Container::create are named constructors on immutable value objects. A weight string like '500 g' is parsed exactly, the same as a dimension.

use Packvium\Config\PackingConfig;
use Packvium\Domain\Container;
use Packvium\Domain\Dimensions;
use Packvium\Domain\Item;
use Packvium\Packer;

$items = [Item::create('sku', Dimensions::mm('100', '80', '40'), '500 g', quantity: 4)];
$containers = [Container::create('box', Dimensions::mm('250', '200', '100'), maxPayload: '10 kg')];

03Run pack() and read the result#

complete() is true only when every item is placed. toArray() gives you the same JSON-shaped structure every other engine returns, ready to log or compare.

$result = (new Packer(PackingConfig::balanced()))->pack($items, $containers);

var_dump($result->complete(), $result->toArray());

04Handle items the engine could not place#

Every entry in $result->unpacked carries a reason code. Explain::unpackedItem turns it into a sentence, so a refusal reaches a human without teaching them the reason vocabulary first.

use Packvium\Explain\Explain;

foreach ($result->unpacked as $unpacked) {
    printf("%s: %s\n", $unpacked->instance->item->id, Explain::unpackedItem($unpacked));
}

05What is already checked before you see it#

Every placement pack() returns has been re-checked by validation logic independent of the search that found it. The fixture pages on this site show that validator's verdict next to the engine's for the same request, so a wrong placement is not something you have to take on trust.

06Check a result yourself#

From 1.7.0 the reference validator ships in the package, on PHP 7.3 and later. validate($request, $result) reads the decoded JSON documents, shares no code with the engine that packed them, and returns a ResultIssue for every problem it finds; an empty array means the result is valid. A result without the documented shape throws MalformedResult.

use Packvium\Serialization\ArrayCodec;
use function Packvium\Validation\validate;

$result = ArrayCodec::pack($request);
foreach (validate($request, $result) as $issue) {
    echo $issue->code, ': ', $issue->detail, PHP_EOL;
}

07Next steps#

Read the request and result contract for every public field, run your own dimensions in the Playground, or open examples/constraints.php for stacking, tags and top-load limits using this same reason-reading pattern.