[Security] Add article showing an overview of the internals

[wouterj]

The Security component has a very different public API and internal API. While we're doing a good job at documenting the usage in the Security chapter of the book, we don't document the internals that great.

The Security component documentation of course has internals, but it is very strongly related to the standalone usage and less to the extension usage. All other cookbook articles are related to fixing specific things with the Security component.

However, there is no document giving you an overview of what's happening inside and were you can extend/customize it easily. @kriswallsmith has given a great presentation about the overview at Symfony Live 2013: http://www.slideshare.net/kriswallsmith/love-and-loss-a-symfony-security-play I think we should transform something like this into a documentation chapter ( @kriswallsmith can we maybe use your very nice graphs?)

One thing that is lacking from Kris' presentation is the Simple* classes that are in the Security component, we should explain them as well in this article.

I would love to hear some opinions about this, @xabbuh @weaverryan @iltar.

[weaverryan]

@wouterj I agree that @kriswallsmith's presentation was probably the single best source of "how it works under the hood" documentation for the Symfony component. Adding an article that borrows from how he explained I think could be very nice. But I'd want to keep it a little high level - maybe with links to other documents (or borrow code from other documents) to see examples of listener, providers, etc.

So:

A) Yes, but keep it high level and short. Afterall, I don't think there's a huge audience that says "I want to learn how the internals of security work". But there is a huge audience of people asking "how do I do X? How do I do Y?"

B) Add more "How do I do X" type of cookbook articles, for things like entry point, success/failure handlers, etc Even if these link to other places, this will help them be findable

C) In some places, we have too much security docs (look at the Security cookbook list, and also the WSSE article, which I'm not sure is really a good idea to have anymore, with the Simple stuff + it doesn't use any Abstract classes).

[linaori]

@wouterj With the arrival of the Guard implementation that @weaverryan made, I'm not sure how useful it is to focus on the simple variants.

• We have the normal, DAO for example. Not extendable, but will be able to configure the user checkers in the future
• Simple variants, very configurable but a lot of extra work
• Guard, even simpler than the Simple and allows easy configuration of multiple authenticators with re-usable code.

I think the security components could use a "how do I.." knowledge base. There's usually a lot of similar questions on IRC. We can keep writing documentation for every specific use case, but the cookbook would become too big.

Regarding the simple variants, I think it should be slowly fased out if the Gaurd can replace it. They contain a lot of code and configuration duplication from their normal variants in both user-implementations and the core. With user-checkers being able to validate more DAO cases and the Guard being able to handle multiple custom implementations, that might be worth exploring.

[wouterj]

The problem I have with the "how do I do ..." articles in the Security cookbook is that it only explains how to solve the problem. But the same problem might be solved in other places as well. Only if you know the full overview, you can make a good decision on where to put it.

This is what I like about the HTTPKernel component docs, it shows a very clear overview with a clear graph. This makes it easy to decide if something needs to be fixed in the kernel.request or kernel.controller event for instance.

[weaverryan]

i'm still +1 for both the overview and that more real-world "how do I" type of stuff.

[wouterj]

In that case we agree :)

[xabbuh]

I agree with both approaches.

By the way, @jaytaph wrote a very nice book about the Security component. Maybe we can get inspired by it to rework the existing overview.

[javiereguiluz]

We agree that the Symfony Security docs need a lot of improvements. This is in our priority list ... but it's taking us a lot of time because of the massive complexity of the Security internals.

In any case, to focus all our discussions about this in one place, we've created a meta issue in #7496 and we've linked this issue from there. That's why we're closing your issue ... but only to avoid duplicated discussions. We won't forget about what you said here. Thanks!