Symfony4.2入門教學【第二篇】建立第一個頁面

建立一個新頁面，有兩個步驟要做：

1. 建立路由(route)：所謂路由就是連接到網頁的URL(e.g. /about)和控制器。
2. 建立控制器(controller)：控制器是由PHP函式構成，針對你接收到請求(request)去建立一個Symfony的回應(Response)，這個回應有可能是HTML、JSON字串或二進位檔(binary file)如圖片或PDF。

你更傾向影片教學？查看教學影片。

Symfony 有包含HTTP 請求-回應生命週期(HTTP Request-Response lifecycle)，要了解更多訊息，請看Symfony和HTTP基礎知識

新建頁面：路由和控制器(Route and Controller)

繼續之前，請先確定你已經讀完「Symfony4.2入門教學【第一篇】安裝」(原文)這篇文章，且可以用瀏覽器觀看你的Symfony應用。

架設你要建立一個頁面 - /lucky/number - 會亂數產生一個幸運數字並印在頁面上，為了達到這個目的，新建一個"Controller Class"、一個"controller"的函式(method)在class裡面。

<?php
// src/Controller/LuckyController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;

class LuckyController
{
    public function number()
    {
        $number = random_int(0, 100);

        return new Response(
            'Lucky number: '.$number.''
        );
    }
}

現在你需要將這個控制器與一個可以公開存取的URL路徑(e.g. /lucky/number)連接在一起，讓使用者訪問這個頁面時能執行number()這個函式，這個連接的方式必須在檔案config/routes.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

就是這麼簡單！如果你已經啟動了Symfony的網頁伺服器，可以打開瀏覽器去看看：

http://localhost:8000/lucky/number

若你看到一個幸運數字印在頁面上，那就恭喜你囉！但在你跑去買樂透之前，先看看這是怎麼辦到的呢，建立頁面的兩個步驟記得嗎？

1. 建立路由：在config/routes.yaml檔案裡，路由定義了頁面的URL要呼叫哪一個控制器，你可以在路由這一個章節學到更多，裡面也會提到如何設定參數(Variable)。
2. 建立控制器：在此建立頁面的函式，並在最後回覆一個Response的物件，你可以在控制器的章節內學到更多，裡面也會提到如何將JSON字串當作Response回傳。

註解式路由(Annotation Routes)

如果不是在YAML定義路由，取得代之，Symfony提供一個註解式(Annotation)的路由，如果要使用，請先安裝套件：

composer require annotations

你可以直接在控制器的函式上方定義路由：

// src/Controller/LuckyController.php

// ...
use Symfony\Component\Routing\Annotation\Route;

class LuckyController
{
   /**
    * @Route("/lucky/number")
    */
    public function number()
    {
        // this looks exactly the same
    }
}

是不是很簡單呢！這個頁面 -http://localhost:8000/lucky/number- 功能就跟之前一樣，Annotations絕對是個備受推薦的路由設定方法。

Auto-Installing Recipes with Symfony Flex

你可能還沒有發現，當你執行composer require annotations這個指令時，發生了兩件神奇的事情，這都是多虧了強大的Composer插件 Flex。

首先，annotations並非套件真正的名稱，而是一個別名(alias)(i.e. 捷徑shortcut)，是由Flex解析成實際的套件sensio/framework-extra-bundle。

第二，當這個套件完成下載後，Flex會自動執行食譜(Recipe)，所謂食譜就是一連串指令去告訴Symfony如何統整這些外部套件。Flex食譜使得許多套件能辦到更多事情，像是新增設定檔、新增目錄、更新.gitignore，以及在.env新增設定，Flex讓安裝自動化，這麼以來你就可以專注在寫程式上。

你可以參考"Using Symfony Flex to Manage Symfony Applications"了解更多資訊，不過既然你安裝新的套件時，Flex會自動地在背景執行它的任務，這就不是那麼重要了！

指令 bin/console

你的專案已經內建了相當好用的除錯工具(debugging tool)：指令bin/console，試著執行看看：

php bin/console

你應該會看到一堆指令，可以提供除錯資訊，可以幫你產生程式、產生資料庫遷移(database migration)等等，當你安裝更多套件時，可以接觸到更多指令。

若要取得伺服器內所有路由，請執行指令debug:router：

php bin/console debug:router

