Added an opening PHP tag for the first example of "Symfony Page Creation"

[javiereguiluz]

If accepted, this fixes #6116.

---

This article is linked from the "Welcome to Symfony" page you see after installing Symfony. This is one of the most popular pages for Symfony newcomers. This little change can make a big difference because it's the first example you copy+paste and it should always work.

[javiereguiluz]

Today we received a new bug report about this: symfony/symfony#18369 In my opinion, it's clear that we need to fix this. The changes are minimal, they require zero maintenance and they have a positive impact for newcomers.

[xabbuh]

I am not convinced that simply adding the opening PHP tag in one example will solve anything. I guess that this will probably just lead to people wondering in the second example why that is not working as expected. If we wanted to add opening tags in this example, we should imo also add a short note that explains that we don't include that in all other code blocks.

[javiereguiluz]

@xabbuh let's see if my guess convinces you: I guess that lots of people copy+paste the code of the first example ... but then do the modifications for the rest of examples. If this is true, the opening tag is critical for the first example.

[xabbuh]

Okay, let's Marge this if neither @weaverryan nor @wouterj have any objections and then see how things go in the future.

[wouterj]

I don't like this. It's very very inconsistent, with the other examples in the same article as well as with the complete docs. Why should we include this in the first example of a "Creating your first Page" document, but not in the quick tour or best practices for instance? And on that same idea, let's add it to all first examples of all articles and then just add it to all examples. If we don't do it to all examples, I expect lots of PRs adding them to other examples (and if I really hate to do one thing, it's closing a PR because we don't agree with the change). As I've explained before already, I don't like adding it to all examples.

Also, I count the PHP open tag as one of the most basic PHP things. Any editor (even vim) will show that you're missing something important.

Instead, what about improving DX on the user side? Without docs, things should still work as one normally would expect. in this case, I would expect an error when the annotation loader isn't able to load annotations. Let's throw an exception when the token stream is empty in the AnnotationFileLoader. This class will only be called for .php files (see AnnotationDirectoryLoader), so when the token stream is empty, there must be something wrong.

[javiereguiluz]

I'm closing this because two doc maintainers are against it. Thanks for explaining in detail your reasons!