Lo esencial de crear paquetes de Laravel

El marco Laravel PHP ofrece su sistema de paquetes para permitir a los desarrolladores redistribuir paquetes de código útiles u organizar aplicaciones en varios "paquetes" de aplicaciones más pequeñas..

En este tutorial, aprenderemos los entresijos de crear y distribuir paquetes desde cero..

Un paquete de Laravel tiene acceso a todas las características que el marco ofrece a su aplicación host, incluyendo enrutamiento, migraciones, pruebas, vistas y muchas otras características útiles.

Aquí hay un pequeño secreto, entre nosotros: el solicitud La carpeta del paquete fuente de Laravel también es un paquete, al que Laravel se refiere como el DEFAULT_BUNDLE.


Cuándo crear un paquete?

Antes de escribir un nuevo código, me gustaría hacerme algunas preguntas simples para determinar si es apropiado para un paquete. Déjame compartir esta técnica contigo.

¿Podría este código ser útil para otros??

Si la respuesta a esta pregunta es sí, primero me aseguraré de que alguien no haya creado un paquete o paquete similar. Aparte de con fines de aprendizaje, no tiene sentido recrear la rueda. Si el otro paquete es de un estándar lo suficientemente alto como para ser usado en su proyecto, entonces use ese lugar y ahórrese tiempo.

En segundo lugar, pienso en el código y decido si puede ser útil o no para los usuarios de otros marcos, o para las personas que no utilizan un marco en absoluto. Si el código no está relacionado con el marco de trabajo de Laravel y no necesita hacer uso de las clases centrales de Laravel, entonces crearía un paquete Composer. Los paquetes de Composer se están convirtiendo en el estándar para compartir código que no está restringido a un solo marco o proyecto.

Para obtener más información sobre Composer, consulte los siguientes enlaces:

  • Documentacion oficial
  • Fácil gestión de paquetes con Composer

Si el código podría ser útil para otros y depende del marco de trabajo de Laravel, entonces tiene una buena razón para crear un nuevo paquete..

¿Tendré que volver a escribir este código??

DRY es el nombre del juego..

Si el código proporciona la funcionalidad que escribe con frecuencia, entonces tiene sentido crear un paquete. DRY (¡No te repitas!) Es el nombre del juego..

¿Podría este código ser considerado una aplicación independiente??

Por ejemplo, puede estar creando un sitio simple que, entre otras características, tenga un componente de blog. El blog podría considerarse una aplicación separada que se incluirá en un paquete para una organización mucho mayor de su proyecto..

Otro ejemplo sería una sección administrativa o 'back-end' para su sitio web. Esta sección podría considerarse fácilmente como un componente separado de la aplicación principal y, en cambio, podría organizarse en uno o más paquetes..

¿Encajaría este código en una sola clase??

Si este es el caso, podría considerar escribir una 'Biblioteca' en su lugar. Una biblioteca es una clase única que contiene código reutilizable. Se puede agregar fácilmente a un proyecto Laravel colocando la clase en el aplicación / bibliotecas / directorio, que se carga automáticamente por defecto.


Creación de un paquete

Creemos un complemento simple que interactúe con el servicio Gravatar para ofrecer un método simple para generar avatares de varios tamaños dentro de nuestra aplicación principal. También agregaremos la funcionalidad necesaria para ingresar una dirección de correo electrónico y el tamaño del avatar, y veremos el gravatar asociado en la página..

Empecemos creando un nuevo directorio dentro del /manojos Directorio de nuestro proyecto. Llamaremos al directorio y nuestro paquete. gravitación. No salsa.

Vamos a añadir gravvy a la matriz de paquetes dentro aplicación / bundles.php para que podamos probarlo a medida que avanzamos. Añadiremos un 'auto' => verdadero Opción a la matriz para que el paquete se inicie automáticamente, y cualquier asignación de autocargador que creamos estará disponible para todo Laravel.

return array ('docs' => array ('handle' => 'docs'), 'gravvy' => array ('auto' => true));

Primero, necesitaremos crear una pequeña biblioteca que recupere el avatar de un usuario, usando una dirección de correo electrónico. Cree un nuevo archivo dentro de la raíz del paquete, llamado gravvy.php. Vamos a crear una clase, llamada Gravvy con un método estático, hacer(), para replicar el esquema de nombres usado por las propias bibliotecas de Laravel.

