diff --git a/page_creation.rst b/page_creation.rst index 8e7bb902a6b..06b7bf4292a 100644 --- a/page_creation.rst +++ b/page_creation.rst @@ -7,13 +7,13 @@ Create your First Page in Symfony Creating a new page - whether it's an HTML page or a JSON endpoint - is a two-step process: -#. **Create a route**: A route is the URL (e.g. ``/about``) to your page and - points to a controller; - #. **Create a controller**: A controller is the PHP function you write that builds the page. You take the incoming request information and use it to create a Symfony ``Response`` object, which can hold HTML content, a JSON - string or even a binary file like an image or PDF. + string or even a binary file like an image or PDF; + +#. **Create a route**: A route is the URL (e.g. ``/about``) to your page and + points to a controller. .. admonition:: Screencast :class: screencast @@ -55,47 +55,12 @@ random) number and prints it. To do that, create a "Controller" class and a } } -Now you need to associate this controller function with a public URL (e.g. ``/lucky/number``) -so that the ``number()`` method is called when a user browses to it. This association -is defined by creating a **route** in the ``config/routes.yaml`` file: - -.. code-block:: yaml - - # config/routes.yaml - - # the "app_lucky_number" route name is not important yet - app_lucky_number: - path: /lucky/number - controller: App\Controller\LuckyController::number - -That's it! If you are using Symfony web server, try it out by going to: http://localhost:8000/lucky/number - -If you see a lucky number being printed back to you, congratulations! But before -you run off to play the lottery, check out how this works. Remember the two steps -to create a page? - -#. *Create a controller and a method*: This is a function where *you* build the page and ultimately - return a ``Response`` object. You'll learn more about :doc:`controllers ` - in their own section, including how to return JSON responses; - -#. *Create a route*: In ``config/routes.yaml``, the route defines the URL to your - page (``path``) and what ``controller`` to call. You'll learn more about :doc:`routing ` - in its own section, including how to make *variable* URLs. - .. _annotation-routes: -Annotation Routes ------------------ - -Instead of defining your route in YAML, Symfony also allows you to use *annotation* -or *attribute* routes. Attributes are built-in in PHP starting from PHP 8. In earlier -PHP versions you can use annotations. To do this, install the annotations package: - -.. code-block:: terminal - - $ composer require annotations - -You can now add your route directly *above* the controller: +Now you need to associate this controller function with a public URL (e.g. ``/lucky/number``) +so that the ``number()`` method is called when a user browses to it. This association +is defined with the ``#[Route]`` attribute (in PHP, `attributes`_ are used to add +metadata to code): .. configuration-block:: @@ -115,27 +80,25 @@ You can now add your route directly *above* the controller: } } -That's it! The page - http://localhost:8000/lucky/number will work exactly -like before! Annotations/attributes are the recommended way to configure routes. +That's it! If you are using Symfony web server, try it out by going to: http://localhost:8000/lucky/number -.. _flex-quick-intro: +.. tip:: -Auto-Installing Recipes with Symfony Flex ------------------------------------------ + Symfony recommends defining routes as attributes to have the controller code + and its route configuration at the same location. However, if you prefer, you can + :doc:`define routes in separate files ` using YAML, XML and PHP formats. -You may not have noticed, but when you ran ``composer require annotations``, two -special things happened, both thanks to a powerful Composer plugin called -:ref:`Flex `. +If you see a lucky number being printed back to you, congratulations! But before +you run off to play the lottery, check out how this works. Remember the two steps +to create a page? -First, ``annotations`` isn't a real package name: it's an *alias* (i.e. shortcut) -that Flex resolves to ``sensio/framework-extra-bundle``. +#. *Create a controller and a method*: This is a function where *you* build the page and ultimately + return a ``Response`` object. You'll learn more about :doc:`controllers ` + in their own section, including how to return JSON responses; -Second, after this package was downloaded, Flex runs a *recipe*, which is a -set of automated instructions that tell Symfony how to integrate an external -package. `Flex recipes`_ exist for many packages and have the ability -to do a lot, like adding configuration files, creating directories, updating ``.gitignore`` -and adding a new config to your ``.env`` file. Flex *automates* the installation of -packages so you can get back to coding. +#. *Create a route*: In ``config/routes.yaml``, the route defines the URL to your + page (``path``) and what ``controller`` to call. You'll learn more about :doc:`routing ` + in its own section, including how to make *variable* URLs. The bin/console Command ----------------------- @@ -343,4 +306,4 @@ Go Deeper with HTTP & Framework Fundamentals .. _`Twig`: https://twig.symfony.com .. _`Composer`: https://getcomposer.org .. _`Harmonious Development with Symfony`: https://symfonycasts.com/screencast/symfony/setup -.. _`Flex recipes`: https://github.com/symfony/recipes/blob/flex/main/RECIPES.md +.. _`attributes`: https://www.php.net/manual/en/language.attributes.overview.php diff --git a/setup.rst b/setup.rst index beb966d163a..51e60ab6fcd 100644 --- a/setup.rst +++ b/setup.rst @@ -147,6 +147,7 @@ Symfony Docker Integration If you'd like to use Docker with Symfony, see :doc:`/setup/docker`. .. _symfony-flex: +.. _flex-quick-intro: Installing Packages -------------------