Security documentation: The Big Picture is missing

[jkufner]

Hello,
I'm digging through Symfony's Security components trying to implement a custom security bundle, and I really miss one thing: The Big Picture. There is a lot written about individual components and even source code is quite understandable, but there is nothing about how these components work together.

The workflow diagrams in HttpKernel documentation are extremely helpful. There should be similar diagrams included in Security component documentation. How all these components interact with each other? What happens during ordinary HTTP request? What happens during login? What happens during subsequent HTTP requests? …? …?

The documentation says there are some components (Guards missing, btw) and that's it. No relation between them is provided. No context. Nothing about basic principles nor ideas.

Security is important and must be well understood to make it right. A cookbook without context is not enough — it helps when one understands, but does not make him understand. Symfony Security component is powerful and complex, so it is hard to get into it.

Someone who has deep understanding of the Security component, please, draw few diagrams how it works. It will help many other developers.

Also, please don't think about what could be done and how great it would be, at least not for now. The first step to get there is to draw where we are now.

---

Related issues:

• Moved from Security documentation: The Big Picture is missing symfony#21760.
• This issue may be understood as a subtask of Rethink Symfony Security docs #7496.
• Symfony security component documentation is bad structured #6861 is focused on individual terms and concepts. This issue is about top-level view.
• [Pre-Draft][WIP] Started rewriting Security component docs #5463 mentions some big picture too.

[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!