los hacer() El método aceptará dos parámetros: una dirección de correo electrónico y un entero para representar el tamaño del avatar para recuperar.

 * / class Gravvy / ** * Crea un nuevo elemento de imagen desde una dirección de correo electrónico. * @param string $ email La dirección de correo electrónico. * @param integer $ size El tamaño del avatar. * @return string La fuente de un elemento de imagen. * / public static function make ($ email, $ size = 32) // convertir nuestro correo electrónico en un hash md5 $ email = md5 ($ email); // devuelve el elemento de imagen retorno '');  / ** * Probar que una salida de avatares aparezca como se esperaba cuando * se especifica un tamaño de avatar personalizado. * * @return void * / public function testAvatarImageIsGeneratedWithSize () // start the gravvy bundle Bundle :: start ('gravvy'); // comprueba que la salida coincida con el $ this-> assertEquals esperado (Gravvy :: make ('[email protected] ', 64),''); 

Anteriormente, hemos escrito dos pruebas de PHPUnit: una para probar el resultado de generar un avatar mediante un correo electrónico, y otra que también especifica un tamaño de avatar en píxeles. Notarás que llamamos Bundle :: start ('gravvy') para iniciar manualmente el paquete. Esto se debe a que Laravel no carga automáticamente los paquetes a través de la interfaz de línea de comandos en la actualidad.

Como miembro del equipo central, me gustaría señalar que tenemos la intención de resolver esto en una versión futura!

Usemos Artisan para ejecutar nuestras pruebas PHPUnit escribiendo la prueba comando y usando el nombre del paquete, gravitación, como parámetro.

php prueba artesanal de gravvy

¡Genial! Nuestras pruebas se ejecutaron con éxito en el primer intento, y nuestro ego ha crecido, solo un poco!

¡Ahora que nuestra clase Gravvy ha sido probada, la gente puede usarla en sus propias aplicaciones! Vamos a llevar el paquete un paso más allá y crear un par de páginas simples para generar y previsualizar gravatars. Podemos usar este ejemplo para aprender cómo el sistema de enrutamiento maneja los paquetes..

Para comenzar, vamos a crear un nuevo controlador de 'vista previa' para nuestro paquete. Necesitaremos crear un controladores directorio dentro del paquete y, dentro de él, agregaremos un nuevo archivo: preview.php.

 

El nombre del controlador debe tener un prefijo con el nombre del paquete, y debe agregarse con _Controlador - como con los controladores normales.

Podríamos crear algunas rutas para asignar nuestras acciones de controlador a URI sensibles, pero ¿no sería mejor si pudiéramos permitir que el usuario de nuestro paquete decida qué URI base usar? ¿Sería? Hagamos eso entonces!

Añadiendo un 'handle' => 'gravvy' par clave-valor a la matriz de configuración de paquetes, podemos permitir al usuario cambiarlo sin alterar el código del paquete en sí. Aquí está la configuración resultante en aplicación / bundles.php.

return array ('docs' => array ('handle' => 'docs'), 'gravvy' => array ('auto' => true, 'handle' => 'gravvy'));

Ahora podemos usar el (:haz) lugar en nuestras rutas, que será reemplazado por el valor del manijas opción. Vamos a crear un rutas.php Archivo dentro de la raíz de nuestros paquetes y agregar algunas rutas.

Route :: get ('(: bundle) / form', 'gravvy :: preview @ form'); Route :: post ('(: bundle) / preview', 'gravvy :: preview @ preview');

Tenemos la ruta OBTENER gravvy / forma que se asigna a la formar acción de la Avance controlador, y Gravado POST / vista previa que se asigna a la avance acción de la Avance controlador.

Vamos a crear las vistas asociadas para nuestras acciones de controlador; Puedes hacerlos tan complejos y bonitos como quieras, pero los voy a mantener simples. Primero, crea un puntos de vista carpeta dentro del paquete, al igual que con el directorio de aplicaciones.

 

Ahora que tenemos un formulario que enviará un correo electrónico y un campo de tamaño a la vista previa @ vista previa controlador / par de acción, vamos a crear una página de vista previa para el avatar generado; Usaremos un atributo, llamado $ elemento, para mantener su fuente.

 

$ elemento

HTML :: link \ _to \ _action ('gravvy :: preview @ form', '< Go Back!')

Ahora debemos alterar el avance Acción para hacer uso de los datos enviados desde el formulario..

/ ** * Muestra el avatar resultante. * / public function action_preview () // obtener datos de nuestro formulario $ email = Input :: get ('email'); $ size = Input :: get ('size'); // generar el avatar $ avatar = Gravvy :: make ($ email, $ size); // carga la vista previa de la vista return View :: make ('gravvy :: preview') -> with ('element', $ avatar); 

