Expose additional positional info in v2 as requested in #78

docs/advanced-usage.rst

@@ -32,6 +32,28 @@ Example - warning on a massively oversized box
             }
         }
 
+Positional information
+----------------------
+It is also possible to see the precise positional and dimensional information of each item as packed. This is exposed as x,y,z
+co-ordinates from origin, alongside length/width/depth in the packed orientation.
+
+Example
+^^^^^^^
+
+.. code-block:: php
+
+    <?php
+
+        // assuming packing already took place
+        foreach ($packedBoxes as $packedBox) {
+            $packedItems = $packedBox->getPackedItems();
+            foreach ($packedItems as $packedItem) { // $packedItem->getItem() is your own item object
+                echo $packedItem->getItem()->getDescription() .  ' was packed at co-ordinate ' ;
+                echo '(' . $packedItem->getX() . ', ' . $packedItem->getY() . ', ' . $packedItem->getZ() . ') with ';
+                echo 'l' . $packedItem->getLength() . ', w' . $packedItem->getWidth() . ', d' . $packedItem->getDepth();
+                echo PHP_EOL;
+            }
+        }
 
 Custom Constraints
 ------------------

src/PackedBox.php

@@ -7,6 +7,8 @@
 
 namespace DVDoug\BoxPacker;
 
+use RuntimeException;
+
 /**
  * A "box" with items.
  *
@@ -91,6 +93,11 @@ class PackedBox
      */
     protected $usedDepth;
 
+    /**
+     * @var PackedItemList
+     */
+    protected $packedItemList;
+
     /**
      * Get box used.
      *
@@ -261,6 +268,25 @@ public function getVolumeUtilisation()
         return round($itemVolume / $this->box->getInnerVolume() * 100, 1);
     }
 
+    /**
+     * @return PackedItemList
+     */
+    public function getPackedItems()
+    {
+        if (!$this->packedItemList instanceof PackedItemList) {
+            throw new RuntimeException('No PackedItemList was set. Are you using the old constructor?');
+        }
+        return $this->packedItemList;
+    }
+
+    /**
+     * @param PackedItemList $packedItemList
+     */
+    public function setPackedItems(PackedItemList $packedItemList)
+    {
+        $this->packedItemList = $packedItemList;
+    }
+
     /**
      * Legacy constructor.
      *
@@ -328,6 +354,7 @@ public static function fromPackedItemList(Box $box, PackedItemList $packedItems)
             $maxLength,
             $maxDepth
         );
+        $packedBox->setPackedItems($packedItems);
 
         return $packedBox;
     }

tests/PackedBoxTest.php

@@ -37,6 +37,7 @@ public function testGetters()
         self::assertEquals(34, $packedBox->getRemainingDepth());
         self::assertEquals(2540, $packedBox->getRemainingWeight());
         self::assertEquals(5445440, $packedBox->getInnerVolume());
+        self::assertEquals($packedItemList, $packedBox->getPackedItems());
     }
 
     /**