Cómo programar con Yii2: Subir archivos

() translation by (you can also view the original English article)

Final product image — What You'll Be Creating

Si se está preguntando, "¿Qué es Yii?" Echa un vistazo a mi tutorial anterior: Introducción a Yii Framework, que revisa los beneficios de Yii e incluye una visión general de lo que es nuevo en Yii 2.0, publicado en octubre de 2014.

En este capitulo de la serie Cómo programar con Yii2, estoy orientando a los lectores en el uso de Yii2 Framework para PHP. En este tutorial, te guiaré a través de los conceptos básicos de subir archivos e imágenes en Yii2.

Para estos ejemplos, seguiremos imaginando que estamos construyendo un framework para publicar actualizaciones de estado simples, por ejemplo nuestro propio mini-Twitter. La imagen de arriba demuestra escribir una actualización corta al subir una foto que tomé del Taj Mahal.

Sólo un recordatorio, yo participo en los comentarios. Estoy especialmente interesado si tiene diferentes enfoques, ideas adicionales o desea sugerir temas para futuros tutoriales. Si tiene alguna pregunta o sugerencia de tema, por favor, hazla. También puede contactarme directamente en Twitter @reifman.

Complementos de carga de archivos

Yii2 Image Uploads - Kartik File Input Widget Demo Examples

Hay dos complementos de carga de archivos para Yii2 que parecen los más robustos:

El Widget FileInput de Kartik Visweswaran (mostrado arriba)
El 2Amigos BlueImp File Uploader (un envoltorio para el BlueImp JQuery File Uploader)

Para este tutorial, decidí continuar con el complemento de Kartik. Lo encontré más fácil de usar y mejor documentado que el complemento 2Amigos. Sin embargo, el BlueImp File Uploader tiene algunas características intrigantes de la experiencia del usuario que puede que desee explorar (se muestra a continuación):

Yii2 Image Uploads - 2Amigos and BlueImp File Upload Examples

Programando con el complemento FileInput

Comencemos por instalar y utilizar el cargador de archivos e integrarlo en nuestro applet de publicación de estados tipo-Twitter. Una vez más, usaremos el árbol de aplicaciones de Yii2 Hello que puedes descargar con el enlace del botón de GitHub del costado o debajo.

Instalación del complemento

Primero, podemos usar composer para agregar kartik-v/yii2-widget-fileinput a su aplicación:

$ composer require kartik-v/yii2-widget-fileinput "*"
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Updating kartik-v/yii2-widget-fileinput (dev-master 36f9f49 => v1.0.4)
    Checking out 36f9f493c2d814529f2a195422a8af2e020fc80c

Writing lock file
Generating autoload files

Ampliando de la tabla estado

A continuación, debemos agregar campos para el archivo que subiremos a nuestra tabla estado. En este ejemplo, dejaremos que el usuario cargue una imagen para ir junto con su estado.

Los campos que agregaremos son para el nombre de archivo original de los archivos cargados, así como un nombre de archivo único que se almacenará en nuestro servidor para su visualización:

image_src_filename
image_web_filename

Cree una nueva migración para agregar estos campos a la tabla estado:

$ ./yii migrate/create extend_status_table_for_image
Yii Migration Tool (based on Yii v2.0.6)

Create new migration '/Users/Jeff/Sites/hello/migrations/m160316_201654_extend_status_table_for_image.php'? (yes|no) [no]:yes
New migration created successfully.

Esta es la migración personalizada para agregar los dos campos como cadena:

<?php

use yii\db\Schema;
use yii\db\Migration;

class m160316_201654_extend_status_table_for_image extends Migration
{
    public function up()
    {
      $tableOptions = null;
      if ($this->db->driverName === 'mysql') {
          $tableOptions = 'CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE=InnoDB';
      }
      $this->addColumn('{{%status}}','image_src_filename',Schema::TYPE_STRING.' NOT NULL');
      $this->addColumn('{{%status}}','image_web_filename',Schema::TYPE_STRING.' NOT NULL');
    }

    public function down()
    {
        $this->dropColumn('{{%status}}','image_src_filename');
        $this->dropColumn('{{%status}}','image_web_filename');
        return false;
    }

}

A continuación, ejecute la migración:

$ ./yii migrate/up
Yii Migration Tool (based on Yii v2.0.6)

Total 1 new migration to be applied:
    m160316_201654_extend_status_table_for_image

Apply the above migration? (yes|no) [no]:yes
*** applying m160316_201654_extend_status_table_for_image
    > add column image_src_filename string NOT NULL to table {{%status}} ... done (time: 0.044s)
    > add column image_web_filename string NOT NULL to table {{%status}} ... done (time: 0.011s)
*** applied m160316_201654_extend_status_table_for_image (time: 0.071s)


Migrated up successfully.

Dado que Yii2 está construido con una arquitectura Modelo Vista Controlador (MVC), hay tres otras áreas de programación que necesitamos implementar para el cargador de archivos:

