From 7c0a3a1237d5eb6df96212aaf1b2f170a916c33e Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Mon, 22 Oct 2018 12:58:12 +0200 Subject: [PATCH] review getting started chapter for belittling words --- controller.rst | 6 +++--- routing.rst | 9 +++++---- setup.rst | 13 +++++++------ templating.rst | 43 ++++++++++++++++++++++--------------------- 4 files changed, 37 insertions(+), 34 deletions(-) diff --git a/controller.rst b/controller.rst index acd010bcb0d..86b5c5f07ca 100644 --- a/controller.rst +++ b/controller.rst @@ -192,7 +192,7 @@ Symfony comes *packed* with a lot of useful objects, called :doc:`services ` +Like with all services, you can also use regular :ref:`constructor injection ` in your controllers. .. versionadded:: 4.1 @@ -358,7 +358,7 @@ The Request object as a Controller Argument What if you need to read query parameters, grab a request header or get access to an uploaded file? All of that information is stored in Symfony's ``Request`` -object. To get it in your controller, just add it as an argument and +object. To get it in your controller, add it as an argument and **type-hint it with the Request class**:: use Symfony\Component\HttpFoundation\Request; diff --git a/routing.rst b/routing.rst index 526fd6b5408..123b78c9122 100644 --- a/routing.rst +++ b/routing.rst @@ -137,8 +137,9 @@ use them later to :ref:`generate URLs `. .. sidebar:: Routing in Other Formats The ``@Route`` above each method is called an *annotation*. If you'd rather - configure your routes in YAML, XML or PHP, that's no problem! Just create a - new routing file (e.g. ``routes.xml``) and Symfony will automatically use it. + configure your routes in YAML, XML or PHP, that's no problem! Create a new + routing file (e.g. ``routes.xml``) in the ``config/`` directory and Symfony + will automatically use it. .. _i18n-routing: @@ -759,7 +760,7 @@ Route path If the requested URL is ``/foo`` If the requested URL is `` Controller Naming Pattern ------------------------- -The ``controller`` value in your routes has a very simple format ``CONTROLLER_CLASS::METHOD``. +The ``controller`` value in your routes has the format ``CONTROLLER_CLASS::METHOD``. .. tip:: @@ -780,7 +781,7 @@ system: mapping the URL to a controller and also a route back to a URL. To generate a URL, you need to specify the name of the route (e.g. ``blog_show``) and any wildcards (e.g. ``slug = my-blog-post``) used in the path for that -route. With this information, any URL can easily be generated:: +route. With this information, an URL can be generated in a controller:: class MainController extends AbstractController { diff --git a/setup.rst b/setup.rst index 1a09225f201..04bf7a7167f 100644 --- a/setup.rst +++ b/setup.rst @@ -43,7 +43,7 @@ Running your Symfony Application On production, you should use a web server like Nginx or Apache (see :doc:`configuring a web server to run Symfony `). -But for development, it's even easier to use the :doc:`Symfony PHP web server `. +But for development, it's convenient to use the :doc:`Symfony PHP web server `. Move into your new project and start the server: @@ -76,8 +76,9 @@ by pressing ``Ctrl+C`` from your terminal. Storing your Project in git --------------------------- -Storing your project in services like GitHub, GitLab and Bitbucket is easy! Init -a new repository with ``Git`` and you are ready to push to your remote: +Storing your project in services like GitHub, GitLab and Bitbucket works like with +any other code project! Init a new repository with ``Git`` and you are ready to push +to your remote: .. code-block:: terminal @@ -94,9 +95,9 @@ that file when needed. Setting up an Existing Symfony Project -------------------------------------- -If you're working on an existing Symfony application, you'll just need to do a few -things to get your project setup. Assuming your team uses Git, you can setup your -project with the following commands: +If you're working on an existing Symfony application, you only need to get the +project code and install the dependencies with composer. Assuming your team uses Git, +setup your project with the following commands: .. code-block:: terminal diff --git a/templating.rst b/templating.rst index 21df296f0fc..7a696f3bc85 100644 --- a/templating.rst +++ b/templating.rst @@ -148,8 +148,8 @@ Twig Template Caching Twig is fast because each template is compiled to a native PHP class and cached. But don't worry: this happens automatically and doesn't require *you* to do anything. And while you're developing, Twig is smart enough to re-compile your templates after -you make any changes. That means Twig is fast in production, but easy to use while -developing. +you make any changes. That means Twig is fast in production, but convenient to use +while developing. .. index:: single: Templating; Inheritance @@ -200,12 +200,12 @@ First, build a base layout file: Though the discussion about template inheritance will be in terms of Twig, the philosophy is the same between Twig and PHP templates. -This template defines the base HTML skeleton document of a simple two-column +This template defines the base HTML skeleton document of a two-column page. In this example, three ``{% block %}`` areas are defined (``title``, ``sidebar`` and ``body``). Each block may be overridden by a child template or left with its default implementation. This template could also be rendered directly. In that case the ``title``, ``sidebar`` and ``body`` blocks would -simply retain the default values used in this template. +retain the default values used in this template. A child template might look like this: @@ -226,7 +226,7 @@ A child template might look like this: .. note:: The parent template is stored in ``templates/``, so its path is - simply ``base.html.twig``. The template naming conventions are explained + ``base.html.twig``. The template naming conventions are explained fully in :ref:`template-naming-locations`. The key to template inheritance is the ``{% extends %}`` tag. This tells @@ -437,7 +437,8 @@ template. First, create the template that you'll need to reuse. {{ article.body }}

-Including this template from any other template is simple: +Including this template from any other template is achieved with the +``{{ include() }}`` function: .. code-block:: html+twig @@ -452,12 +453,11 @@ Including this template from any other template is simple: {% endfor %} {% endblock %} -The template is included using the ``{{ include() }}`` function. Notice that the -template name follows the same typical convention. The ``article_details.html.twig`` -template uses an ``article`` variable, which we pass to it. In this case, -you could avoid doing this entirely, as all of the variables available in -``list.html.twig`` are also available in ``article_details.html.twig`` (unless -you set `with_context`_ to false). +Notice that the template name follows the same typical convention. The +``article_details.html.twig`` template uses an ``article`` variable, which we +pass to it. In this case, you could avoid doing this entirely, as all of the +variables available in ``list.html.twig`` are also available in +``article_details.html.twig`` (unless you set `with_context`_ to false). .. tip:: @@ -537,7 +537,7 @@ configuration: return $routes; -To link to the page, just use the ``path()`` Twig function and refer to the route: +To link to the page, use the ``path()`` Twig function and refer to the route: .. code-block:: html+twig @@ -631,7 +631,7 @@ Linking to Assets ~~~~~~~~~~~~~~~~~ Templates also commonly refer to images, JavaScript, stylesheets and other -assets. Of course you could hard-code the path to these assets (e.g. ``/images/logo.png``), +assets. You could hard-code the web path to these assets (e.g. ``/images/logo.png``), but Symfony provides a more dynamic option via the ``asset()`` Twig function. To use this function, install the *asset* package: @@ -715,8 +715,9 @@ stylesheets and JavaScripts that you'll need throughout your site: -That's easy enough! But what if you need to include an extra stylesheet or -JavaScript from a child template? For example, suppose you have a contact +This looks almost like regular HTML, but with the addition of the +``{% block %}``. Those are useful when you need to include an extra stylesheet +or JavaScript from a child template. For example, suppose you have a contact page and you need to include a ``contact.css`` stylesheet *just* on that page. From inside that contact page's template, do the following: @@ -733,11 +734,11 @@ page. From inside that contact page's template, do the following: {# ... #} -In the child template, you simply override the ``stylesheets`` block and -put your new stylesheet tag inside of that block. Of course, since you want -to add to the parent block's content (and not actually *replace* it), you -should use the ``parent()`` Twig function to include everything from the ``stylesheets`` -block of the base template. +In the child template, you override the ``stylesheets`` block and put your new +stylesheet tag inside of that block. Since you want to add to the parent +block's content (and not actually *replace* it), you also use the ``parent()`` +Twig function to include everything from the ``stylesheets`` block of the base +template. You can also include assets located in your bundles' ``Resources/public/`` folder. You will need to run the ``php bin/console assets:install target [--symlink]``