Lekce 3 - CMS v Nette a Doctrine 2 - Modely a Layout

V minulé lekci, CMS v Nette a Doctrine 2 - Kostra aplikace, jsme si založili projekt se všemi potřebnými knihovnami a úpravami.

V dnešním Nette tutoriálu začneme tvořit modelovou vrstvu a přidáme layout s úvodní stránkou.

Model

Klíčem k práci s Doctrine jsou anotace. Pomocí nich si uloží do cache informace o entitách, jako jsou názvy sloupců, jejich datové typy, vazby mezi entitami atd. Pokud tedy například pomocí anotace určíme, že proměnná bude typu boolean, při výběru dat z databáze se hodnota automaticky přetypuje na TRUE nebo FALSE (v databázi hodnota bude uložena jako 1 / 0). Informace lze zapisovat i pomocí formátu XML nebo YAML, ale anotace jsou nejpoužívanější.

Entity

app/model/enti­ties/User.php

Vytvoříme si naši první jednoduchou entitu, která bude reprezentovat uživatele. Nezapomínejte na to, že Nette obsahuje třídu Nette\Security\User, jejíž objekt je ve všech presenterech a šablonách v proměnné $user. Neměli bychom tuto proměnnou přepsat, proto se proměnná naší entity bude v šablonách jmenovat $userEntity.

Pro začátek bude naše entita velmi jednoduchá. Obsahuje definici atributů, které odpovídají sloupcům v databázové tabulce user. Název je odvozen od názvu entity, proto pokud bychom měli jiný název tabulky, přidáme anotaci @ORM\Table(name="nazev_tabulky").

Stejně to platí i u názvů sloupců, tam přidáme do závorky parametr name (@ORM\Column(name="nazev_sloupce")).

<?php

namespace App\Model\Entities;

use Doctrine\ORM\Mapping as ORM;
use Kdyby\Doctrine\Entities\BaseEntity;

/**
 * Doctrine entita pro tabulku user.
 * @package App\Model\Entities
 * @ORM\Entity
 */
class User extends BaseEntity
{
    // Pomocné konstanty pro náš model.

    /** Konstanty pro uživatelské role. */
    const ROLE_USER = 1,
        ROLE_ADMIN = 2;

    /** Konstanty pro uživatelské jméno. */
    const MAX_NAME_LENGTH = 15,
        NAME_FORMAT = "^[a-zA-Z0-9]*$";

    // Proměné reprezentující jednotlivé sloupce tabulky.

    /**
     * Sloupec pro ID uživatele.
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue
     */
    protected $id;

    /**
     * Sloupec pro jméno.
     * @ORM\Column(type="string")
     */
    protected $name;

    /**
     * Sloupec pro heslo.
     * @ORM\Column(type="string")
     */
    protected $password;

    /**
     * Sloupec pro email.
     * @ORM\Column(type="string")
     */
    protected $email;

    /**
     * Sloupec pro IP adresu.
     * @ORM\Column(type="string")
     */
    protected $ip;

    /**
     * Sloupec pro datum registrace.
     * @ORM\Column(name="`registration_date`", type="datetime")
     */
    protected $registrationDate;

    /**
     * Sloupec role uživatele. Význam hodnot viz. konstanty pro uživatelské role.
     * @ORM\Column(type="integer")
     */
    protected $role;

    /**
     * Ověřuje, zda je uživatel v roli administrátora.
     * @return bool vrací true, pokud je uživatel administrátor; jinak vrací false
     */
    public function isAdmin()
    {
        return $this->role === self::ROLE_ADMIN;
    }
}

Pro ID je potřeba zapsat anotací více, Doctrine ho poté automaticky použije jako primární klíč.

Dále si všimněte metody isAdmin() - entita není jen přepravkou na data, ale může umět i jednoduché operace.

Všechny naše entity budou dědit od základní entity, vytvořené rozšířením Kdyby. Získá díky tomu některé příjemné funkce, např. nebudeme muset psát settery a gettery a místo toho budeme moci používat přímo $user->name.

Poznámka: Pokud atributu určíme datový typ date nebo datetime, Doctrine automaticky při tahání data z databáze vytvoří objekt třídy DateTime.

Fasády

Fasády budou služby (tzn. že v celé aplikaci bude jen jedna instance dané třídy), které budou zprostředkovávat veškeré operace.

app/model/faca­des/UserFacade­.php

Pro začátek bude opět naše třída velmi jednoduchá. Konstruktorem automaticky dostane objekt třídy Kdyby\Doctrine\EntityManager (opět malé vylepšení EntityManager od Doctrine) a přidáme metodu na vyhledání uživatele podle ID.

<?php

namespace App\Model\Facades;

use App\Model\Entities\User;
use Kdyby\Doctrine\EntityManager;
use Nette\Object;

/**
 * Fasáda pro manipulaci s uživateli.
 * @package App\Model\Facades
 */
class UserFacade extends Object
{
    /** @var EntityManager Manager pro práci s entitami. */
    private $em;

    /**
     * Konstruktor s injektovanou třídou pro práci s entitami.
     * @param EntityManager $em automaticky injektovaná třída pro práci s entitami
     */
    public function __construct(EntityManager $em)
    {
        $this->em = $em;
    }

    /**
     * Najde a vrátí uživatele podle jeho ID.
     * @param int|NULL $id ID uživatele
     * @return User|NULL vrátí entitu uživatele nebo NULL pokud uživatel nebyl nalezen
     */
    public function getUser($id)
    {
        return isset($id) ? $this->em->find(User::class, $id) : NULL;
    }
}

Metoda EntityManager::find() vyhledá entitu User podle daného ID. Normálně bychom jako první parametr měli napsat celý název třídy App\Model\Entities\User, ale magická konstanta class (zabudovaná přímo v PHP) tento název včetně jmenného prostoru obsahuje, je proto náš zápis o něco kratší.

V našem případě se buď vrátí načtená entita User (jako načtená chápejte objekt naplněný daty z databáze) nebo NULL (což vrací metoda EntityManager::find(), pokud takovou entitu nenajde).

app/config/con­fig.neon

Jelikož je UserFacade automaticky injectovaná služba, musíme ji zaregistrovat v našem konfiguračním souboru:

...
services:
    - App\Model\Facades\UserFacade
    router: App\RouterFactory::createRouter
...

Presentery

app/presenter­s/BasePresenter­.php

Entitu User i UserFacade budeme využívat v podstatě všech presenterech, proto je uložíme do našeho BasePresenteru:

<?php

namespace App\Presenters;

use App\Model\Entities\User as UserEntity;
use App\Model\Facades\UserFacade;
use Kdyby\Translation\Translator;
use Nette\Application\UI\Presenter;
use Nette\Bridges\ApplicationLatte\Template;

/**
 * Základní presenter pro všechny ostatní presentery aplikace.
 * @package App\Presenters
 */
abstract class BasePresenter extends Presenter
{
    /** @persistent null|string Určuje jazykovou verzi webu. */
    public $locale;

    /**
     * @var Translator Obstarává jazykový překlad na úrovni presenteru.
     * @inject
     */
    public $translator;

    /**
     * @var UserFacade Fasáda pro manipulaci s uživateli.
     * @inject
     */
    public $userFacade;

