Yii Structure

Yii2 has a new and improved application structure. It uses composer to manage its dependencies. Yii1 has only a basic application structure. While Yii2 has basic as well as advanced application structure.

Yii2 divides the entire application into following sections:

Backend : For backend web development
Common : Include common files for all the application
Console : Console application
Environments : Environment configurations
Frontend : For frontend web development

Yii2 Directory Structure

ROOT
/ contains the frontend entry script and web resources
/assets contains the frontend web assets
common
config/ contains shared configurations
mail/ contains view files for e-mails
models/ contains model classes used in both backend and frontend
tests/ contains various tests for objects that are common among applications
console
config/ contains console configurations
controllers/ contains console controllers (commands)
migrations/ contains database migrations
models/ contains console-specific model classes
runtime/ contains files generated during runtime
tests/ contains various tests for the console application
backend
assets/ contains application assets such as JavaScript and CSS
config/ contains backend configurations
controllers/ contains Web controller classes
models/ contains backend-specific model classes
runtime/ contains files generated during runtime
tests/ contains various tests for the backend application
views/ contains view files for the Web application
web/ contains the entry script and Web resources
frontend
assets/ contains application assets such as JavaScript and CSS
config/ contains frontend configurations
controllers/ contains Web controller classes
models/ contains frontend-specific model classes
runtime/ contains files generated during runtime
tests/ contains various tests for the frontend application
views/ contains view files for the Web application
vendor/ contains dependent 3rd-party packages
environments/ contains environment-based overrides

assets

Asset bundles are used to include JavaScript and style sheets. Lot of assessment and caching is done through the assets.

There is one more asset folder inside the web directory. Yii uses this folder to cache the assets. It will have a .gitignore in this folder.

If JavaScript or CSS files are need to be updated, all the folders in this directory need to be deleted. They can be deleted any time and can be auto-generated by Yii as cache files.

commands

This directory allows you to create Yii management scripts to run. These commands can be executed on command line by going on Yii root directory and typing php yii or ./yii. It will display a by default available commands list .

config

The config folder includes configuration settings which include e-mail sending, database connection, etc.

controllers

Controllers manage data traffic in MVC framework. When request is made, it is controller that processes that request.

mail

It stores templates that Yii uses to construct a mail.

models

Models manage all the database work in MVC. Any type of coding related to database is written in model.

runtime

This folder is used during processing of a web requests.

tests

This folder checks the functionality.

vendor

Yii source files reside in this directory. Third party installed module will be stored here. During upgradation, codes in this folder are overwritten hence code alteration in this directory should be avoided.

views

Views in MVC contains the pages which are displayed upon a web request. All the HTML coding is done in view directory.

web

This is the document root directory that the web server points to. The index.php file launches the Yii process when called. In this file, debugging code can be turned on or off. Debug bar is viewable at the bottom of the page.

Here you can put any files, images or anything else which needs web accessibility. Files placed in this folder only will be accessed.

Inside this web directory a subdirectory named asset is also present. This directory is used to respond web requests.

Yii Entry Scripts

It is the first step in application handling process and responsible to start a request handling cycle. An application has a single entry script. Request made by end users comes to entry script which initialize the application and forward the request to them.

These scripts are stored under web application directories to make them accessible by the end users. By default, they are named as index.php but can also be given other names.

For a console application, entry scripts are stored in base path and named as yii.php. They should be made executable for users to run on console application.

Entry scripts perform following work:

Define global constants
Register Composer autoloader
Include Yii class file
Load application configuration
Create and configure an application instance
Call the application to process the request

Defining Constants

Global constants are very well defined in the entry scripts. They should be defined at the beginning of an entry script for effective result when other PHP files are included. Yii framework supports following three constants:

YII_DEBUG: It specifies whether an application is running in debug mode or not. This mode should be mainly used during development. Because an application will keep more log information and will reveal detailed error if in debug mode.
YII_ENV: It defines the environment the application is running in. Its default value is 'prod' which stands for 'Production'. Other values are dev and test.
YII_ENABLE_ERROR_HANDLER: By default it is always true. It specifies whether to enable or disable the error handler value.

