Permalink
Browse files

Add in-progress v3 info to docs

  • Loading branch information...
dvdoug committed Aug 27, 2017
1 parent e04a456 commit 15d6df8a0d0464adb356a7b59a46cdbc308ace57
Showing with 117 additions and 16 deletions.
  1. +3 −2 CHANGELOG.md
  2. +1 −1 README.md
  3. +26 −4 docs/advanced-usage.rst
  4. +2 −2 docs/conf.py
  5. +3 −3 docs/getting-started.rst
  6. +5 −0 docs/index.rst
  7. +6 −1 docs/installation.rst
  8. +71 −3 docs/whatsnew.rst
View
@@ -1,10 +1,11 @@
# Changelog
## [Unreleased]
## [3.0.0] - Unreleased
### Added
- Introduced `PackedItem`s which are a wrapper around `Item`s with positional and dimensional information (x,y,z co-ordinates of corner closest to origin, width/length/depth as packed)
### Changed
- `PackedBox` now contains a `PackedItemList` of `PackedItem`s (rather than an `ItemList` of `Item`s)
- `ConstrainedItem->canBePackedInBox` now takes a `PackedItemList` of `PackedItem`s (rather than an `ItemList` of `Item`s)
- Minimum PHP version is now 7.1
## [2.4.0] - 2017-08-14
@@ -146,7 +147,7 @@ Initial release
- Experimental code to get a feel for how calculations can best be implemented
- Only works if all items fit into a single box (so not production ready at all)
[Unreleased]: https://github.com/dvdoug/BoxPacker/compare/2.4.0...master
[3.0.0]: https://github.com/dvdoug/BoxPacker/compare/2.4.0...master
[2.4.0]: https://github.com/dvdoug/BoxPacker/compare/2.3.2...2.4.0
[2.3.2]: https://github.com/dvdoug/BoxPacker/compare/2.3.1...2.3.2
View
@@ -7,7 +7,7 @@ them all in taking into account physical dimensions and weights.
Especially useful for e.g. e-commerce contexts when you need to know box size/weight to calculate shipping costs, or
even just want to know the right number of labels to print.
See [documentation](http://boxpacker.readthedocs.io/en/latest/) for more details.
See [documentation](http://boxpacker.readthedocs.io/) for more details.
[![Build Status](https://travis-ci.org/dvdoug/BoxPacker.svg?branch=master)](https://travis-ci.org/dvdoug/BoxPacker)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/dvdoug/BoxPacker/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/dvdoug/BoxPacker/?branch=master)
View
@@ -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->getItems();
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
------------------
@@ -58,16 +80,16 @@ Example - only allow 2 batteries per box
{
/**
* @param ItemList $alreadyPackedItems
* @param TestBox $box
* @param PackedItemList $alreadyPackedItems
* @param Box $box
*
* @return bool
*/
public function canBePackedInBox(ItemList $alreadyPackedItems, Box $box)
public function canBePackedInBox(PackedItemList $alreadyPackedItems, Box $box)
{
$batteriesPacked = 0;
foreach ($alreadyPackedItems as $packedItem) {
if ($packedItem instanceof LithiumBattery) {
if ($packedItem->getItem() instanceof LithiumBattery) {
$batteriesPacked++;
}
}
View
@@ -54,9 +54,9 @@
# built documents.
#
# The short X.Y version.
version = u'version 2'
version = u'version 3'
# The full version, including alpha/beta/rc tags.
release = u'version 2'
release = u'version 3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
@@ -58,9 +58,9 @@ Packing a set of items into a given set of box types
echo "The combined weight of this box and the items inside it is {$packedBox->getWeight()}g" . PHP_EOL;
echo "The items in this box are:" . PHP_EOL;
$itemsInTheBox = $packedBox->getItems();
foreach ($itemsInTheBox as $item) { // your own item object, in this case TestItem
echo $item->getDescription() . PHP_EOL;
$packedItems = $packedBox->getItems();
foreach ($packedItems as $packedItem) { // $packedItem->getItem() is your own item object, in this case TestItem
echo $packedItem->getItem->getDescription() . PHP_EOL;
}
}
View
@@ -11,6 +11,11 @@ License
-------
BoxPacker is licensed under the `MIT license`_.
.. warning::
You are reading the documentation for BoxPacker v3 which is under development and has not been released yet. Everything
contained in these pages and in the code is subject to change, and you are highly recommend to use v2 instead.
.. _NP-hard problem: http://en.wikipedia.org/wiki/Bin_packing_problem
.. _MIT license: https://github.com/dvdoug/BoxPacker/blob/master/license.txt
View
@@ -13,7 +13,12 @@ If you don't want to use Composer, the code is available to download from `GitHu
Requirements
------------
BoxPacker is compatible with all versions of PHP 5.4+ (including PHP 7 and HHVM)
BoxPacker v3 is compatible with PHP 7.1+ (including HHVM)
.. note::
Still running an older version of PHP? No problem! BoxPacker v2 is compatible with PHP 5.4 and up, is just as
production-ready, and is actively maintained.
Versioning
----------
View
@@ -3,15 +3,83 @@ What's new / Upgrading
.. note::
Below is summary of important changes between versions. A full changelog, including changes in versions not yet
released is available from https://github.com/dvdoug/BoxPacker/blob/master/CHANGELOG.md
Below is summary of key changes between versions that you should be aware of. A full changelog, including changes in minor
versions is available from https://github.com/dvdoug/BoxPacker/blob/master/CHANGELOG.md
Version 3
---------
.. warning::
Version 3 is **unreleased**. Use v2 instead.
Positional information on packed items
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Version 3 allows you to see the positional and dimensional information of each item as packed. Exposing this additional data
unfortunately means an API change - specifically ``PackedBox->getItems`` now returns a set of ``PackedItem`` s rather than
``Item`` s. A ``PackedItem`` is a wrapper around around an `Item` with positional and dimensional information
(x/y/z co-ordinates of corner closest to origin, width/length/depth as packed). Adapting existing v2 code to v3 is simple:
Before
.. code-block:: php
<?php
$itemsInTheBox = $packedBox->getItems();
foreach ($itemsInTheBox as $item) { // your own item object
echo $item->getDescription() . PHP_EOL;
}
After
.. code-block:: php
<?php
$packedItems = $packedBox->getItems();
foreach ($packedItems as $packedItem) { // $packedItem->getItem() is your own item object
echo $packedItem->getItem->getDescription() . PHP_EOL;
}
If you use ``BoxPacker\ConstrainedItem``, you'll need to make the same change there too.
PHP 7 type declarations
^^^^^^^^^^^^^^^^^^^^^^^
Version 3 also takes advantage of the API break opportunity introduced by the additional positional information and is the first
version of BoxPacker to take advantage of PHP7's type declaration system. The core ``BoxPacker\Item`` and ``BoxPacker\Box``
interfaces definitions have been supplemented with code-level type information to enforce expectations. This is a technical break
only, no implementation requires changing - only the correct type information added, e.g.
Before
.. code-block:: php
<?php
/**
* @return string
*/
public function getDescription()
{
return $this->description;
}
After
.. code-block:: php
<?php
/**
* @return string
*/
public function getDescription(): string
{
return $this->description;
}
Version 2
---------
3D rotation when packing
^^^^^^^^^^^^^^^^^^^^^^^^
Version 2 of BoxPacker introduces a key feature for many usecases, which is support for full 3D rotations of items. Version 1
Version 2 of BoxPacker introduces a key feature for many use-cases, which is support for full 3D rotations of items. Version 1
was limited to rotating items in 2D only - effectively treating every item as "keep flat" or "ship this way up". Version 2
adds an extra method onto the ``BoxPacker\Item`` interface to control on a per-item level whether the item can be turned onto
it's side or not.

0 comments on commit 15d6df8

Please sign in to comment.