Recuperamos los datos de POST y los usamos para crear nuestro avatar. También debemos agregar un con() método para el Ver :: hacer () Cadena para permitir el uso del elemento dentro de la vista..

¡Finalmente podemos probar nuestro sistema de previsualización de avatares! Echa un vistazo a la / gravvy / form URI y darle una oportunidad! Todo funciona como se espera.

Puede que esta no sea la mejor manera de organizar su paquete, pero sí resalta algunas de las cosas útiles que son posibles. Diviértase creando sus propios paquetes y asegúrese de considerar publicarlos en el sitio web de los paquetes..


Publicando un paquete

Una vez que su paquete esté en un estado funcional, es posible que desee considerar su inclusión en el Directorio de Laravel Bundles. Repasemos el proceso de envío de un nuevo paquete..

Primero, deberá tener una cuenta de GitHub y tener su paquete versionado dentro de un repositorio público. GitHub ofrece cuentas gratuitas con un número ilimitado de repositorios públicos; Encontrarás su formulario de registro aquí..

Si eres nuevo en el control de versiones con Git, te sugiero leer la gran serie de artículos de Git aquí en Nettuts.+.

Una vez que tenga su cuenta y código en orden, asegúrese de que la última versión de su paquete se puede encontrar dentro de la rama 'maestra', y que la raíz de su paquete (donde start.php sería) es la raíz del repositorio, en lugar de un subdirectorio.

Luego, visite el sitio web del Directorio de Laravel Bundles e inicie sesión con sus credenciales de GitHub.

Ahora haga clic en el botón 'Enviar un paquete', seleccione su repositorio de paquetes del menú desplegable y presione el botón 'Continuar'.

El formulario de registro es bastante sencillo, pero aquí hay algunos "errores" que no puede detectar..

Nombre

Nombre es una palabra clave en minúsculas que se usa para instalar la aplicación. Debe ser una palabra corta pero precisa para describir su paquete..

Resumen / Descripción

Estos campos pueden contener contenido de formato markdown. Así que siéntase libre de copiar el contenido de su GitHub README.md expediente.

Dependencias / Tags

Use el botón de coma en su teclado para separar etiquetas y dependencias. El campo de dependencias debe contener la palabra clave de instalación corta para el paquete que existe como una dependencia para el paquete que está enviando.

Activo

los Activo el campo simplemente determina si el paquete se mostrará o no a otros usuarios. Aún puede instalar paquetes inactivos por su palabra clave de instalación para fines de prueba. Establezca este campo en 'Sí' solo cuando esté de acuerdo con que otras personas utilicen su paquete.

Una vez que haga clic en el botón 'Guardar', su paquete se habrá enviado y, si está marcado como 'Activo', aparecerá en las listas de paquetes. Siempre puede editar su lista de paquetes en una fecha posterior.


Encontrar paquetes

Los paquetes que se han compartido con la comunidad Laravel se enumeran en el directorio de paquetes en http://bundles.laravel.com.

Puede buscar paquetes por categoría o usar la función de búsqueda para encontrar el paquete que está buscando. Una vez que haya encontrado un paquete que cumpla con sus requisitos, consulte la pestaña 'Instalación' del perfil del paquete para encontrar la palabra clave de instalación.


Instalación de un paquete

Una vez que tenga la palabra clave de instalación para un paquete, puede instalarla desde la base de su proyecto usando la interfaz de línea de comandos 'Artisan', y es paquete: instalar mando. Por ejemplo…

php artisan bundle: install bob

Artisan consultará la API de los paquetes para recuperar la ruta al repositorio de GitHub de los paquetes y los repositorios de todas sus dependencias. A continuación, descargará los paquetes de origen directamente desde GitHub y los extraerá al /manojos directorio para usted.

Deberá agregar manualmente el nombre del paquete a la matriz dentro de aplicación / bundles.php para que el paquete se habilite.

return array ('docs' => array ('handle' => 'docs'), 'bob');

En algunas situaciones, es posible que necesite agregar información adicional a este formación entrada para facilitar el inicio automático, o dirigir ciertas rutas al paquete. El autor habrá proporcionado esta información adicional en la descripción de los paquetes, si ese es el caso.


¡Gracias por leer y disfrutar creando tus propios paquetes con Laravel! Si desea obtener más información sobre Laravel, asegúrese de recoger mi libro.!