El Modelo Status
La vista y el formulario Status
El controlador Status

Mejora de la funcionalidad del Modelo

Ahora, haremos cambios en el archivo /models/Status.php. Primero, necesitamos proporcionar atributos y reglas de validación para los nuevos campos de imagen, así como la variable de $image temporal que el widget utilizará para cargar el archivo.

A continuación, agregamos comentarios para las dos nuevas variables $image_xxx_filename y creamos una variable temporal pública llamada $image:

/**
 * This is the model class for table "status".
 *
 * @property integer $id
 * @property string $message
 * @property integer $permissions
 * @property string $image_src_filename
 * @property string $image_web_filename
 * @property integer $created_at
 * @property integer $updated_at
 * @property integer $created_by 
 * 
 * @property User $createdBy
 */
class Status extends \yii\db\ActiveRecord
{
      const PERMISSIONS_PRIVATE = 10;
      const PERMISSIONS_PUBLIC = 20;  
      public $image;

A continuación, agregaremos validación para nuestra imagen, como el tipo de archivo y el tamaño máximo:

public function rules()
    {
        return [        
            [['message'], 'required'],
            [['message'], 'string'],
            [['permissions', 'created_at', 'updated_at','created_by'], 'integer'],
            [['image'], 'safe'],
            [['image'], 'file', 'extensions'=>'jpg, gif, png'],
            [['image'], 'file', 'maxSize'=>'100000'],
             [['image_src_filename', 'image_web_filename'], 'string', 'max' => 255],        ];
    }

Y nuevas etiquetas de atributos para las vistas:

    public function attributeLabels()
    {
        return [
          'id' => Yii::t('app', 'ID'),
          'message' => Yii::t('app', 'Message'),
          'permissions' => Yii::t('app', 'Permissions'),
          'image_src_filename' => Yii::t('app', 'Filename'),
          'image_web_filename' => Yii::t('app', 'Pathname'),          
          'created_by' => Yii::t('app', 'Created By'),
          'created_at' => Yii::t('app', 'Created At'),
          'updated_at' => Yii::t('app', 'Updated At'),        ];
    }

Ahora podemos pasar a los cambios en View en el formulario ActiveModel.

Agregar nuestra vista y la funcionalidad del formulario

Integración de carga de imágenes en el formulario de publicación de estado

Yii2 Image Uploads - Creating a Status with Our New File Input Capability

Para habilitar la integración del formulario de carga de imágenes en las actualizaciones de estado (mostradas arriba), necesitamos realizar cambios en el archivo /views/status/_form.php.

Primero, incluimos el widget kartik\file\FileInput cerca de la parte superior y actualizamos el formulario para que se convierta en multipart, lo que soporta la publicación de archivos:

<?php

use yii\helpers\Html;
use yii\widgets\ActiveForm;
use app\assets\StatusAsset;
use kartik\file\FileInput;

StatusAsset::register($this);

/* @var $this yii\web\View */
/* @var $model app\models\Status */
/* @var $form yii\widgets\ActiveForm */
?>

<div class="status-form">
  <?php 
      $form = ActiveForm::begin([
          'options'=>['enctype'=>'multipart/form-data']]); // important         
           ?>    

A continuación, entre el campo Permissions (Permisos) y los botones Submit (Enviar), agregamos el widget FileInput:

<?=
        $form->field($model, 'permissions')->dropDownList($model->getPermissions(), 
                 ['prompt'=>Yii::t('app','- Choose Your Permissions -')]) ?>
               </div>
    </div>
    <div class="row">
      <?= $form->field($model, 'image')->widget(FileInput::classname(), [
              'options' => ['accept' => 'image/*'],
               'pluginOptions'=>['allowedFileExtensions'=>['jpg','gif','png'],'showUpload' => false,],
          ]);   ?>
  </div>
    <div class="row">
                 
    <div class="form-group">
 <?= Html::submitButton($model->isNewRecord ? Yii::t('app', 'Create') : Yii::t('app', 'Update'), ['class' => $model->isNewRecord ? 'btn btn-success' : 'btn btn-primary']) ?>
     </div>
   </div>

En la línea de pluginOptions, restringimos los tipos de archivo a formatos de imagen comunes como jpg.

Cuando esté completo, se verá algo así, esperando que el usuario agregue una imagen:

Yii2 Image Uploads - Create Status Page with File Upload Added

Visualización de la imagen

También voy a agregar código para mostrar la imagen cargada para más tarde (después de que terminemos el soporte del controlador).

Primero, lo agregaré a la página de vista de estado (/views/status/view.php), que es muy básica. Sin embargo, exhibiré la imagen debajo de los detalles del artículo:

<?= DetailView::widget([
        'model' => $model,
        'attributes' => [
            'id',
            'createdBy.email',
            'message:ntext',
            'permissions',
            'image_web_filename',
            'image_src_filename',
            'created_at',
            'updated_at',
        ],
    ]) ?>
    
