Skip to content

Documentation: add missing php tags / "use" statements #8324

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Documentation: add missing php tags / "use" statements #8324

wants to merge 2 commits into from

Conversation

MichaelDimmitt
Copy link

@MichaelDimmitt MichaelDimmitt commented Aug 31, 2017

Not sure if these were needed

However, this was the only way I was able to get the page creation working on my:
macintosh computer (mac)

Left the ending php tag out which seemed the convention after looking at the default_controller.

Cheers, Michael Dimmitt 🙂
Happy to have a discussion about this PR.
And add any additional details.

elsewise this would be the error,

  The autoloader expected class "AppBundle\Controller\ LuckyController" 
  to be defined in file "/Users/michaeldimmitt/new_h/bartender  
  /vendor/composer/../../src/AppBundle/Controller/LuckyController.php". 
  The file was found but the class was not in it, the class n  
  ame or namespace probably has a typo.    ```

@MichaelDimmitt MichaelDimmitt changed the title add missing php tags Documentation: add missing php tags Aug 31, 2017
@MichaelDimmitt MichaelDimmitt changed the title Documentation: add missing php tags Documentation: add missing php tags and use statements Aug 31, 2017
@MichaelDimmitt MichaelDimmitt changed the title Documentation: add missing php tags and use statements Documentation: add missing php tags and "use" statements Aug 31, 2017
@MichaelDimmitt MichaelDimmitt changed the title Documentation: add missing php tags and "use" statements Documentation: add missing php tags / "use" statements Aug 31, 2017
not sure if these were needed
<br>However, this was the only way I was able to get the page creation working on my macintosh computer.

Cheers, Michael Dimmitt
Happy to have a discussion about this PR.

// ...
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use this placeholder comment in many places to indicate that the code example is not complete. This is usually done when the code evolves during the reader following an article down from the top. We then just try to add what is new for this specific example.

In this file, the LuckyController class was already introduced before (in the other code example that you changed) including the needed namespace and use statements.

Furthermore, we omit the opening <?php tags everywhere for brevity to keep all code examples as small as possible.

Thus, for me there is nothing to change here. Anyway, thank you very much for opening this PR. We really appreciate people coming with feedback and trying to improve the docs.

@javiereguiluz
Copy link
Member

@MichaelDimmitt your proposal is 100% correct ... but as @xabbuh said, we made some decisions to make docs easier to read and maintain. So, we don't need to add <?php or repeat the use statements here and that's why I'm closing this.

It's sad because this was going to be your first contribution to Symfony Docs ... but I'm sure there will be more opportunities to contribute. Thanks!

@MichaelDimmitt
Copy link
Author

MichaelDimmitt commented Sep 1, 2017

@javiereguiluz @xabbuh, here is an idea for another pull request.
I understand not wanting to repeat <?php or use statements for maintainability purposes and potentially the extra lines take away from the core concepts.
However, the pull request was on chapter 2, page creation. Very early in the documentation.

ideas/options:

  1. '<?php' could be defined once at the end of "chapter 1, page setup" or at the beginning of "chapter 2, page creation." That php documents require <?php.
  2. alternative, at the beginning of chapter 2, page creation tutorial. Refer readers to /src/AppBundle/Controller/DefaultController.php and they will see that the files need to start with <?php.

Possibly your target is veteran php programmers. I was not sure if magic could happen in a framework that allowed a php file to run without a beginning <?php tag.

Any of these changes I would be happy to mock up in a new pull request.
But it is also probably fine without a change.

Positive experience with symfony so far, good work to you both and your team. :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants