It may be easiest to start with an example.
The entity_metadata_wrapper() function seems to do a lot of complex magic behind the scenes in order to return an object with all data related to the entity in question. But how do I know what properties and methods are available to me once the object is returned?
Let's say I have Commerce Order. (This is not necessarily a Commerce question, it's just good for an example). On checkout I want to check that the order contains a line item of a given product type and notify the user. Maybe I also want to compare the calculated lined item price with the original price in the product type.
Ok, so that's Order, Line Item(s), Product Type, and User that are all referenced entities. The Product type has multiple custom fields, maybe those are references to another entity like the billing information.
$order_wrapper = entity_metadata_wrapper('commerce_order', $order);
According to the Entity API docs, all of those referenced entities are now included in the object ready for me to use thanks to the wrapper.
But how do I know how to access a value I'm looking for or where it is in the object structure? Are all referenced drupal fields their machine name by design? I know chaining has to play a part, so how does that factor in? And wouldn't this structure change every time entity_metadata_wrapper is called given that the entity in question could arbitrarily reference other entities (that reference other entities, etc)? And if the structure is arbitrary, any code that relied on that structure at a given time, if it changes, won't that break the code?
Finally, I see references to things like ->save() and ->value() in the Entity API docs, but I cannot find a reference to the full set of methods available to me. Is there any logical structure to figuring this out or do I need to use something like xdebug each time (and if I do, that still doesn't let me know what methods are available to me to act on the data). This is for D7, but if a D8+ answer could add clarity, please provide.
