Como Fazer um "Hello World"

Esta seção descreve como criar uma nova página de "Hello" em sua aplicação. Para atingir este objetivo, você criará uma ação (action) e uma visão (view):

• A aplicação enviará a requisição de página para a ação
• e a ação por sua vez renderizará a view que mostra as palavras "Hello" para o usuário final.

Através deste tutorial, você aprenderá três coisas:

1. Como criar uma ação para responder às requisições,
2. como criar uma visão para compor o conteúdo da resposta, e
3. como uma aplicação envia as requisições para as ações.

Criando uma Ação

Para a tarefa "Hello", você criará uma ação say que lê um parâmetro message da requisição e exibe essa mensagem de volta para o usuário. Se a requisição não fornecer um parâmetro message, a ação exibirá a mensagem padrão "Hello".

Informação: Ações são os objetos aos quais os usuários finais podem se referir diretamente para execução. As ações são agrupadas nos controladores (controllers). O resultado da execução de uma ação é a resposta que o usuário final receberá.

As ações devem ser declaradas em controladores. Por motivo de simplicidade, você pode declarar a ação say na classe já existente SiteController. Este controlador está definido no arquivo controllers/SiteController.php. Segue aqui o início da nova ação:

<?php

namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
    // ...código existente...

    public function actionSay($message = 'Hello')
    {
        return $this->render('say', ['message' => $message]);
    }
}

No código acima, a ação say está definida como um método chamado actionSay na classe SiteController. O Yii usa o prefixo action para diferenciar métodos de ações de métodos que não são de ações em uma classe de controlador. O nome após o prefixo action é mapeado para o ID da ação.

Quando se trata de dar nome às suas ações, você deveria entender como o Yii trata os IDs de ações. Os IDs das ações são sempre referenciados em minúsculo. Se o ID de uma ação necessitar de múltiplas palavras, elas serão concatenadas por hífens (por exemplo, create-comment). Os nomes de métodos de ações são mapeados para os IDs das ações removendo-se os hífens dos IDs, colocando em maiúsculo a primeira letra de cada palavra, e prefixando o resultado com action. Por exemplo, o ID de ação create-comment corresponde ao método de ação actionCreateComment.

O método de ação em nosso exemplo recebe um parâmetro $message, cujo valor padrão é "Hello" (exatamente da mesma forma que você define um valor padrão para qualquer argumento de função ou método no PHP). Quando a aplicação recebe a requisição e determina que a ação say é responsável por tratar a requisição, a aplicação alimentará este parâmetro com o parâmetro de mesmo nome encontrado na requisição. Em outras palavras, se a requisição inclui um parâmetro message com o valor "Goodbye", a variável $message na ação receberá esse valor.

Dentro do método da ação, [[yii\web\Controller::render()|render()]] é chamado para renderizar um arquivo de visão chamado say. O parâmetro message também é passado para a visão de modo que ele possa ser usado ali. O resultado da renderização é retornado pelo método da ação. Esse resultado será recebido pela aplicação, e exibido para o usuário final no navegador (como parte de uma págian HTML completa).

Criando uma Visão

As visões são scripts que você escreve para gerar o conteúdo de uma resposta. Para a tarefa "Hello", você criará uma visão say que imprime o parâmetro message recebido do método da ação, e passado pela ação para a visão:

<?php
use yii\helpers\Html;
?>
<?= Html::encode($message) ?>

A visão say deve ser salva no arquivo views/site/say.php. Quando o método [[yii\web\Controller::render()|render()]] é chamado em uma ação, ele procurará um arquivo PHP chamado de views/IDdoController/NomeDaView.php.

Perceba que no código acima o parâmetro message é [[yii\helpers\Html::encode()|codificado como HTML]] antes de ser impresso. Isso é necessário, já que o parâmetro vem de um usuário final, tornando-o vulnerável a ataques de cross-site scripting (XSS) onde coloca-se código JavaScript malicioso no parâmetro.

Naturalmente, você pode colocar mais conteúdo na visão say. O conteúdo pode consistir de tags HTML, texto puro, ou até mesmo instruções de PHP. De fato a visão say é apenas um script PHP que é executado pelo método [[yii\web\Controller::render()|render()]]. O conteúdo impresso pelo script da visão será retornado à aplicação como o resultado da resposta. A aplicação, por sua vez, retornará este resultado para o usuário final.

Testando

Após criar a ação e a visão, você pode acessar a nova página através da seguinte URL:

http://hostname/index.php?r=site/say&message=Hello+World

Esta URL resultará em uma página exibindo "Hello World". Esta página compartilha o mesmo cabeçalho e rodapé das outras páginas da aplicação.

Se você omitir o parâmetro message na URL, você veria a página exibindo somente "Hello". Isso é porque message é passado como um parâmetro para o método actionSay(), e quando ele é omitido, o valor padrão "Hello" será usado ao invés dele.

Informação: A nova página compartilha o mesmo cabeçalho e rodapé de outras páginas porque o método [[yii\web\Controller::render()|render()]] irá automaticamente incluir o resultado da visão say em um layout que neste caso está localizado em views/layouts/main.php.

O parâmetro r na URL acima requer mais explicação. Ele significa rota, um ID abrangente e único de uma aplicação que se refere a uma ação. O formato da rota é IDdoController/IDdaAction. Quando a aplicação recebe uma requisição, ela verificará este parâmetro, usando a parte IDdoController para determinar qual classe de controlador deve ser instanciada para tratar a requisição. Então o controlador usará a parte IDdaAction para determinar qual ação deverá ser instanciada para fazer o trabalho. No caso deste exemplo, a rota site/say será resolvida como a classe de controlador SiteController e a ação say. Como resultado, o método SiteController::actionSay() será chamado para tratar a requisição.

Informação: Assim como as ações, os controladores também possuem IDs que os identificam de maneira única em uma aplicação. Os IDs de controladores seguem as mesmas regras de nomenclatura que os IDs de ações. Os nomes das classes de controlllers derivam dos IDs de controladores removendo-se os hífens dos IDs, convertendo a primeira letra de cada palavra em maiúscula, e adicionando o sufixo Controller. Por exemplo, o ID de controlador post-comment corresponde ao nome de classe de controlador PostCommentController.

Resumo

Nesta seção, você tocou as partes do controlador (controller) e da visão (view) do padrão de arquitetura MVC. Você criou uma ação (action) como parte de um controlador para tratar uma requisição específica. E você também criou uma visão para compor o conteúdo da resposta. Neste exemplo simples acima, nenhum modelo (model) foi utilizado, já que os único dado sendo exibido foi o parâmetro message.

Você também aprendeu sobre as rotas no Yii, que agem como a ponte entre as requisições do usuário e as ações do controlador.

Na próxima seção, você aprenderá como criar um modelo e adicionar uma nova página contendo um formulário HTML.