Yii Models

Models are part of MVC structure. They represent the rules and logic for an application. Means they hold data and define the validating rules for the data.

Model classes are extended by yii\base\Model or its child classes.

Mainly following features are implemented using models.

attribute declaration
attribute labels
massive attribute assignment
scenario-based validation
can not embed HTML
can not be directly accessed

Attributes

Attributes mainly represent the business data. Each attribute is a publicly accessible property of a model. They can be accessed like array elements or normal object properties. it is like publicly accessible properties of a model.

The method,

yii\base\Model::attributes()

specifies what attributes a model class has.

Model class is also the base class for ActiveRecord class (which is an advanced model with additional functionality).

Attribute as a normal object property:

$model = new \app\models\ContactForm;
// "name" is an attribute of ContactForm
$model->name = 'example';
echo $model->name;
Attribute as array elements:
$model = new \app\models\ContactForm;
// accessing attributes like array elements
$model['name'] = 'example';
echo $model['name'];
// Model is traversable using foreach.
foreach ($model as $name => $value) {
echo "$name: $value\n";
}

In earlier versions of Yii, scenarios and validation were handled with the same function. But in Yii2, they are split into different functions i.e; rules() and scenarios().

Here, rules() specify the validation of a data while scenarios() specify which attributes are safe to be assigned to the model.

Attribute Labels

Attribute labels are values which are displayed with attributes to get the input from the users.

For example, in the below code, ID, Name, Designation, Contact and Email denotes the attribute labels. All this is defined under a function attributeLabels().

public function attributeLabels()
{
return [
'id' => 'ID',
'name' => 'Name',
'designation' => 'Designation',
'contact' => 'Contact',
'email' => 'Email',
];
}

Look at the above snapshot, the heading data denotes the attribute labels.

Scenarios

A model may be used for different scenarios. For example, a model may be used to collect login user inputs while it may also be used to collect inputs of new users for registration. So in different scenarios a model may use different rules and logic.

Example

This is the ContactForm.php code,

<?php
namespace frontend\models;
use Yii;
use yii\base\Model;
/**
* ContactForm is the model behind the contact form.
*/
class ContactForm extends Model {
public $name;
public $email;
public $subject;
public $body;
public $verifyCode;
const SCENARIO_EMAIL_FROM_GUEST = 'EMAIL_FROM_GUEST';
const SCENARIO_EMAIL_FROM_USER = 'EMAIL_FROM_USER';
public function scenarios() {
return [
self::SCENARIO_EMAIL_FROM_GUEST => ['name', 'email', 'subject',
'body', 'verifyCode'],
self::SCENARIO_EMAIL_FROM_USER => ['name', 'email' ,'subject', 'body',
'verifyCode'],
];
}
/**
* @return array the validation rules.
*/
public function rules() {
return [
// name, email, subject and body are required
[['name', 'email', 'subject', 'body'], 'required'],
// email has to be a valid email address
['email', 'email'],
// verifyCode needs to be entered correctly
['verifyCode', 'captcha'],
];
}
/**
* @return array customized attribute labels
*/
public function attributeLabels() {
return [
'name' => 'Name',
'email' => 'Email',
'subject' => 'Subject',
'body' => 'Body',
'verifyCode' => 'Verification Code',
];
}
/**
* Sends an email to the specified email address using the information
collected by this model.
* @param string $email the target email address
* @return boolean whether the model passes validation
*/
public function contact($email) {
if ($this -> validate()) {
Yii::$app->mailer->compose()
->setTo($email)
->setFrom([$this->email => $this->name])
->setSubject($this->subject)
->setTextBody($this->body)
->send();
return true;
}
return false;
}
}
?>

Create an action actionContact in SiteController.php file

public function actionContact() {
$model = new ContactForm();
$model->scenario = ContactForm::SCENARIO_EMAIL_FROM_GUEST;
if ($model->load(Yii::$app->request->post()) && $model->
contact(Yii::$app->params ['adminEmail'])) {
Yii::$app->session->setFlash('contactFormSubmitted');
return $this->refresh();
}
return $this->render('contact', [
'model' => $model,
]);

Now, we'll run the program in the browser,

Now change the scenarion in actionContact in SiteController.php as

$model->scenario = ContactForm::SCENARIO_EMAIL_FROM_USER;

Now on running the program in the browser, Subject and Body field will be no longer required field.

Validation Rules

These are the rules which are set for the fields to be fulfilled by the users. For example, required rule will make sure that the respective field is not empty. And email attribute will make sure that the email entered is a valid email. If values do not satisfy the rules, an error message will appear on the screen.

To declare validation rules for all the fields in all the scenarios, following code is used.

public function rules()
{
return [
// the name, email, subject and body attributes are required
[['name', 'email', 'subject', 'body'], 'required'],
// the email attribute should be a valid email address
['email', 'email'],
];
}
To declare different validation rules for different scenarios, use the following code.
public function rules()
{
return [
// username, email and password are all required in "register" scenario
[['username', 'email', 'password', 'd_o_b'], 'required', 'on' => self::SCENARIO_REGISTER],
// username and password are required in "login" scenario
[['username', 'password'], 'required', 'on' => self::SCENARIO_LOGIN],
];
}

The on property implements that, rule will be applied to a particular scenario. If you'll not use on property than by default rule will be applied for all the fields.

Massive Assignment

In massive assignment, a model is populated with user inputs using a single line of code. Massive assignment only applies to the safe attributes.

Look at the following two types of code, both assigning the submitted form data by the end users to attributes of the ContactForm model.

First one is,

$model = new \app\models\ContactForm;
$model->attributes = \Yii::$app->request->post('ContactForm');
Second one is,
$model = new \app\models\ContactForm;
$data = \Yii::$app->request->post('ContactForm', []);
$model->name = isset($data['name']) ? $data['name'] : null;
$model->email = isset($data['email']) ? $data['email'] : null;
$model->subject = isset($data['subject']) ? $data['subject'] : null;
$model->body = isset($data['body']) ? $data['body'] : null;

The first one using massive assignment is much easier, neat and less error prone.

Views

View part in the MVC structure is responsible to present data in front of users. They mainly contain the HTML content and presentational PHP code.

Creating Views

Look at the About page code of basic Yii page.

<?php
/* @var $this yii\web\View */
use yii\helpers\Html;
$this->title = 'About';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="site-about">
<h1><?= Html::encode($this->title) ?></h1>
<p>This is the About page. You may modify the following file to customize its content:</p>
<code><?= __FILE__ ?></code>
</div>

And it's output is this:

In the above script, PHP code is used to generate the dynamic content in title and inside the form tag. HTML tags displays the data in a presentation view.

View Conventions

Views rendered by a controller should be written into @app/views/controllerID folder.
Views rendered by a widget should be written into widgetPath/views folder.

Following controller methods can be called to render views within controller:

render() : Renders the mentioned view file and applies a layout.
renderPartial() : Renders the mentioned view but without applying a layout.
renderAjax() : Renders a view without a layout and injects all registered JS scripts and CSS files.
renderFile() : Renders a view file in the specified path.
renderContent() : Renders a static ring.

Following controller methods can be called to render views within another view:

render() : Renders a view page.
renderAjax() : Renders a view without a layout and injects all registered JS scripts and CSS files.
renderFile() : Renders a view file in the specified path.

Following controller methods can be called to render views within widgets:

render() : Renders a view page.
renderFile() : Renders a view file in the specified path.

Example:

Step 1 Inside views/site folder, we are creating a view file exm.php file.

<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body>
<h1>Hello, welcome to JavaTpoint.</h1>
</body>
</html>

Step 2 Render exm.php view file in the about.php view file in the site folder.

<?php
/* @var $this yii\web\View */
use yii\helpers\Html;
$this->title = 'About';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="site-about">
<h1><?= Html::encode($this->title) ?></h1>
<p>This is the About page. You may modify the following file to customize its content:</p>
<?= $this->render("exm") ?>
<code><?= __FILE__ ?></code>
</div>

Step 3 Run it on the browser.

Controllers

In MVC structure, controllers role is to process the requests from the user and generate the responses. The incoming requests are analyzed by the controllers, passed onto models, models results are directed into views and finally a response is generated.

Controllers Action

Controller contains actions which are called by user to execute a request. A controller can have more than one request.

Following code is an example with two actions update and create in a controller file SiteController.php.

<?php
namespace frontend\controllers;
use Yii;
use frontend\models\Yiicrud;
use frontend\models\SearchYiicrud;
use yii\web\Controller;
use yii\web\NotFoundHttpException;
use yii\filters\VerbFilter;
/**
* YiicrudController implements the CRUD actions for Yiicrud model.
*/
class YiicrudController extends Controller
{
/**
* @inheritdoc
*/
public function behaviors()
{
return [
'verbs' => [
'class' => VerbFilter::className(),
'actions' => [
'delete' => ['POST'],
],
],
];
}
public function actionUpdate($id)
{
$model = $this->findModel($id);
if ($model->load(Yii::$app->request->post()) && $model->save()) {
return $this->redirect(['view', 'id' => $model->id]);
} else {
return $this->render('update', [
'model' => $model,
]);
}
}
/**
* Deletes an existing Yiicrud model.
* If deletion is successful, the browser will be redirected to the 'index' page.
* @param integer $id
* @return mixed
*/
public function actionDelete($id)
{
$this->findModel($id)->delete();
return $this->redirect(['index']);
}

Look at the above code, action update (actionUpdate( )), it will first load the model according to requested id, then tries to include the new model instance using the request data and save the model. Then it will be redirected to view action with the model id. Otherwise, it will return the update action.

Action delete (actionDelete( )), it will load the model according to requested id,and then delete it. It will be redirected to the index action.

Routes

In Yii URL, you must have noticed there is a r. This r is the route.

For example: http://localhost/index.php?r=site/index

The route is site/index in the above example.

which consist of the following parts:

moduleID : It applies only when controller belongs to a non-application module.

controllerID : A string that identifies the controller among all controllers within a same module. In above example, it is site.

actionID : A string that identifies the action name among all actions in a controller. In above example, it is index.

Route format is:

ControllerID/ActionID

If belongs to a module, it takes the following format:

ModuleID/ControllerID/ActionID

Controllers Action

Actions are defined in the controllers file. They need to be called while executing a request in an application through the URL.

Creating Action

An action is created by defining a public method whose name starts with the word action.

Example:

Step 1 We'll create an action named index2 in the SampleController.php file.

<?php
namespace frontend\controllers;
use Yii;
use yii\web\Controller;
class SampleController extends Controller
{
public function actionIndex()
{
return $this->render('index');
}
public function actionIndex2()
{
return "<h1>This action is Index2</h2>";
}
}
?>

Step 2 Run it on the browser.

http://localhost/action/frontend/web/index.php?r=sample/index2

Action IDs

An action is created to perform a particular request, and hence it is generally named as verbs like create, view, update, delete, etc.

An action ID can contain only these letters:

English letters in lower case
Underscores
Hyphens
Numbers after english alphabets like index2 in the above example.

Actions can be created in two ways:

Inline action
Standalone action

Inline Action

Inline action is a method in the controller class. These are the most commonly created actions when they don't need to be used more than once and are easy to create.

Inline action ID name is defined according to the following points:

Start the method name with the action prefix.
The first letter of the word after action will be in upper case.
Remove hyphens.

For example,

Index2 becomes actionIndex2
login-form becomes actionLoginForm

Standalone Action

A standalone action extends yii\base\Action or its child classes. These actions are mainly created when they need to be used in different controllers or redistributes as extensions.

They can be defined as separate classes and then connect them to your controllers. This way they will be able to reuse.

These actions must implement a method called run() and extend to yii\base\Action or a child class.

Example

We'll demonstrate a simple use of standalone action.

Step 1 Create a folder standing in the frontend directory of your Yii2 folder.

Step 2 Now create a MultiAction.php file in above created folder.

<?php
namespace frontend\standing;
use yii\base\Action;
class MultiAction extends Action {
public function run() {
return "<h3>This is StandAlone action example</h3>";
}
}
?>

Look at the above code, we have created a standalone action named as MultiAction which extends to Action class. The have implemented the run() method.

Step 3 In the above created SampleController.php file add some extra codes.

<?php
namespace frontend\controllers;
use Yii;
use yii\web\Controller;
class SampleController extends Controller
{
public function actionIndex()
{
return $this->render('index');
}
public function actions()
{
return [
'multi' => 'frontend\standing\MultiAction',
];
}
public function actionIndex2()
{
return "<h1>This action is Index2</h2>";
}
}
?>

Look at the above code, actions() method returns the standalone action which is multi action created in the standing folder.

Step 4 Run it on the browser with the URL,

http://localhost/action/frontend/web/index.php?r=sample/multi

Action Return Value

Return value of an action stands for the result of the corresponding action.

The following example shows an action being redirected to a new URL by returning a response object. The redirect() method always returns a response object.

Step1 Add the following code in the SampleController.php file.

public function actionMysite()
{
// redirect the user browser to http://example.com
return $this->redirect('http://javatpoint.com');
}

Step 2 Run it on the browser with the following URL,

http://localhost/action/frontend/web/index.php?r=sample/mysite

The above URL will result the javatpoint.com site in front of you.

Action Parameters

You can also add parameters to the action methods. Their values will be retrieved from the $_GET method using parameter name as key.

Step 1 Add the following code in the SampleController.php file.

public function actionPara($a, $b)
{
return "$a $b";
}

Step 2 Run it on the browser with the following URL,

http://localhost/action/frontend/web/index.php?r=sample/para&a=Welcome to&b=our site

In the above URL, if you'll not provide any value to a and b variables, exception error will be thrown.

Default Action

A default action is always specified in every controllers file. By default, it is set as index.

When in the route, URL only contains controller ID, then it goes to default action that is index. However this default value can be changed by overriding it.

namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
public $defaultAction = 'main_page';
public function actionHome()
{
return $this->render('main_page');
}
}

Modules

A module resides in the main application and organized as a directory that is called base path of the module. This module directory will have its own MVC (model, view and controller) and other supporting components just like an application.

Module Structure

Modules follow a typical structure as shown below.

newModule/
Module.php the module class file
controllers/ containing controller class files
DefaultController.php the default controller class file
models/ containing model class files
views/ containing controller view and layout files
layouts/ containing layout view files
default/ containing view files for DefaultController
index.php the index view file

Module Class

Module class characteristics:

Each module should have a unique class extending to yii\base\Module.
Class should be located under module's base path and should be accessible.
On execution, a single instance of the module class will be created.
Module instances are used to share data and components for codes within modules.
By default it is named as Module.php.

Example

Let's look at an example to create a module.

Step 1 Create modules named folder in Frontend directory of your Yii2 folder.

Step 2 Inside modules folder create a folder named as project.

Step 3 Inside project folder create a file named as Project.php.

<?php
namespace frontend\modules\project;
/**
* project module definition class
*/
class Project extends \yii\base\Module
{
/**
* @inheritdoc
*/
public $controllerNamespace = 'frontend\modules\project\controllers';
/**
* @inheritdoc
*/
public function init()
{
parent::init();
// custom initialization code goes here
}
}

Look at the above code, this is module class we have created. The init() function here is to initialize the module's properties.

Step 4 Inside project folder create two more folders named as controllers and views.

Step 5 Inside controllers folder create EmpController.php file.

<?php
namespace frontend\modules\project\controllers;
use yii\web\Controller;
/**
* Default controller for the `project` module
*/
class EmpController extends Controller
{
/**
* Renders the index view for the module
* @return string
*/
public function actionMessage()
{
return $this->render('message');
}
}

Look at the above snapshot, here we have defined the action actionMessage.

Step 6 Inside views folder create emp folder and inside it create message.php file.

<h1>This is an Example to create a Module.</h1>

The below snapshot shows our final modules's structure in our modd directory. It displays all the files created inside modd/frontend/modules directory.

Step 7 Now we need to do some config settings to add our module. Go to config folder of frontend directory.

Add the module in the file main.php in the config folder.

<?php
$params = array_merge(
require(__DIR__ . '/../../common/config/params.php'),
require(__DIR__ . '/../../common/config/params-local.php'),
require(__DIR__ . '/params.php'),
require(__DIR__ . '/params-local.php')
);
return [
'id' => 'app-frontend',
'basePath' => dirname(__DIR__),
'bootstrap' => ['log'],
'controllerNamespace' => 'frontend\controllers',
'modules' => [
'project' =>[
'class' => 'frontend\modules\project\Project',
],
],
'components' => [
'request' => [
'csrfParam' => '_csrf-frontend',
],
'user' => [
'identityClass' => 'common\models\User',
'enableAutoLogin' => true,
'identityCookie' => ['name' => '_identity-frontend', 'httpOnly' => true],
],
'session' => [
// this is the name of the session cookie used for login on the frontend
'name' => 'advanced-frontend',
],
'log' => [
'traceLevel' => YII_DEBUG ? 3 : 0,
'targets' => [
[
'class' => 'yii\log\FileTarget',
'levels' => ['error', 'warning'],
],
],
],
'errorHandler' => [
'errorAction' => 'site/error',
],
/*
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'rules' => [
],
],
*/
],
'params' => $params,
];

Step 8 Run it on the browser with the following URL,

http://localhost/modd/frontend/web/index.php?r=project/emp/message

Important Points:

Modules should be used for large applications. Divide its features into several groups and develop them as a module.
Modules should be reusable for the future projects.

Widgets

Widgets are reusable building blocks on client-side (containing JavaScript, HTML and CSS). They are used to create complex and configurable user interface elements in views.

For example, a Progress widget and DatePicker widget can create a progress bar and stylist date picker in your application.

Using Widgets

Widgets are majorly used in views. To call a widget you can call,

yii\base\Widget::widget()

This method takes a configuration array for initializing the widget.

For example, the following code inserts a date picker widget configured to use Russian language.

<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget([
'model' => $model,
'attribute' => 'from_date',
'language' => 'ru',
'clientOptions' => [
'dateFormat' => 'yy-mm-dd',
],
])
?>

Example

In this example, we'll use progress widget.

Step 1 Create an action actionWidget() in the SiteController.php file in the frontend directory.

public function actionWidget()
{
return $this->render('widget');
}

Look at the above code, we are rendering to the widget page in view folder.

Step 2 Create a page widget.php in the views/site folder in the frontend directory.

<?php
use yii\bootstrap\Progress;
?>
<?= Progress::widget(['percent' => 99, 'label' => 'Loading 99%']) ?>

Step 3 Run it on the browser with the URL,

http://localhost/wid/frontend/web/index.php?r=site/widget

Friday 6 January 2017

YII Frame Work Structures

Yii Structure

Yii2 Directory Structure

assets

commands

config

controllers

mail

models

runtime

tests

vendor

views

web

Yii Entry Scripts

Defining Constants

Yii Models

Attributes

Attribute Labels

Scenarios

Validation Rules

Massive Assignment

Views

Creating Views

View Conventions

Controllers

Controllers Action

Controllers Action

Creating Action

Action IDs

Inline Action

Standalone Action

Action Return Value

Action Parameters

Default Action

Modules

Module Structure

Module Class

Important Points:

Widgets

Using Widgets

No comments:

Post a Comment