Shipment labels for multiple pieces

[mvdnbrk]

@jacobdekeizer I have merged in your PR #10.

We should still address the issue with shipment labels for a parcel with multiple pieces.

[mvdnbrk]

We should take the following steps to tackle this issue:

• Add ShipmentPiece resource. See Add ShipmentPiece resource. #29
• Add a pieces variable to the Shipment class which is a Collection object.
• Update the PiecesCollection class so it can accept an array of Piece objects.
• Update the Shipments endpoint so it adds the pieces from the API response to the pieces of the Shipment resource class.

Above steps can be done without changing the current behavior.
Last we can remove the current behavior and remove barcode and label_id from the Shipment resource class.

[mvdnbrk]

It would also be nice to have some methods for convenience like:

function barcodes(): array  
function labelIds(): array

Backwards compatibility:

function getBarcodeAttribute(): string
function getLabalIdAttribute(): string

The latter would also be nice to have in case you are creating a shipment with just one piece (I am doing this most of the time). In this way you don't have to deal with the array of piece items.

[Thorry84]

I would opt against this, it shouldn't matter in the code if you have a single piece or multiple pieces in a shipment. Having two code paths for two identical situations (from a technical point of view) introduces duplicate code and code smell.

Why would you make your code only work most of the time? Most of the time you have 1 piece, but not all of the time. Since code should work all of the time and not most of the time, it should handle a collection of pieces in a shipment. Since the collection can have 1 item in it, it works perfectly fine all of the time.

Not having to 'deal' with an array of piece items seems like an unavoidable reality and to me doesn't seem like that big of a thing to deal with.

[jacobdekeizer]

@mvdnbrk I'm not a fan of magic methods, because there is no autocompletion for magic methods in any ide. If you wan't to have a method to get the first item of an array, maybe we should make a ResourceCollection which should implement a first() method.

I my opinion we should not worry about backwards compatibility, until we reach version 1.0. We should introduce breaking changes if necessary to create a solid base to work with.

[jacobdekeizer]

* Update the `Pieces` class so it can accept an array of `Piece` or `ShipmentPiece` objects.

In my opinion it should be in seperate classes

[mvdnbrk]

The Pieces class is in fact a collection. It is holding an array of Piece items.

[mvdnbrk]

@Thorry84 I would do something like this.

public function getBarcode()
{
    return $this->pieces->first()->tracker_code;
}

So you can simply do $shipment->getBarcode()
versus $shipment->pieces->first()->tracker_code all the time.

Most of us will create a shipment with just one piece almost anytime I guess.

Side note: I thought creating multiple pieces would create a multi collo shipment.
That was my first thought and made perfectly sense. However it will just create two different parcel parcels with separate tracking codes.

[jacobdekeizer]

@mvdnbrk I don't think that is a good idea. You should provide only one way to retrieve the tracking codes so it doesn't lead to confusion and it is easier to maintain.

In your case it is easier to have a getBarcode() method, but I think there will be many people who don't know in advance how many shipment pieces they are going to make. In my case I need to loop through the order items from a webshop and create a shipment for them.

[mvdnbrk]

@jacobdekeizer You won't create a separate parcel for each item in an order will you?

Typically an order = one parcel.

[jacobdekeizer]

@mvdnbrk An order can have multiple products which can be shipped as multiple pieces. It depends on the size of the product.

[mvdnbrk]

@jacobdekeizer Makes sense 😄

[Thorry84]

My 2 cents: In all use cases I've seen we don't know in advance how many pieces there will be. I guess in most cases it will be 1 piece, but it could be multiple pieces. Since we don't know we should make sure the code handles multiple pieces at any time.

I agree with @jacobdekeizer a single code path is the way to go.

Breaking backwards compatibility isn't something to get hung up on. I would consider it a nice to have, only if it doesn't make the code worse in any way. People can always lock a version or make their own branch if backwards compatibility matters to them.

[tom-it]

I'd be interested in this feature as well, sometimes I need to have 2-3labels for one shipment, it would be great if I could add the quantity and the pieceNumber (or if it would be handled automatically)