Intended delete() behavior?

[cxj]

The AbstractGateway delete and hence the mapper delete assume the object being passed provides the ID which should match a synthetic primary key for the row, but the examples and documentation seem to suggest a different behavior. That is, one can pass an object to AbstractMapper::delete and an obvious assumption from examples and code comments is that ONLY that object (row) will be deleted.

But this is not the case for some tables where there is not a unique row for each object's primary column. Instead, all rows matching are deleted.

This behavior can make sense if it is clearly documented, although it will also be a severe limitation.

For example, how does one handle a table where a pair of columns form the primary key? This is often the case in tables which express a 1:N relationship between two objects, where the real primary keys of each object are foreign keys in the relationship table. Both will be duplicated across rows in that table, but as a pair will always be unique.

For example, an invoice of items. The invoice ID will occur multiple times for for an invoice with more than one item, and the ID of an item may appear on more than one invoice.

getPrimaryCol is not able to handle anything other than a single column name.

I called $mapper->delete($myObject) with $myObject containing just the 2 columns which form the primary key to the table, expecting it to delete that single row. Instead, it deleted all rows matching just the first column (primary column).

Now that I know how it works, I can live with it for this particular usage. But it would be nice to more generally define what the limitations and real API are. With some guidance, I'd be happy to create some documentation for this.