Is there a place where all the magic is documented?

I don't think there is, I would have thought it would have just worked.

I know there is a section in the dev docs that give an example of how to decorate an object so that you can use all the presenter logic.

By magic do you mean presenter methods cascading backwards?

By default - you can access the objects exactly as you would via API. Presenters and magic won't come into play there. The magic is to make the view logic a little more graceful and easier to follow for people who have no idea about the API. And act as shorthand for those who do.

With that said - presenter -> object decorated is where the majority of that stuff is regarding Pyro. Laravel does use some for getter access on models. $model->foo runs through getFooAttribute if it's there for example.

The second thing to note is that fields return the respective field type presenter as well in order to use / decorate that fields value easily.

The gravatar() method though is a non-magic thing. If you're removing the presenter layer you have to expect to move those too I suppose. If you are no longer decorating at all - all presenters will need their methods moved into the objects they generally decorate but the question I am begging is "Why?". That's a lot of fussing about to remove an entire layer from the system. Seems extremely counterintuitive or maybe indicative that there's a misunderstanding around it or an issue regarding it?

Hope this answers your question lol

@ryanthompson - that's just it - i didn't remove the presenter. The problem is that the presenter was added via magic (naming convention / class_exists()). This means that when i extend the user model the class_exists for the presenter fails (doesn't throw error, just doesn't load UserPresenter class - decorates with the default EntryPresenter instead). This means i have to then create an empty presenter class in my namespace that extends the core UserPresenter to get the gravatar() method back. Same thing with form builders. If i extend a core form builder all the classes that are loaded via naming convention no longer load and i have to extend all of those too.

So by magic, i'm referring to naming convention loading of related classes as opposed to explicitly defining those classes in code (in which case i wouldn't be running into these issues when extending one of the classes). Does that clarify things? I just don't know what other classes i need to extend for things to work the same as they otherwise would.

Ok I am understanding you a little better sorry. The class transformation can get in the way a little bit sometimes. Which sounds like what you're experiencing. You would need to define this method explicitly on your model:

https://github.com/anomalylabs/streams-platform/blob/1.2/src/Entry/EntryModel.php#L771

As you can see there that's where it transforms the class into it's neighboring presenter..

These should definitely be doc'd you're right!

Same things happen for builders as you mention. I'll get on that - sorry I wasn't quite on the same page before!

Ok thanks - it's good to know i can just override that method rather than creating an empty class that extends the presenter. It would be nice to just define this stuff code to make extending stuff easier. Even knowing how to manage this specific UserPresenter issue i still don't know for other classes (builders, field types, modules etc.) what stuff is being loaded via convention and what is not or if there are other convention-based classes being loaded for user (besides presenter). I don't really see any downside to defining all references in code which would remove this uncertainty (as well as make it simpler to extend core classes).

I'll get on it!