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/packvium02Build 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.