Handles both a single line array and an array of lines — the two shapes a BusinessDocument documentLines payload can take.

The line is built through Reflection::hydrate() rather than the BusinessDocumentLine constructor : only that path honors the #[HydrateAs] / #[HydrateWith] attributes declared on the class, so adjustments, price (and its priceComponent breakdown), quantity, subtotal, taxes and total come out typed instead of staying raw arrays.

The item property is the exception : its Product|Service union cannot be resolved from the property type alone, so it is delegated to hydrateDocumentLineItem() which reads the payload's @type. That delegation happens only when the raw payload holds an array under item — when there is something to hydrate — and its answer is then written as is, null included : an array that resolves to nothing becomes null, never a leftover raw array. Anything else is left to whatever Reflection::hydrate() made of it.

🔑 An empty list is kept as an empty list, where the rest of the family answers null. « This document has no line » is an answer, and it is not the answer « nothing here was readable » : a consumer mapping over the value deserves the empty list it can map over, and a document born empty is the ordinary state of a draft rather than an anomaly. A non-empty list that hydrates to nothing keeps the family's null — there, nothing usable was found, which is a different statement.

🔑 A bare reference survives inside a list, exactly as it does on its own : a list of unresolved handles comes back as it stands, and only an entry that was an array and resolved to nothing is dropped. The keys stay gap-free — a filtered list left with holes serializes as a JSON object, and a consumer walking the value gets something it cannot walk.