你應該會看到app_lucky_number在最上面：

Name	Method	Scheme	Host	Path
app_lucky_number	ANY	ANY	ANY	/lucky/number

你也會看到一些除錯用的路由(debugging route)在app_lucky_number下面，關於除錯的路由會在下一個章節更詳細的介紹。

繼續往下學，就能了解更多指令。

除錯工具列

除錯工具列(Web Debug Toolbar)是Symfony最大的特色，當你在開發時，頁面底下在這個區域會顯示大量的有助於除錯的資訊，全都包由symfony/profiler-pack這個套件來搞定。

在頁面的最下方看到都一個黑色框框，你會慢慢更了解上面訊息代表的意思，你可以隨意試試，每個icon都可以滑過去或按按看，可以看到關於路由、效能、logging等等的資訊。

Rendering a Template

如果想要讓控制器回傳一個HTML物件，你或許會希望回應(render)一個模板。幸運的是，Symfony有Twig，這個模板語言非常簡單、強大且真的很有趣。

請確定LuckyController必須延伸(extend)Symfony的class AbstractController。

// src/Controller/LuckyController.php

// ...
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class LuckyController
class LuckyController extends AbstractController
{
    // ...
}

現在，render()這個方便的函式可以回傳一個模板，給一個number的變數讓你可以在Twig中使用。

// src/Controller/LuckyController.php

// ...
class LuckyController extends AbstractController
{
    /**
     * @Route("/lucky/number")
     */
    public function number()
    {
        $number = random_int(0, 100);

        return $this->render('lucky/number.html.twig', [
            'number' => $number,
        ]);
    }
}

模板檔案放在templates/目錄裡，這個目錄在安裝Twig時會自動建立，現在建立一個新目錄templates/lucky和一個新檔案number.html.twig在目錄裡：

{# templates/lucky/number.html.twig #}

<h1>Your lucky number is {{ number }}</h1>

這個{{ number }}語句是用來在Twig裡印出參數，重新整理網頁就能看到新的幸運數字。

http://localhost:8000/lucky/number

再來你可能會疑惑，網頁的除錯工具列(the Web Debug Toolbar)是不是不見了呢？這是因為現在的模板裡缺了</body>這個tag，你可自已加上body，或著延伸base.html.twig，裡面已經包含所有基礎的HTML元件。

在建立及使用模板的文章內，你可以如何寫迴圈、render其他模板和利用其強大的佈局繼承系統。

查看專案架構

有個好消息，就是你已經實際操作過專案中最重要的目錄：

config/
當然是包含了設定檔，你可以設定路由、服務(services)和套件。

src/
所有的PHP程式碼都放在這裡。

templates/
所有Twig模板存放的位置。

大部分的情況下，你只會用到src/、templates/和config/，繼續看下去就可以更加了解這幾個目錄各別的用途。

bin/
大名鼎鼎的bin/console就在這裡，還有一些其他執行檔(executable files)。

var/
這裡的檔案都是自動產生存在這裡，像是暫存(cache)檔案(var/cache/)和log(var/log/)。

vendor/
第三方函式庫的位置，用Composer安裝的套件會自動載到這邊。

public/
這是你專案的根目錄，任何可以開放存取的檔案可以放在這裡。

當你安裝新的套件時，如果有需要會自動建立新的目錄。

下一步

恭喜你！你已經掌握Symfony，並學到如何建立一個架構優雅、具功能的、快速的、便於維護的全新方法。

好的，是時候來看看這些文章掌握基礎知識：

• Symfony4.2入門教學【第三篇】路由(Routes)
• Symfony4.2入門教學【第四篇】控制器(Controller)
• Symfony4.2入門教學【第五篇】模板(Templates)
• Symfony4.2入門教學【第六篇】設定(Configuration)

接著，其他一些重要的主題也值得一學，像是service container, the form system, using Doctrine (if you need to query a database)等等。

Have fun!


文章原文：
https://symfony.com/doc/4.2/page_creation.html

系列文章：

• Symfony4.2入門教學【第一篇】安裝
• Symfony4.2入門教學【第三篇】路由(Routes)
• Symfony4.2入門教學【第四篇】控制器(Controller)
• Symfony4.2入門教學【第五篇】模板(Templates)
• Symfony4.2入門教學【第六篇】設定(Configuration)