    <?php
       if ($model->image_web_filename!='') {
         echo '<br /><p><img src="'.Yii::$app->homeUrl. '/uploads/status/'.$model->image_web_filename.'"></p>';
       }    
    ?>

Se verá algo como esto:

Yii2 Image Uploads - Enhanced Status View with Image Below

También agregamos una pequeña vista en miniatura a nuestra página de índice de estado (/views/status/index.php). He añadido un atributo de columna personalizado al widget GridView de Yii2:

<?= GridView::widget([
           'dataProvider' => $dataProvider,
           'filterModel' => $searchModel,
           'columns' => [
               ['class' => 'yii\grid\SerialColumn'],
               'id',
               'message:ntext',
               'permissions',
               'created_at',
               [
                     'attribute' => 'Image',
                     'format' => 'raw',
                     'value' => function ($model) {   
                        if ($model->image_web_filename!='')
                          return '<img src="'.Yii::$app->homeUrl. '/uploads/status/'.$model->image_web_filename.'" width="50px" height="auto">'; else return 'no image';
                     },
                   ],
           	      ['class' => 'yii\grid\ActionColumn',
   				      'template'=>'{view} {update} {delete}',
   					    'buttons'=>[
                   'view' => function ($url, $model) {     
                     return Html::a('<span class="glyphicon glyphicon-eye-open"></span>', 'status/'.$model->slug, ['title' => Yii::t('yii', 'View'),]);	
   						      }
   							],
   			      ],
           ],
       ]); ?>

En última instancia, se verá así:

Yii2 Image Uploads - Enhanced Status Index with Uploaded Image Thumbnails

Creando el soporte del controlador

Para que todo lo anterior sea posible, necesitamos terminar la integración del controlador.

En la parte superior de /controllers/StatusController.php, tenemos que incluir yii\web\UploadedFile:

<?php
namespace app\controllers;
use Yii;
use app\models\Status;
use app\models\StatusSearch;
use app\models\User;
use app\components\AccessRule;
use yii\web\Controller;
use yii\web\NotFoundHttpException;
use yii\filters\VerbFilter;
use yii\filters\AccessControl;
use yii\web\UploadedFile;

Entonces tenemos que actualizar la función actionCreate:

public function actionCreate()
    {
        $model = new Status();

        if ($model->load(Yii::$app->request->post())) {
          $image = UploadedFile::getInstance($model, 'image');
           if (!is_null($image)) {
             $model->image_src_filename = $image->name;
             $ext = end((explode(".", $image->name)));
              // generate a unique file name to prevent duplicate filenames
              $model->image_web_filename = Yii::$app->security->generateRandomString().".{$ext}";
              // the path to save file, you can set an uploadPath
              // in Yii::$app->params (as used in example below)                       
              Yii::$app->params['uploadPath'] = Yii::$app->basePath . '/web/uploads/status/';
              $path = Yii::$app->params['uploadPath'] . $model->image_web_filename;
               $image->saveAs($path);
            }
            if ($model->save()) {             
                return $this->redirect(['view', 'id' => $model->id]);             
            }  else {
                var_dump ($model->getErrors()); die();
             }
              }
              return $this->render('create', [
                  'model' => $model,
              ]);     
    }

Esencialmente, esto realiza las siguientes operaciones:

Capturamos el nombre de archivo original de la información del formulario de archivo cargado (image_src_filename).
Generamos un nombre de archivo único para nuestro servidor (image_web_filename).
Guardamos el archivo en su directorio de carga (/web/uploads/status/).
Guardamos el modelo.
Redireccionamos a la página de vista mejorada.

Usted puede ver los resultados finales con la imagen de arriba, que incluye una foto del Taj Mahal.

El File Input Widget de Kartik también ofrece configuraciones más avanzadas que documenta bastante bien, como Arrastrar y Soltar:

Yii2 Image Uploads - Enhanced File Input Widget Options with Drag and Drop

Mire más de estos y compruébelos en las siguientes páginas:

¿Que sigue?

Espero que esto le ayude con los fundamentos de la carga de archivos en su aplicación Yii2. Si desea ver otro paso a través similar de este tipo de funcionalidad, consulte Creando su startup con PHP: configuración de usuario, imágenes de perfil y detalles de contacto. Ese tutorial ofrece una integración ligeramente diferente de este tutorial, usando pestañas, actualizando perfiles de usuario y escalando las imágenes.

Vea los próximos tutoriales en mi Serie: Cómo programar con Yii2 mientras continúo sumando diferentes aspectos del framework. También puede comprobar mi serie Creando su Startup con PHP, que está utilizando la plantilla avanzada de Yii2 como construir una aplicación del mundo real.

Si quieres saber cuándo llega el próximo tutorial de Yii2, sígueme @reifman en Twitter o consulta mi página de instructor. Mi página de instructor incluirá todos los artículos de esta serie tan pronto como se publiquen.

Enlaces relacionados

Aquí hay una variedad de enlaces que he utilizado para investigar y escribir este tutorial: