<commit_before>Sammaye's Application Template
===================================

This is a template for the Yii 2 advanced application which I have decided to release.

**But why?**

This template was born out of a number of a projects, including an e-commerce site. Covering a common set of functionality I kept implementing between them.

I also seemed to always do this very repetitively as such I sought to remedy that. It incorporates what I feel is a good structure, this does, of course, make it opinionated but might give you pointers as well; might even be exactly what your looking for.

Maybe it will help someone.

First I will talk abut the structure and then I will delve into the things I have done. I will attempt to explain it concisely however, it is likely I may miss things out.

This guide is intended for those who already know Yii 2 and the structure of a normal advanced application. If you are not one of those individuals [please investigate their 
readme first](https://github.com/yiisoft/yii2/blob/master/apps/advanced/README.md).

# DIRECTORY STRUCTURE

```
common
	components/			contains all of the extended components of the framework
	config/				contains shared configurations
	mail/				contains view/template files for e-mails
	rbac/				contains the role based permissions configuration
	models/				contains model classes used in both backend and frontend
	tests/				contains various tests for objects that are common among applications
	widgets/			contains widgets common to both back and front end
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 (Does not actually exist)
	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 (Does not actually exist)
	runtime/			contains files generated during runtime
	tests/				contains various tests for the frontend application
	views/				contains view files for the Web application
	web/				contains the entry script and Web resources
vendor/					contains dependent 3rd-party packages
environments/			contains environment-based overrides
```

## Structure Changes

The directory structure has changed a little to a version that I have tested as being quite good. The main changes revolve around moving stuff to the `common/` folder. `common/` holds all of the stuff that is common to the application globally. 

### common/components/

`components/` holds all of the extended Yii 2 components such as custom `Controller`, `User` and `Request` objects.

You can put extensions in here but you may find it better to put them in an `extensions/` folder, it is entirely up to your better judgement.

### common/mail/

This folder contains all the stuff for mail, from templates to view files.

The mail templates and views are strictly common globally to the entire application.

### common/rbac/

This folder contains the RBAC configuration including rule classes. 

Again this is globally common across the entire application.

### common/models/

I have made all models reside in `common/models` including the `SignupForm.php`, `PasswordResetRequestForm.php` and the `ResetPasswordForm.php`.

The reason for adding even these, normally frontend, models is because I found more and more that they are also useful on the backend. You want employees of a company 
using the backend to be able to register and reset their passwords without having to jump between two systems; especially if they are a new employee on their first 
day of work registering a new account in your system.

This means that the `models/` folder in both backend and frontend do not actually exist, but they can if you really need them to.

### common/widgets/

This folder contains global widgets.

There are a number of widgets you may find are actually global to your entire application, for example: I have already added the `Alert` widget as a global widget and added it to both the frontend and the backend layout.

### frontend/models/

Now moved to `common/models`.

### backend/models/

Now moved to `common/models`.


# COMPOSER

Composer has been changed. What it installs by default has been expanded and/or changed.

This project, by defauult, will download the MongoDB extension. I will explain later how to rid it of that, it is literally 2 lines of changes.

Here is a brief but comphrensive list of changes in composer:

- `yii2-mongodb` has been added and is the default database of the application
- jQuery installs a IE 8 and 9 compliant edition
- jQuery UI install a IE 8 and 9 compliant edition
- `yii2-jui` extension has been added
- `yii2-imagine` has been added for image manipulation capabilities

# CONFIGURATION

It is important to get to grips with the configuration and how it is laid out before you start fiddling.

Most of the configuration is placed within `common/config/main.php` however a sizeable amount of customisation exists within `backend/config/main.php` and `frontend/config/main.php`.

The `common/config/main.php` contains:

- Url Manager
- user
- session
- cache
- request
- mailer
- Asset Manager
- RBAC

These parts are essential to the site in general, both frontend and backend.

The asset manager configuration provides the ability to have a custom Bootstrap with your own theme and CSS for it.

The RBAC configuration allows for the default RBAC that is set-up in this template, refer to the RBAC section below.

The other parts are not so important and do pretty much what they say on the tin. Ensure to take a good long look at the configuration files and also the `params.php` files within those directories.

The `params.php` files tends to hold varibles which are helpful, these should be explained later in their own "feature" section, for which their functionality refers to. These files are quite bare currently so do not be surprised if you hear nothing of them again.

Some of the configuration is defined within the environments folder too, essentially the database, for example: SQL and MongoDB are both defined in the environments folder's own configuration files.

# CONTROLLERS

All controllers now inherit from `common\components\Controller` which provides tier 2 functionality, which will be discussed later.

The `common\components\Controller` class runs a `beforeAction` event which can be expanded with your own functionality.

# FEATURES

## common\models\Request

### CSRF Routes<commit_msg>Improved readme headers<commit_after>Sammaye's Application Template
===================================

This is a template for the Yii 2 advanced application which I have decided to release.

**But why?**

This template was born out of a number of a projects, including an e-commerce site. Covering a common set of functionality I kept implementing between them.

I also seemed to always do this very repetitively as such I sought to remedy that. It incorporates what I feel is a good structure, this does, of course, make it opinionated but might give you pointers as well; might even be exactly what your looking for.

Maybe it will help someone.

First I will talk abut the structure and then I will delve into the things I have done. I will attempt to explain it concisely however, it is likely I may miss things out.

This guide is intended for those who already know Yii 2 and the structure of a normal advanced application. If you are not one of those individuals [please investigate their 
readme first](https://github.com/yiisoft/yii2/blob/master/apps/advanced/README.md).

- [Github Repository](https://github.com/Sammaye/yii2-advanced-template)
- [Packagist Entry](https://packagist.org/packages/sammaye/yii2-advanced-template)
- [Issue Tracker](https://github.com/Sammaye/yii2-advanced-template/issues)

# Directory Structure

```
common
	components/			contains all of the extended components of the framework
	config/				contains shared configurations
	mail/				contains view/template files for e-mails
	rbac/				contains the role based permissions configuration
	models/				contains model classes used in both backend and frontend
	tests/				contains various tests for objects that are common among applications
	widgets/			contains widgets common to both back and front end
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 (Does not actually exist)
	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 (Does not actually exist)
	runtime/			contains files generated during runtime
	tests/				contains various tests for the frontend application
	views/				contains view files for the Web application
	web/				contains the entry script and Web resources
vendor/					contains dependent 3rd-party packages
environments/			contains environment-based overrides
```

## Structure Changes

The directory structure has changed a little to a version that I have tested as being quite good. The main changes revolve around moving stuff to the `common/` folder. `common/` holds all of the stuff that is common to the application globally. 

### common/components/

`components/` holds all of the extended Yii 2 components such as custom `Controller`, `User` and `Request` objects.

You can put extensions in here but you may find it better to put them in an `extensions/` folder, it is entirely up to your better judgement.

### common/mail/

This folder contains all the stuff for mail, from templates to view files.

The mail templates and views are strictly common globally to the entire application.

### common/rbac/

This folder contains the RBAC configuration including rule classes. 

Again this is globally common across the entire application.

### common/models/

I have made all models reside in `common/models` including the `SignupForm.php`, `PasswordResetRequestForm.php` and the `ResetPasswordForm.php`.

The reason for adding even these, normally frontend, models is because I found more and more that they are also useful on the backend. You want employees of a company 
using the backend to be able to register and reset their passwords without having to jump between two systems; especially if they are a new employee on their first 
day of work registering a new account in your system.

This means that the `models/` folder in both backend and frontend do not actually exist, but they can if you really need them to.

### common/widgets/

This folder contains global widgets.

There are a number of widgets you may find are actually global to your entire application, for example: I have already added the `Alert` widget as a global widget and added it to both the frontend and the backend layout.

### frontend/models/

Now moved to `common/models`.

### backend/models/

Now moved to `common/models`.

# Composer

Composer has been changed. What it installs by default has been expanded and/or changed.

This project, by defauult, will download the MongoDB extension. I will explain later how to rid it of that, it is literally 2 lines of changes.

Here is a brief but comphrensive list of changes in composer:

- `yii2-mongodb` has been added and is the default database of the application
- jQuery installs a IE 8 and 9 compliant edition
- jQuery UI install a IE 8 and 9 compliant edition
- `yii2-jui` extension has been added
- `yii2-imagine` has been added for image manipulation capabilities

# Configuration

It is important to get to grips with the configuration and how it is laid out before you start fiddling.

Most of the configuration is placed within `common/config/main.php` however a sizeable amount of customisation exists within `backend/config/main.php` and `frontend/config/main.php`.

The `common/config/main.php` contains:

- Url Manager
- user
- session
- cache
- request
- mailer
- Asset Manager
- RBAC

These parts are essential to the site in general, both frontend and backend.

The asset manager configuration provides the ability to have a custom Bootstrap with your own theme and CSS for it.

The RBAC configuration allows for the default RBAC that is set-up in this template, refer to the RBAC section below.

The other parts are not so important and do pretty much what they say on the tin. Ensure to take a good long look at the configuration files and also the `params.php` files within those directories.

The `params.php` files tends to hold varibles which are helpful, these should be explained later in their own "feature" section, for which their functionality refers to. These files are quite bare currently so do not be surprised if you hear nothing of them again.

Some of the configuration is defined within the environments folder too, essentially the database, for example: SQL and MongoDB are both defined in the environments folder's own configuration files.

# Controllers

All controllers now inherit from `common\components\Controller` which provides tier 2 functionality, which will be discussed later.

The `common\components\Controller` class runs a `beforeAction` event which can be expanded with your own functionality.

# Features

## common\models\Request

### CSRF Routes
{'fraction_non_alphanumeric': 0.04876880984952121, 'fraction_numerical': 0.0021203830369357045, 'mean_word_length': 4.203202846975089, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 5, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3643997', 'n_tokens_mistral': 3712, 'n_tokens_neox': 3504, 'n_words': 2069}