<y:NodeLabelalignment="center"autoSizePolicy="content"fontFamily="Dialog"fontSize="12"fontStyle="plain"hasBackgroundColor="false"hasLineColor="false"height="17.96875"modelName="custom"textColor="#000000"visible="true"width="88.50390625"x="-24.488452911376953"y="-29.990825653076172">base de datos<y:LabelModel>
<y:NodeLabelalignment="center"autoSizePolicy="node_width"backgroundColor="#FFCC00"borderDistance="0.0"fontFamily="Dialog"fontSize="15"fontStyle="plain"hasLineColor="false"height="21.4609375"modelName="internal"modelPosition="t"textColor="#000000"visible="true"width="267.1120014190674"x="0.0"y="0.0">script de entrada</y:NodeLabel>
<y:NodeLabelalignment="center"autoSizePolicy="content"fontFamily="Dialog"fontSize="12"fontStyle="plain"hasBackgroundColor="false"hasLineColor="false"height="17.96875"modelName="custom"textColor="#000000"visible="true"width="211.193359375"x="4.043069839477539"y="6.015625">cargar configuración de aplicación<y:LabelModel>
<y:NodeLabelalignment="center"autoSizePolicy="content"fontFamily="Dialog"fontSize="12"fontStyle="plain"hasBackgroundColor="false"hasLineColor="false"height="17.96875"modelName="custom"textColor="#000000"visible="true"width="107.01953125"x="12.990234375"y="8.515625">script de entrada<y:LabelModel>
Cada vez que una aplicación Yii gestiona una petición, se somete a una flujo de trabajo similar.
1. Un usuario hace una petición al [script de entrada](structure-entry-scripts.md) ‘web/index.php’.
2. El script de entrada carga la [configuración](concept-configurations.md) y crea una instancia de la [aplicación](structure-applications.md) para gestionar la petición.
3. La aplicación resuelve la [ruta](runtime-routing.md) solicitada con la ayuda del componente [petición](runtime-requests.md) de la aplicación.
4. La aplicación crea una instancia del [controlador](structure-controllers.md) para gestionar la petición.
5. El controlador crea una instancia de la [acción](structure-controllers.md) y ejecuta los filtros para la acción.
6. Si algun filtro falla, se cancela la acción.
7. Si pasa todos los filtros, se ejecuta la acción.
8. La acción carga un modelo de datos, posiblemente de la base de datos.
9. La acción interpreta una vista, proporcionandole el modelo de datos.
10. El resultado interpretado se devuelve al componente [respuesta](runtime-responses.md) de la aplicación.
11. El componente respuesta envía el resultado interpretado al navegador del usuario.
El siguiente diagrama muestra como una aplicación gestiona una petición.
Los modelos forman parte de la arquitectura [MVC](http://es.wikipedia.org/wiki/Modelo%E2%80%93vista%E2%80%93controlador). Son objetos que representan datos de negocio, reglas y lógica.
Se pueden crear clases modelo extendiendo a [[yii\base\Model]] o a sus clases hijas. La clase base [[yii\base\Model]] soporta muchas características útiles:
*[Atributos](#attributes): representan los datos de negocio y se puede acceder a ellos como propiedades normales de un objeto o como elementos de un array;
*[Etiquetas de atributo](#attribute-labels): especifica la etiqueta a mostrar para los atributos;
*[Asignación masiva](#massive-assignment): soporta la asignación múltiple de atributos en un único paso;
*[validación](#validation-rules): asegura la validez de los datos de entrada basándose en reglas declaradas;
*[Exportación de datos](#data-exporting): permite que los datos del modelo sean exportados en términos de arrays con formatos personalizables.
La clase 'modelo' también es una base base para modelos más avanzados, tales como [Registros Activos](db-active-record.md).
>Info: No es obligatorio basar las clases modelo en [[yii\base\Model]]. Sin embargo, debido a que hay muchos componentes de Yii construidos para dar soporte a [[yii\base\Model]], por lo general es la clase base preferible para un modelo.
### Atributos <a name="attributes"></a>
Los modelos representan los datos de negocio en términos de *atributos*. Cada atributos es como una propiedad públicamente accesible de un modelo. El método [[yii\base\Model::attributes()]] especifica qué atributos tiene la clase modelo.
Se puede acceder a un atributo como se accede a una propiedad de un objeto normal.
```php
$model=new\app\models\ContactForm;
// "name" es un atributo de ContactForm
$model->name='example';
echo$model->name;
```
También se puede acceder a los atributos como se accede a los elementos de un array, gracias al soporte para [ArrayAccess](http://php.net/manual/es/class.arrayaccess.php) y [ArrayIterator](http://php.net/manual/es/class.arrayiterator.php) que brinda [[yii\base\Model]]:
Por defecto, si un modelo extiende directamente a [[yii\base\Model]], todas sus variables miembro no estáticas son atributos. Por ejemplo, la siguiente clase modelo 'ContactForm' tiene cuatro atributos: 'name', 'email', 'subject', 'body'. El modelo 'ContactForm' se usa para representar los datos de entrada recibidos desde un formulario HTML.
```php
namespaceapp\models;
useyii\base\Model;
classContactFormextendsModel
{
public$name;
public$email;
public$subject;
public$body;
}
```
Se puede sobrescribir [[yii\base\Model::attributes()]] para definir los atributos de diferente manera. El método debe devolver los nombres de los atributos de un modelo. Por ejemplo [[yii\db\ActiveRecord]] lo hace devolviendo el nombre de las columnas de la tabla de la base de datos asociada como el nombre de sus atributos. Hay que tener en cuenta que también puede necesitar sobrescribir los métodos mágicos como `__get()`, `__set()` de modo que se puede acceder a los atributos como a propiedades de objetos normales.
### Etiquetas de atributo <a name="attribute-labels"></a>
Cuando se muestran valores o se obtienen entradas para atributos, normalmente se necesita mostrar etiquetas asociadas a los atributos. Por ejemplo, dado un atributo con nombre 'segundoApellido', es posible que se quiera mostrar la etiqueta 'Segundo Apellido' ya que es más fácil de interpretar por el usuario final en lugares como campos de formularios y en mensajes de error.
Se puede obtener la etiqueta de un atributo llamando a [[yii\base\Model::getAttributeLabel()]] . Por ejemplo:
```php
$model=new\app\models\ContactForm;
// muestra "Name"
echo$model->getAttributeLabel('name');
```
Por defecto, una etiqueta de atributo se genera automáticamente a partir del nombre de atributo. La generación se hace con el método [[yii\base\Model::generateAttributeLabel()]]. Este convertirá los nombres de variables de tipo came-case en múltiples palabras con la primera letra de cada palabra en mayúsculas. Por ejemplo 'usuario' se convertirá en 'Nombre', y 'primerApellido' se convertirá en 'Primer Apellido'.
Si no se quieren usar las etiquetas generadas automáticamente, se puede sobrescribir [[yii\base\Model::attributeLabels()]] a una declaración de etiquetas de atributo especifica. Por ejemplo:
```php
namespaceapp\models;
useyii\base\Model;
classContactFormextendsModel
{
public$name;
public$email;
public$subject;
public$body;
publicfunctionattributeLabels()
{
return[
'name'=>'Your name',
'email'=>'Your email address',
'subject'=>'Subject',
'body'=>'Content',
];
}
}
```
Para aplicaciones con soporte para múltiples idiomas, se puede querer traducir las etiquetas de los atributos. Esto se puede hacer en el método [[yii\base\Model::attributeLabels()|attributeLabels()]], como en el siguiente ejemplo:
```php
publicfunctionattributeLabels()
{
return[
'name'=>\Yii::t('app','Your name'),
'email'=>\Yii::t('app','Your email address'),
'subject'=>\Yii::t('app','Subject'),
'body'=>\Yii::t('app','Content'),
];
}
```
Incluso se puede definir etiquetas de atributo condicionales. Por ejemplo, basándose en el [escenario](#scenarios) en que se esta usando el modelo, se pueden devolver diferentes etiquetas para un mismo atributo.
> Info: Estrictamente hablando, los atributos son parte de las [vistas](structure-views.md). Pero declarar las etiquetas en los modelos, a menudo, es muy conveniente y puede generar a un código muy limpio y reutilizable.
## Escenarios <a name="scenarios"></a>
Un modelo puede usarse en diferentes *escenarios*. Por ejemplo, un modelo 'Usuario', puede ser utilizado para recoger entradas de inicio de sesión de usuarios, pero también puede usarse para generar usuarios. En diferentes escenarios, un modelo puede usar diferentes reglas de negocio y lógica. Por ejemplo, un atributo 'email' puede ser requerido durante un registro de usuario, pero no ser necesario durante el inicio de sesión del mismo.
Un modelo utiliza la propiedad [[yii\base\Model::scenario]] para mantener saber en qué escenario se esta usando. Por defecto, un modelo soporta sólo un escenario llamado 'default'. El siguiente código muestra dos maneras de establecer el escenario en un modelo.
```php
// el escenario se establece como una propiedad
$model=newUser;
$model->scenario='login';
// el escenario se establece mediante configuración
$model=newUser(['scenario'=>'login']);
```
Por defecto, los escenarios soportados por un modelo se determinan por las [reglas de validación](#validation-rules) declaradas en el modelo. Sin embargo, se puede personalizar este comportamiento sobrescribiendo el método [[yii\base\Model::scenarios()]], como en el siguiente ejemplo:
```php
namespaceapp\models;
useyii\db\ActiveRecord;
classUserextendsActiveRecord
{
publicfunctionscenarios()
{
return[
'login'=>['username','password'],
'register'=>['username','email','password'],
];
}
}
```
> Info: En el anterior y en los siguientes ejemplos, las clases modelo extienden a [[yii\db\ActiveRecord]] porque el uso de múltiples escenarios normalmente sucede con clases de [Registros Activos](db-active-record.md).
El método 'scenarios()' devuelve un array cuyas claves son el nombre de escenario y los valores correspondientes a los *atributos activos*. Un atributo activo puede ser [asignado masivamente](#massive-assignment) y esta sujeto a [validación](#validation-rules). En el anterior ejemplo, los atributos 'username' y 'password' están activados en el escenario 'login'; mientras que en el escenario 'register', el atributo 'email' esta activado junto con 'username' y 'password'.
La implementación por defecto de los 'scenarios()' devolverá todos los escenarios encontrados en el método de declaración de las reglas de validación [[yii\base\Model::rules()]]. Cuando se sobrescribe 'scenarios()', si se quiere introducir nuevos escenarios además de los predeterminados, se puede hacer como en el siguiente ejemplo:
La característica escenario se usa principalmente en las [validaciones](#validation-rules) y por la [asignación masiva de atributos](#massive-assignment). Aunque también se puede usar para otros propósitos. Por ejemplo, se pueden declarar [etiquetas de atributo](#attribute-labels) diferentes basándose en el escenario actual.
## Reglas de Validación <a name="validation-rules"></a>
Cuando un modelo recibe datos del usuario final, estos deben ser validados para asegurar que cumplan ciertas reglas (llamadas *reglas de validación*, también conocidas como *reglas de negocio*). Por ejemplo, dado un modelo 'ContactForm', se puede querer asegurar que ningún atributo este vacío y que el atributo 'email' contenga una dirección de correo válida. Si algún valor no cumple con las reglas, se debe mostrar el mensaje de error apropiado para ayudar al usuario a corregir estos errores.
Se puede llamar a [[yii\base\Model::validate()]] para validar los datos recibidos. El método se usará para validar las reglas declaradas en [[yii\base\Model::rules()]] para validar cada atributo relevante. Si no se encuentran errores, se devolverá true. De otro modo, este almacenará los errores en la propiedad [[yii\base\Model::errors]] y devolverá falso. Por ejemplo:
```php
$model=new\app\models\ContactForm;
// establece los atributos del modelo con la entrada de usuario
// validación fallida: $errors es un array que contiene los mensajes de error
$errors=$model->errors;
}
```
Para declarar reglas de validación asociadas a un modelo, se tiene que sobrescribir el método [[yii\base\Model::rules()]] para que devuelva las reglas que los atributos del modelo deben satisfacer. El siguiente ejemplo muestra las reglas de validación declaradas para el modelo 'ContactForm'.
```php
publicfunctionrules()
{
return[
// name, email, subject y body son atributos requeridos
[['name','email','subject','body'],'required'],
// el atribuido email debe ser una dirección de correo electrónico válida
['email','email'],
];
}
```
Una regla puede usarse para validar uno o más atributos, y un atributo puede validarse por una o múltiples reglas. Por favor refiérase a la sección [Validación de entrada](input-validation.md) para obtener más detalles sobre cómo declarar reglas de validación.
A veces, solamente se quiere aplicar una regla en ciertos [escenarios](#scenarios). Para hacerlo, se puede especificar la propiedad 'on' de una regla, como en el siguiente ejemplo:
```php
publicfunctionrules()
{
return[
// username, email y password son obligatorios en el escenario “register”
Si no se especifica la propiedad 'on', la regla se aplicará en todos los escenarios. Se llama a una regla *regla activa* si esta puede aplicarse en el [[yii\base\Model::scenario|scenario]] actual.
Un atributo será validado si y sólo si es un atributo activo declarado en 'scenarios()' y esta asociado con una o más reglas activas declaradas en 'rules()'.
La asignación masiva es una buena forma de rellenar los atributos de un modelo con las entradas de usuario en una única línea de código. Rellena los atributos de un modelo asignando los datos de entrada directamente a las propiedades de [[yii\base\Model::$attributes]]. Los siguientes dos ejemplos son equivalentes, ambos intentan asignar los datos enviados por el usuario final a través de un formulario a los atributos del modelo 'ContactForm'. Claramente, el primero, que usa la asignación masiva, es más claro y menos propenso a errores que el segundo:
La asignación masiva sólo se aplica a los llamados *atributos seguros* qué son los atributos listados en [[yii\base\Model::scenarios()]] para el actual [[yii\base\Model::scenario|scenario]] del modelo. Por ejemplo, si en el modelo 'User' tenemos la siguiente declaración de escenario, entonces cuando el escenario actual sea 'login', sólo los atributos 'username' y 'password' podrán ser asignados masivamente. Cualquier otro atributo permanecerá intacto
```php
publicfunctionscenarios()
{
return[
'login'=>['username','password'],
'register'=>['username','email','password'],
];
}
```
> Info: La razón de que la asignación masiva sólo se aplique a los atributos seguros es debida a que se quiere controlar qué atributos pueden ser modificados por los datos del usuario final. Por ejemplo, si el modelo 'User' tiene un atributo 'permission' que determina los permisos asignados al usuario, se quiere que estos atributos sólo sean modificados por administradores desde la interfaz backend.
Debido a hecho que la implementación por defecto de [[yii\base\Model::scenarios()]] devolverá todos los escenarios y atributos encontrados en[[yii\base\Model::rules()]], si no se sobrescribe este método, significa que un atributo es seguro mientras aparezca en una de las reglas de validación activas.
Por esta razón, se proporciona un validador especial con alias 'safe' con el que se puede declarar un atributo como seguro sin llegar a validarlo. Por ejemplo, las siguientes reglas declaran que los atributos 'title' y 'description' son atributos seguros.
Como se ha descrito anteriormente, el método [[yii\base\Model::scenarios()]] sirve para dos propósitos: determinar qué atributos deben ser validados y determinar qué atributos son seguros. En situaciones poco comunes, se puede querer validar un atributo pero sin marcarlo como seguro. Se puede hacer prefijando el signo de exclamación '!' delante del nombre del atributo cuando se declaran en 'scenarios()', como el atributo 'secret' del siguiente ejemplo:
```php
publicfunctionscenarios()
{
return[
'login'=>['username','password','!secret'],
];
}
```
Cuando el modelo esté en el escenario 'login', los tres atributos serán validados. Sin embargo, sólo los atributos 'username' y 'password' se asignarán masivamente. Para asignar un valor de entrada al atribuido 'secret', se tendrá que hacer explícitamente como en el ejemplo:
```php
$model->secret=$secret;
```
## Exportación de Datos <a name="data-exporting"></a>
A menudo necesitamos exportar modelos a diferentes formatos. Por ejemplo, se puede querer convertir un conjunto de modelos a formato JSON o Excel. El proceso de exportación se puede dividir en dos pasos independientes. En el primer paso, se convierten los modelos en arrays; en el segundo paso, los arrays se convierten a los formatos deseados. Nos puede interesar fijarnos en el primer paso, ya que el segundo paso se puede lograr mediante un formateador de datos genérico, tal como [[yii\web\JsonResponseFormatter]].
La manera más simple de convertir un modelo en un array es usar la propiedad [[yii\base\Model::$attributes]]. Por ejemplo:
```php
$post=\app\models\Post::findOne(100);
$array=$post->attributes;
```
Por defecto, la propiedad [[yii\base\Model::$attributes]] devolverá los valores de *todos* los atributos declarados en [[yii\base\Model::attributes()]].
Una manera más flexible y potente de convertir un modelo en un array es usar el método [[yii\base\Model::toArray()]]. Su funcionamiento general es el mismo que el de [[yii\base\Model::$attributes]]. Sin embargo, este permite elegir que elementos de datos, llamados *campos*, queremos poner en el array resultante y elegir como debe ser formateado. De hecho, es la manera por defecto de exportar modelos en desarrollo de servicios Web RESTful, tal y como se describe en [Formatos de Respuesta](rest-response-formatting.md).
### Campos <a name="fields"></a>
Un campo es simplemente un elemento nombrado en el array resultante de ejecutar el método [[yii\base\Model::toArray()]] de un modelo.
Por defecto, los nombres de los campos son equivalentes a los nombres de los atributos. Sin embargo, se puede modificar este comportamiento sobrescribiendo el método [[yii\base\Model::fields()|fields()]] y/o el método [[yii\base\Model::extraFields()|extraFields()]]. Ambos métodos deben devolver una lista de las definiciones de los campos. Los campos definidos mediante 'fields()' son los campos por defecto, esto significa que 'toArray()' devolverá estos campos por defecto. El método 'extraFields()' define campos adicionalmente disponibles que también pueden devolverse mediante 'toArray()' siempre y cuando se especifiquen a través del parámetro '$expand'. Por ejemplo, el siguiente código devolverá todos los campos definidos en 'fields()' y los campos 'prettyName' y 'fullAdress' si estos están definidos en 'extraFields()'.
Se puede sobrescribir 'fields()' para añadir, eliminar, renombrar o redefinir campos. El valor devuelto por 'fields()' debe se un array. Las claves del array son los nombres de los campos, y los valores son las correspondientes definiciones de los campos que pueden ser nombres de propiedades/atributos o funciones anónimas que devuelvan los correspondientes valores de campo. En el caso especial en que un nombre de un campo es el mismo a su definición de nombre de atributo, se puede omitir la clave del array. Por ejemplo:
```php
// lista explícitamente cada campo, es mejor usarlo cuando nos queremos asegurar
// de que los cambios en la tabla de la base de datos o los atributos del modelo
// no modifiquen los campos(para asegurar compatibilidades para versiones anteriores de API)
publicfunctionfields()
{
return[
// el nombre del campo es el mismo que el nombre de atributo
'id',
// el nombre del campo es “email”, el nombre de atributo correspondiente es “email_address”
'email'=>'email_address',
// El nombre del campo es “name”, su valor esta definido por una llamada de retorno PHP
'name'=>function(){
return$this->first_name.' '.$this->last_name;
},
];
}
// filtrar algunos campos, es mejor usarlo cuando se quiere heredar la implementación del padre
// y discriminar algunos campos sensibles.
publicfunctionfields()
{
$fields=parent::fields();
// elimina campos que contengan información sensible.
>Atención: debido a que por defecto todos los atributos de un modelo serán incluidos en el array exportado, se debe examinar los datos para asegurar que no contienen información sensible. Si existe dicha información, se debe sobrescribir 'fields()' para filtrarla. En el anterior ejemplo, se filtra 'aut_key', 'password_hash' y 'password_reset_token'.
Los modelos son los lugares centrales para representar datos de negocio, reglas y lógica. Estos a menudo necesitan ser reutilizados en diferentes lugares. En una aplicación bien diseñada, los modelos normalmente son más grandes que los [controladores](structure-controllers.md).
En resumen, los modelos:
* pueden contener atributos para representar los datos de negocio;
* pueden contener reglas de validación para asegurar la validez e integridad de los datos;
* pueden contener métodos que para implementar la lógica de negocio;
* NO deben acceder directamente a peticiones, sesiones, o otro tipo de datos de entorno. Estos datos deben ser inyectados por los [controladores](structure-controllers.md) en los modelos.
* deben evitar embeber HTML o otro código de presentación – esto es mejor hacerlo en las [vistas](structure-views.md);
* evitar tener demasiados [escenarios](#scenarios) en un mismo modelo.
Generalmente se puede considerar la última recomendación cuando se estén desarrollando grandes sistemas complejos. En estos sistemas, los modelos podrían ser muy grandes debido a que podrían ser usados en muchos lugares y por tanto contener muchos conjuntos de reglas y lógicas de negocio. A menudo esto desemboca en un código muy difícil de mantener ya que una simple modificación en el código puede afectar a muchos sitios diferentes. Para mantener el código más fácil de mantener, se puede seguir la siguiente estrategia:
* Definir un conjunto de clases modelo base que sean compartidas por diferentes [aplicaciones](structure-applications.md) o [módulos](structure-modules.md). Estas clases modelo deben contener el conjuntos mínimos de reglas y lógica que sean comunes para todos sus usos.
* En cada [aplicación](structure-applications.md) o [módulo](structure-modules.md) que use un modelo, definir una clase modelo concreta que extienda a la correspondiente clase modelo base. La clase modelo concreta debe contener reglas y lógica que sean específicas para esa aplicación o módulo.
Por ejemplo, en la [Plantilla de Aplicación Avanzada](tutorial-advanced-app.md), definiendo una clase modelo base 'common\models\Post'. Después en la aplicación front end, definiendo y usando una clase modelo concreta 'frontend\models\Post' que extienda a 'common\models\Post'. Y de forma similar en la aplicación back end, definiendo 'backend\models\Post'. Con esta estrategia, nos aseguramos que el código de 'frontend\models\Post' es específico para la aplicación front end, y si se efectúa algún cambio en el, no nos tenemos que preocupar de si el cambio afectará a la aplicación back end.
Los módulos son unidades de software independientes que consisten en [modelos](structure-models.md), [vistas](structure-views.md), [controladores](structure-controllers.md), y otros componentes de apoyo. Los usuarios finales pueden acceder a los controladores de un módulo cuando éste está instalado en la [aplicación](structure-applications.md). Por éstas razones, los módulos a menudo se considerados como mini-aplicaciones. Los módulos difieren de las [aplicaciones](structure-applications.md) en que los módulos no pueden ser desplegados solos y tienen que residir dentro de aplicaciones.
## Creación de Módulos<a name="creating-modules"></a>
Un módulo está organizado de tal manera que contiene un directorio llamado [[yii\base\Module::basePath|base path]] del módulo. Dentro de este directorio, hay subdirectorios tales como 'controllers', 'models', 'views', que contienen controladores, modelos, vistas y otro código, exactamente como una aplicación. El siguiente ejemplo muestra el contenido dentro de un módulo:
```
forum/
Module.php archivo clase módulo
controllers/ contiene archivos de la clase controlador
DefaultController.php archivo clase controlador por defecto
models/ contiene los archivos de clase modelo
views/ contiene las vistas de controlador y los archivos de diseño
layouts/ contiene los archivos de diseño de las vistas
default/ contiene los archivos de vista del DefaultController
index.php archivo de vista del index
```
### Clases Módulo <a name="module-classes"></a>
Cada módulo debe tener una única clase módulo que extiende a [[yii\base\Module]]. La clase debe encontrarse directamente debajo del [[yii\base\Module::basePath|base path]] y debe ser [autocargable](concept-autoloading.md). Cuando se está accediendo a un módulo, se creará una única instancia de la clase módulo correspondiente. Como en las [instancias de aplicación](structure-applications.md), las instancias de módulo se utilizan para compartir datos y componentes de código dentro de los módulos.
El siguiente ejemplo muestra como podría ser una clase módulo.
```php
namespaceapp\modules\forum;
classModuleextends\yii\base\Module
{
publicfunctioninit()
{
parent::init();
$this->params['foo']='bar';
// ... otro código de inicialización ...
}
}
```
Si el método 'init()' contiene mucho código de inicialización de las propiedades del módulo, también se puede guardar en términos de configuración y cargarlo con el siguiente código ‘init()’:
```php
publicfunctioninit()
{
parent::init();
// inicializa el módulo con la configuración cargada desde config.php
donde el archivo de configuracion ‘config.php’ puede contaner el siguiente contenido, similar al de [configuraciones de aplicacion](structure-applications.md#application-configurations).
```php
<?php
return[
'components'=>[
// lista de configuraciones de componente
],
'params'=>[
// lista de parámetros
],
];
```
### Controladores en Módulos <a name="controllers-in-modules"></a>
Cuando se crean controladores en un modelo, una convención es poner las clases controlador debajo del sub espacio de nombres de ‘controllers’ del espacio de nombres de la clase módulo. Esto también significa que los archivos de la clase controlador deben ponerse en el directorio ‘controllers’ dentro del [[yii\base\Module::basePath|base path]] del módulo. Por ejemplo, para crear un controlador ‘post’ en el módulo ‘forum’ mostrado en la última subdivisión, se debe declarar la clase controlador de la siguiente manera:
```php
namespaceapp\modules\forum\controllers;
useyii\web\Controller;
classPostControllerextendsController
{
// ...
}
```
Se puede personalizar el espacio de nombres de las clases controlador configurando la propiedad [[yii\base\Module::controllerNamespace]]. En el caso que alguno de los controladores esté fuera del espacio de nombres, se puede hacer acesible configurando la propiedad [[yii\base\Module::controllerMap]], similar a [como se hace en una aplicación](structure-applications.md#controller-map).
### Vistas en Módulos <a name="views-in-modules"></a>
Las vistas en un módulo deben deben alojarse en el directorio ‘views’ dentro del módulo del [[yii\base\Module::basePath|base path]]. Las vistas interpretadas por un controlador en el módulo, deben alojarse en el directorio ‘views/ControllerID’, donde el ‘ControllerID’ hace referencia al [identificador del controlador](structure-controllers.md#routes). Por ejemplo, si la clase controlador es ‘PostController’, el directorio sería ‘views/post’ dentro del [[yii\base\Module::basePath|base path]] del módulo.
Un modulo puede especificar un [layout](structure-views.md#layouts) que se aplica a las vistas interpretadas por los controladores del módulo. El layout debe alojarse en el directorio ‘views/layouts’ por defecto, y se puede configurar la propiedad [[yii\base\Module::layout]] para apuntar al nombre del layout. Si no se configura la propiedad ‘layout’, se usar el layout de la aplicación.
## Uso de los Módulos <a name="using-modules"></a>
Para usar un módulo en una aplicación, simplemente se tiene que configurar la aplicación añadiendo el módulo en la propiedad [[yii\base\Application::modules|modules]] de la aplicación. El siguiente ejemplo de la [configuración de la aplicación](structure-applications.md#application-configurations) usa el modelo ‘forum’:
```php
[
'modules'=>[
'forum'=>[
'class'=>'app\modules\forum\Module',
// ... otras configuraciones para el módulo ...
],
],
]
```
La propiedad [[yii\base\Application::modules|modules]] contiene un array de configuraciones de módulo. Cada clave del array representa un *identificador de módulo* que identifica de forma única el módulo de entre todos los módulos de la aplicación, y el correspondiente valor del array es la [configuración](concept-configurations.md) para crear el módulo.
### Rutas <a name="routes"></a>
De Igual manera que el acceso a los controladores en una aplicacion, las [rutas](structure-controllers.md#routes) se utiliza para dirigirse a los controladores en un módulo. Una ruta para un controlador dentro de un módulo debe empezar con el identificador del módulo seguido por el identificador del controlador y el identificador de la acción. Por ejemplo, si una aplicación usa un módulo llamado ‘forum’, la ruta ‘forum/post/index’ representaría la acción ‘index’ del controlador ‘post’ en el módulo. Si la ruta sólo contiene el identificador del módulo, entonces la propiedad [[yii\base\Module::defaultRoute]] que por defecto es ‘default’, determinara que controlador/acción debe usarse. Esto significa que la ruta ‘forum’ representaría el controlador ‘default’ en el módulo ‘forum’.
### Acceder a los Módulos <a name="accessing-modules"></a>
Dentro de un módulo, se puede necesitar obtener la instancia de la [clase módulo](#module-classes) para poder acceder al identificador del módulo, componentes del módulo, etc. Se puede hacer usando la siguiente declaración:
```php
$module=MyModuleClass::getInstance();
```
donde ‘MyModuleClass’ hace referencia al nombre de la clase módulo en la que estemos interesados. El método ‘getInstance()’ devolverá la instancia actualmente solicitada de la clase módulo. Si no se solicita el módulo, el método devolverá nulo. Hay que tener en cuenta que si se crea una nueva instancia del módulo, esta será diferente a la creada por Yii en respuesta a la solicitud.
>Info: Cuando se desarrolla un módulo, no se debe dar por sentado que el módulo usará un identificador fijo. Esto se debe a que un módulo puede asociarse a un identificador arbitrario cuando se usa en una aplicación o dentro de otro módulo. Para obtener el identificador del módulo, primero se debe usar el código del anterior ejemplo para obtener la instancia y luego el identificador mediante ‘$modeule->id’.
También se puede acceder a la instancia de un módulo usando las siguientes declaraciones:
```php
// obtiene el modulo hijo cuyo identificador es “forum”
$module=\Yii::$app->getModule('forum');
// obtiene el módulo al que pertenece la petición actual
$module=\Yii::$app->controller->module;
```
El primer ejemplo sólo es útil cuando conocemos el identificador del módulo, mientras que el segundo es mejor usarlo cuando conocemos los controladores que se están solicitando.
Una vez obtenida la instancia del módulo, se puede acceder a parámetros o componentes registrados con el módulo. Por ejemplo:
Puede darse el caso en que necesitemos que un módulo se ejecute en cada petición. El módulo [[yii\debug\Module|debug]] es un ejemplo. Para hacerlo, tenemos que listar los identificadores de los módulos en la propiedad [[yii\base\Application::bootstrap|bootstrap]] de la aplicación.
Por ejemplo, la siguiente configuración de aplicación se asegura de que el módulo ‘debug’ siempre se cargue:
```php
[
'bootstrap'=>[
'debug',
],
'modules'=>[
'debug'=>'yii\debug\Module',
],
]
```
## Módulos anidados <a name="nested-modules"></a>
Los módulos pueden ser anidados sin límite de niveles. Es decir, un módulo puede contener un módulo y éste a la vez contener otro módulo. Nombramos *padre* al primero mientras que al segundo lo nombramos *hijo*. Los módulos hijo se tienen que declarar en la propiedad [[yii\base\Module::modules|modules]] de sus módulos padre. Por ejemplo:
```php
namespaceapp\modules\forum;
classModuleextends\yii\base\Module
{
publicfunctioninit()
{
parent::init();
$this->modules=[
'admin'=>[
// debe considerarse usar un nombre de espacios más corto!
En un controlador dentro de un módulo anidado, la ruta debe incluir el identificador de todos los módulos antecesores. Por ejemplo, la ruta ‘forum/admin/dashboard/index’ representa la acción ‘index’ del controlador ‘dashboard’ en el módulo ‘admin’ que es el módulo hijo del módulo ‘forum’.
>Info: El método [[yii\base\Module::getModule()|getModule()]] sólo devuelve el módulo hijo que pertenece directamente a su padre. La propiedad [[yii\base\Application::loadedModules]] contiene una lista de los módulos cargados, incluyendo los hijos directos y los anidados, indexados por sus nombres de clase.
Es mejor usar los módulos en grandes aplicaciones en las que sus funcionalidades puedan ser divididas en diferentes grupos, cada uno compuesto por funcionalidades directamente relacionadas. Cada grupo de funcionalidades se puede desarrollar como un módulo que puede ser desarrollado y mantenido por un programador o equipo específico.
Los módulos también son una buena manera de reutilizar código a nivel de grupo de funcionalidades. Algunas funcionalidades de uso común, tales como la gestión de usuarios o la gestión de comentarios, pueden ser desarrollados como módulos para que puedan ser fácilmente reutilizados en futuros proyectos.