    /** @var UserEntity Entita pro aktuálního uživatele. */
    protected $userEntity;
…

Dále si zde přetížíme metodu startup(), kde si vytvoříme entitu User. Pokud je uživatel přihlášen, najdeme informace z databáze a uložíme je do entity. Pokud není, pak vytvoříme entitu s jedinou informací, a to že uživatel není v roli administrátora (abychom nemuseli všude připisovat podmínku $user->isLoggedIn(), ale stačilo jen $userEntity->isAdmin()).

/**
 * Volá se na začátku každé akce, každého presenteru a zajišťuje inicializaci entity uživatele.
 */
public function startup()
{
    parent::startup();
    if ($this->getUser()->isLoggedIn()) {
        $this->userEntity = $this->userFacade->getUser($this->getUser()->getId());
    } else {
        // Abychom mohli použít "$userEntity->isAdmin()", když uživatel není přihlášen.
        $entity = new UserEntity();
        $entity->role = UserEntity::ROLE_USER;
        $this->userEntity = $entity;
    }
}

Nezapomeňte do use uvést

use App\Model\Entities\User as UserEntity

Další metoda beforeRender() předává proměnné šabloně ještě před jejím vykreslením - je jedno, o kterou šablonu se jedná - předá je tedy každé šabloně, která se bude vykreslovat. Jelikož se naše entita hodí ve všech šablonách, předáme ji opět v BasePresenter.

/**
 * Volá se před vykreslením každého presenteru a předává společné proměnné do celkového layoutu webu.
 */
public function beforeRender()
{
    parent::beforeRender();
    $this->template->userEntity = $this->userEntity;
}

Šablony

app/presenter­s/templates/@la­yout.latte

Layout je hlavní šablona, která se vykresluje vždy. Šablony pro jednotlivé stránky se poté vloží makrem {include} do obsahu.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">

    <title>Nette Doctrine 2 blog</title>

    <link rel="stylesheet" href="{$basePath}/css/style.css">
    <link rel="shortcut icon" href="{$basePath}/favicon.ico">
    <meta name="viewport" content="width=device-width">
    {block head}{/block}
</head>
<body>
    <div id="container">

        {if count($flashes) > 0}
            <div id="flashes">
                <div class="text">
                    <div n:foreach="$flashes as $flash" n:class="flash, $flash->type">
                        {$flash->message}
                    </div>
                </div>
            </div>
        {/if}

        <div id="header">
            <div id="logo">
                <h1>Blog system</h1>
            </div>
            <div id="userInfo">
                {if $user->isLoggedIn()}
                    {_common.loggedAs}: {$userEntity->name}
                {/if}
            </div>
            <div id="menu">
                <a n:href="Homepage:default">{_menu.homepage}</a>
            </div>
        </div>
        <div id="content">
            {include content}
        </div>
        <div id="footer">
            <div class="text">
                &copy; Konesoft Corporation
            </div>
        </div>
    </div>

    {block scripts}
    <script src="//code.jquery.com/jquery-1.11.2.min.js"></script>
    <script src="//nette.github.io/resources/js/netteForms.min.js"></script>
    <script src="{$basePath}/js/main.js"></script>
    {/block}
</body>
</html>

Nette kromě proměnné $user předává šablonám automaticky i proměnné $flashes, která obsahuje pole flash zpráv (ty se vytvoří metodou Nette\Application\UI\Control::flashMessage($message, $type)), a $basePath - ta obsahuje název kořenové složky projektu.

Všimněte si, že texty v naší šabloně jsou připravené pro překlad. K tomuto článku přiložím všechny soubory pro překlad, ať to nemusíme v každém článku dopisovat. Je zde podpora pro český a anglický jazyk.

Také bude přiložen CSS soubor. Přijde mi bezdůvodné ho tu ukazovat a vysvětlovat (je ke stažení v projektu), design není cílem této série. Stejně si ho upravíte dle vlastního vkusu.

Poznámka: U překladu znamená první slovo název souboru, ostatní jsou názvy klíčů. Proto makro {_menu.homepage} použije klíč homepage ze souboru menu (přesný soubor se ještě určí podle jazyka). Soubory jsou ve formátu NEON.

app/presenter­s/templates/Ho­mepage/default­.latte

Na úvodní stránce bude zobrazeno několik nejnovějších článků. To si vytvoříme až později, nyní přidáme jen stránku s nadpisem, aby Nette nevyhazovalo chybu 404.

{block content}
<h2>{_homepage.header}</h2>

To je z dnešní lekce vše.

Příště, v lekci CMS v Nette a Doctrine 2 - Registrace uživatele, přidáme možnost registrace uživatele.