The 3.x ORM documentation is severely lacking considering the dramatic changes from 2.x
(1) There are no complete examples showing how to retrieve recordsets within a controller without using paginate(). It took me trial and error and a lot of piecing together of bits strewn about in the docs and the web to figure out how to make an actual find() call… and I still don't understand how to use this thing and how it differs from the results of a paginate() call or why I can't use a paginate() call in the same way as a find() call.
(2) The new ORM is a black box. Debug doesn't work anymore so there's no way to see what state it's in. You can't iterate through it anymore to add/edit/remove properties.
(3) Related to the above, if you want to add/edit/remove properties, the only way to do so now is to use Map Reduce… another black box. The documentation for this piece of kit is, realistically, almost totally usable. Sure, now I can copy the code from the docs and directly change ONE field in each record, provided it fits the format of the example. But nowhere is it explained how each argument is passed in or out of each of the functions, it's not explained when the functions have to be used inside the controller method, it's not explained what emit or emit intermediate does or how the two differ or even whether they are mandatory or not, it's not explained what is native code for each function and what is custom to each example, it's not explained how to apply map and reduce to multiple different fields in each record or how to create and add new fields to each record, it's not explained whether you always need reduce or if you can achieve some things with just map… and it's not explained how to pass your modified recordsets back to your view.
In the past, customizing recordsets was easy as pie… you pull a find(all) and iterate through each record, run your transformations or calculations on the necessary fields, then save the changes back to the actual record. Then set() your recordset back to your view just as it is in the docs. In other words, in between the cake magic of calling the database and the cake magic of handing off the data to your view, you, as a developer, had complete freedom to intercept the data and do whatever you wanted, no matter how arcane or complicated (hand off data to external functions and run advanced statistical analysis even) and everything would just work.
I'm hopeful that it's all still wonderful and cakey-magicky-awesome like that, albeit just a little too black-boxy and undocumented.
Someone please point me to thorough documentation on cake's Map Reduce, how it logically flows, what the inputs and outputs are, and with some nice semi-advanced use cases that show the entire controller code used.
Alternatively, tell me some other way to manually intercept and modify a recordset before handing it to my view (i.e. add/edit/remove individual fields to each record depending on the values of other fields)