Guía de contribución – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Reportes de errores

Para fomentar la colaboración activa, Laravel alenta fuertemente el uso de pull requests, no solo reportes de errores. «Los reportes de errores» pueden además ser enviados en el formulario de un pull request que contenga un test fallido.

Sin embargo, si tu archivo reportar un error, tu issue debería contener un título y una clara descripción del problema. Deberías además incluir tanta información relevante como sea posible y un ejemplo de código que demuestre el problema. La meta de un reporte de error es hacerlo fácil para ti mismo – y para otros – para replicar el error y desarrollar una solución.

Recuerda, los reportes de errores son creados con la esperanza de que otros con el mismo problema puedan colaborar contigo en la solución. No esperes que automáticamente el reporte del error recibirá alguna actividad o que los otros saltarán a repararlo. Crear un reporte de error sirve para ayudarte a ti mismo y a otros a iniciar el camino de reparar el problema.

El código fuente de Laravel es manejado en GitHub, y allí están los repositorios para cada uno de los proyectos de Laravel:

importante sobre la traducción
Los reportes sobre errores o detalles encontrados en esta traducción deben ser realizados en el repositorio oficial de la traducción.

Discusión sobre el desarrollo del núcleo

Tu puedes proponer nuevas funcionalidades o mejoras del comportamiento existente de Laravel en el tablero de ideas de ideas de Laravel. Si propones una nueva funcionalidad, esté dispuesto a implementar al menos parte del código que se necesitaría para completar la funcionalidad.

Discusiones informales sobre errores, nuevas funcionalidades e implementación de existentes funcionalidades toman lugar en el canal #internals del Servidor Discord de Laravel. Taylor Otwell, el encargado de Laravel, está normalmente presente en el canal los días de semana de 8:00am-5:00pm (UTC-06:00 o América/Chicago) y esporádicamente está presente en el canal a otras horas.

¿Cuál rama?

Todas las correcciones de errores deben ser enviadas a la última rama estable o a la actual rama LTS. Las correcciones de errores nunca deben ser enviadas a la rama master a menos que ellos reparen funcionalidades que existan solo en los próximos lanzamientos.

Funcionalidades menores que son totalmente compatible con la versión actual de Laravel pueden enviarse a la última rama estable.

Las nuevas funcionalidades mayores deben siempre ser enviadas a la rama master, la cual contiene el próximo lanzamiento de Laravel.

Si no estás seguro si tu funcionalidad califica como mayor o menor, por favor pregúntale a Taylor Otwell en el canal #internals del servidor Discord de Laravel.

Recursos compilados

Si estás enviando un cambio que afectará un archivo compilado, tal como muchos de los archivos en resources/sass o resources/js del repositorio laravel/laravel, no hagas commit de los archivos compilados. Debido a su gran tamaño, ellos no pueden realistamente ser revisado por el encargado. Esto podría ser usado como una forma de inyectar código malicioso dentro de Laravel. Para evitar esto de manera defensiva, todos los archivos compilados serán generados y confirmados por los mantenedores de Laravel.

Vulnerabilidades de seguridad

Si tu descubres una vulnerabilidad de seguridad dentro de Laravel, por favor envía un email a Taylor Otwell a [email protected]. Todas las vulnerabilidades de seguridad serán tratadas con prontitud.

Estilo de código

Laravel sigue el estándar de código PSR-2 y el estándar de auto carga PSR-4.

Ver post

Guía de Actualización – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Cambios de alto impacto

Cambios de mediano impacto

Actualizando a 6.0 desde 5.8

Tiempo de actualización estimado: una hora

Intentamos documentar cada posible cambio de ruptura (breaking change). Dado que algunos de estos cambios de ruptura se encuentran en las partes oscuras del framework, solo una parte de estos cambios puede afectar tu aplicación.

Ver post

Notas de Lanzamiento – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Esquema de versiones

Laravel y sus otros paquetes de primeros (paquetes desarrollados por una propia compañía) siguen el versionamiento semántico. Los principales lanzamientos del framework son realizados cada seis meses (Febrero y Agosto), mientras que los menores y los parches pueden ser realizados tan frecuente como cada semana. Los lanzamientos de versiones menores y los parches nunca deberían contener cambios que causen que otros componentes fallen (breaking changes).

Cuando haces referencia al framework Laravel o sus componentes desde tu aplicación o paquete, debes utilizar siempre una restricción de versión como ^6.0, ya que las versiones mayores de Laravel incluyen "breaking changes". Sin embargo, nos esforzamos por asegurarnos siempre de que puedas actualizar a una nueva versión mayor en un día o menos.

Política de soporte

Para las versiones LTS, como Laravel 6, se proporcionan correcciones de errores durante 2 años y correcciones de seguridad por 3 años. Estas versiones proporcionan la ventana más larga de soporte y mantenimiento. Para las versiones generales, las correcciones de errores se proporcionan durante 6 meses y las correcciones de seguridad durante 1 año. Para todas las librerías adicionales, incluyendo Lumen, solo la última versión recibe correcciones de error. Adicionalmente, por favor revisa las versiones de bases de datos soportadas por Laravel.

Versión Lanzamiento Corrección de errores hasta Correcciones de seguridad hasta
5.5 (LTS) 30 de Agosto, 2017 30 de Agosto, 2019 30 de Agosto, 2020
5.6 7 de Febrero, 2018 7 de Agosto, 2018 7 de Febrero, 2019
5.7 4 de Septiembre, 2018 4 de Marzo, 2019 4 de Septiembre, 2019
5.8 26 de Febrero, 2019 26 de Agosto, 2019 26 de Febrero, 2020
6 (LTS) 3 de Septiembre, 2019 3 de Septiembre, 2021 3 de Septiembre, 2022

Laravel 6

Laravel 6 (LTS) continúa las mejoras hechas en Laravel 5.8 con la introducción del versionamiento semántico, la compatibilidad con Laravel Vapor, las respuestas de autorización mejoradas, el middleware job o de trabajos, las colecciones lazy o diferidas, las mejoras de subquery o subconsulta, la extracción de la estructura de frontend al paquete de Composer laravel/ui, y una variedad de correcciones de error y mejoras de usabilidad.

Ver post

Laravel Telescope – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Telescope de Laravel es un elegante asistente para depurar código para el framework de Laravel. Telescope proporciona información detallada de las solicitudes entrantes de tu aplicación, excepciones, entradas de log, consultas de bases de datos, trabajos en cola, correos, notificaciones, operaciones de caché, tareas programadas, valores de variables y mucho más. Telescope acompaña maravillosamente tu entorno de desarrollo de Laravel.

Instalación

Puedes usar Composer para instalar Telescope dentro de tu proyecto de Laravel:

composer require laravel/telescope

Después de instalar Telescope, publica sus recursos usando el comando Artisan telescope:install. Después de instalar Telescope, también deberías ejecutar el comando migrate:

php artisan telescope:install

php artisan migrate

Actualizando Telescope

Si haces una actualización de Telescope, deberías volver a publicar los recursos de Telescope:

php artisan telescope:publish

Ver post

Laravel Socialite – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Además de la típica autenticación basada en formularios, Laravel también proporciona una sencilla y conveniente forma de autenticar con proveedores OAuth usando Laravel Socialite. Actualmente Socialite soporta autenticación con Facebook, Twitter, LinkedIn, Google, Github, GitLab y Bitbucket.

Los adaptadores para otras plataformas son listados en el sitio web de Proveedores de Socialite manejado por la comunidad.

Actualizando Socialite

Al actualizar a una nueva versión mayor de Socialite, es importante que revises cuidadosamente la guía de actualización.

Instalación

Para empezar con Socialite, usa Composer para agregar el paquete a las dependencias de tu proyecto:

composer require laravel/socialite

Configuración

Antes de usar Socialite, también necesitarás agregar las credenciales para los servicios OAuth que tu aplicación utiliza. Estas credenciales deberían estar colocadas en tu archivo de configuración config/services.php, y debería usar la clave facebook, twitter, linkedin, google, github, gitlab o bitbucket dependiendo del proveedor que tu aplicación requiera. Por ejemplo:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => 'http://your-callback-url',
],

Si la opción redirect contiene una ruta relativa, será resuelta automáticamente a una URL completamente calificada.

Enrutamiento

A continuación, ¡estás listo para autenticar usuarios! Necesitarás dos rutas: una para redireccionar el usuario al proveedor OAuth y otra para recibir la función de retorno del proveedor después de la autenticación. Accederemos a Socialite usando la clase facade Socialite:

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use Socialite;

class LoginController extends Controller
{
    /**
    * Redirect the user to the GitHub authentication page.
    *
    * @return \Illuminate\Http\Response
    */
    public function redirectToProvider()
    {
        return Socialite::driver('github')->redirect();
    }

    /**
    * Obtain the user information from GitHub.
    *
    * @return \Illuminate\Http\Response
    */
    public function handleProviderCallback()
    {
        $user = Socialite::driver('github')->user();

        // $user->token;
    }
}

El método redirect se toma la tarea de enviar el usuario al proveedor OAuth, mientras que el método user leerá la solicitud entrante y obtendrá la información del usuario desde el proveedor.

Necesitarás definir las rutas para tus métodos de controlador:

Route::get('login/github', 'Auth\LoginController@redirectToProvider');
Route::get('login/github/callback', 'Auth\LoginController@handleProviderCallback');

Parámetros opcionales

Un número de proveedores OAuth soportan parámetros opcionales en la solicitud de redirección. Para incluir algunos de los parámetros opcionales en la solicitud, llama el método with con un arreglo asociativo:

return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

Al momento de usar el método with, procura no pasar algunas palabras reservadas tales como state or response_type.

Alcances de acceso

Antes de redirecionar al usuario, también puedes agregar «alcances (scopes)» adicionales en la solicitud usando el método scopes. Este método mezclará todos los alcances existentes con los que suministras:

return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();

Puedes sobrescribir todos los alcances existentes usando el método setScopes:

return Socialite::driver('github')
    ->setScopes(['read:user', 'public_repo'])
    ->redirect();

Autenticación sin estado

El método stateless puede ser usado para deshabilitar la verificación de estado de sesión. Esto es útil al momento de agregar la autenticación de una red social a una API.

return Socialite::driver('google')->stateless()->user();

La autenticación sin estado no está disponible para el controlador de Twitter, que usa OAuth 1.0 para la autenticación.

Obteniendo detalles de usuario

Una vez que tengas una instancia de usuario, puedes obtener algunos detalles más sobre el usuario:

$user = Socialite::driver('github')->user();

// OAuth Two Providers
$token = $user->token;
$refreshToken = $user->refreshToken; // not always provided
$expiresIn = $user->expiresIn;

// OAuth One Providers
$token = $user->token;
$tokenSecret = $user->tokenSecret;

// All Providers
$user->getId();
$user->getNickname();
$user->getName();
$user->getEmail();
$user->getAvatar();

Obteniendo los detalles de usuario desde un token (OAuth2)

Si ya tienes un token de acceso válido de un usuario, puedes obtener sus detalles usando el método userFromToken:

$user = Socialite::driver('github')->userFromToken($token);

Obteniendo los detalles de usuario desde un token y secreto (OAuth1)

Si ya tienes un par válido de token / secreto de un usuario, puedes obtener sus detalles usando el método userFromTokenAndSecret:

$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);

Scout para Laravel – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Laravel Scout proporciona una sencilla solución, basada en un controlador (driver) para agregar búsquedas de texto completo a tus modelos Eloquent. Usando observadores de modelo, Scout mantendrá automáticamente tus índices de búsqueda sincronizados con tus registros de Eloquent.

Actualmente, Scout viene con el controlador (driver) Algolia; sin embargo, la escritura de controladores personalizados es simple y eres libre de extender Scout con tus propias implementaciones de búsqueda.

Instalación

Primero, instala Scout por medio del manejador de paquetes Composer:

composer require laravel/scout

Después de instalar Scout, debes publicar la configuración de Scout usando el comando Artisan vendor:publish. Este comando publicará el archivo de configuración scout.php en tu directorio config:

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Finalmente, agrega el trait Laravel\Scout\Searchable al modelo en el que te gustaría hacer búsquedas. Este trait registrará un observador de modelo para mantener el modelo sincronizado con tu controlador de búsqueda:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;
}

Ver post

Laravel Passport – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Laravel ya facilita la autenticación por medio de formularios de inicio de sesión tradicionales, pero ¿Qué pasa con las APIs? Las APIs típicamente usan tokens para autenticar a los usuarios y no mantienen el estado de sesión entre solicitudes. Laravel hace de la autenticación de API algo muy simple usando Passport de Laravel, el cual proporciona una implementación de servidor OAuth2 completa para tu aplicación Laravel en sólo minutos. Passport está construido sobre el servidor League OAuth2 que es mantenido por Andy Millington y Simon Hamp.

Esta documentación asume que estás familiarizado con OAuth2. Si no sabes nada sobre OAuth2, considera familiarizarte con la terminología general y las características de Outh2 antes de continuar.

Actualizando Passport

Al actualizar a una nueva versión mayor de Passport, es importante que revises detalladamente la guía de actualización.

Instalación

Para empezar, instala Passport por medio del gestor de paquetes Composer:

composer require laravel/passport

El proveedor de servicio de Passport registra su propio directorio de migración de base de datos con el framework, así que deberías migrar tu base de datos después de instalar el paquete. Las migraciones de Passport crearán las tablas que tu aplicación necesita para almacenar clientes y tokens de acceso:

php artisan migrate

A continuación, debes ejecutar el comando passport:install. Este comando creará las claves de encriptación necesarias para generar tokens de acceso seguro. Además, el comando creará clientes de «acceso personal» y «permiso de contraseña» los cuales serán usados para generar tokens de acceso:

php artisan passport:install

Después de ejecutar este comando, agrega el trait Laravel\Passport\HasApiTokens a tu modelo App\User. Este trait proporcionará algunos métodos helper para tu modelo los cuales permitirán que inspecciones el token y alcances del usuario autenticado:

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
}

Luego, deberías llamar al método Passport::routes dentro del método boot de tu AuthServiceProvider. Este método registrará las rutas necesarias para suministrar tokens y revocar tokens de acceso, clientes y tokens de acceso personal:

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Gate;
use Laravel\Passport\Passport;

class AuthServiceProvider extends ServiceProvider
{
    /**
    * The policy mappings for the application.
    *
    * @var array
    */
    protected $policies = [
        'App\Model' => 'App\Policies\ModelPolicy',
    ];

    /**
    * Register any authentication / authorization services.
    *
    * @return void
    */
    public function boot()
    {
        $this->registerPolicies();

        Passport::routes();
    }
}

Finalmente, en tu archivo de configuración config/auth.php, debes establecer la opción driver del guard de autenticación de api a passport. Esto indicará a tu aplicación que utilice el TokenGuard de Passport al momento de autenticar las solicitudes de API entrantes:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

Ver post

Laravel Horizon – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Horizon proporciona un bonito panel de control y sistema de configuración controlado por código para Laravel, potenciado por colas de Redis. Horizon te permite monitorear fácilmente métricas claves de tu sistema de colas tales como tasa de rendimiento, tiempo de ejecución y fallas de tareas.

Toda la configuración de tu worker es almacenada en un solo archivo de configuración sencillo, permitiendo que tu configuración quede en el código fuente donde tu equipo completo pueda colaborar.

Instalación

Debes asegurarte de que tu conexión de cola está establecido a redis en tu archivo de configuración queue.

Puedes usar Composer para instalar Horizon en tu proyecto de Laravel:

composer require laravel/horizon ~3.0

Después de instalar Horizon, publica sus assets usando el comando Artisan horizon:install:

php artisan horizon:install

Ver post

Laravel Envoy – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Laravel Envoy proporciona una sintaxis limpia y mínima para definir las tareas comunes que ejecutas en tus servidores remotos. Utilizando el estilo de sintaxis de Blade, puedes configurar fácilmente tareas para deploy, comandos de Artisan y más. Envoy solamente es compatible con sistemas operativos Mac y Linux.

Instalación

Primero, instala Envoy utilizando el comando de Composer global require:

composer global require laravel/envoy

Dado que las librerías globales de Composer ocasionalmente pueden causar conflictos en la versión del paquete, puedes considerar utilizar cgr, el cual es un reemplazo directo para el comando composer global require. Las instrucciones de instalación de la librería cgr pueden ser encontradas en GitHub.

Asegúrate de colocar el directorio ~/.composer/vendor/bin en tu PATH para que el ejecutable envoy pueda ser localizado cuando se ejecute el comando envoy en tu terminal.

Actualizar envoy

También puedes usar Composer para mantener tu instalación de Envoy actualizada. Ejecutar el comando composer global update actualizará todos tus paquetes de Composer instalados globalmente:

composer global update

Escribir tareas

Todas tus tareas de Envoy deberán definirse en un archivo Envoy.blade.php en la raíz de tu proyecto. Aquí un ejemplo para comenzar:

@servers(['web' => ['[email protected]']])

@task('foo', ['on' => 'web'])
    ls -la
@endtask

Como puedes ver, un arreglo @servers es definido al inicio del archivo, permitiéndote hacer referencia a estos servidores en la opción on en la declaración de tus tareas. Dentro de tus declaraciones @task, deberás colocar el código Bash que se deberá ejecutar en tu servidor una vez que la tarea sea ejecutada.

Puedes forzar que un script se ejecute localmente especificando la dirección IP del servidor como 127.0.0.1:

@servers(['localhost' => '127.0.0.1'])

Ver post

Laravel Cashier – Documentación de Laravel 6

Duilio Palacios 29/05/2020
Documentación, Laravel 0 comentarios

Introducción

Laravel Cashier proporciona una expresiva interfaz fluida para los servicios de pagos en línea por suscripción de Stripe. Maneja casi todo el código de facturación de suscripción que estás teniendo pavor de escribir. Además de la gestión de suscripción, Cashier puede manejar cupones, cambio de suscripciones, «cantidades» de suscripción, cancelación de períodos de gracia e incluso generar PDFs de facturas.

Actualizando Cashier

Al actualizar a una versión nueva de Cashier, es importante que revises cuidadosamente la guía de actualización.

Para prevenir errores por cambios de actualización, Cashier usa una versión API de Stripe fija. Cashier 10.1 utiliza la versión 2019-08-14 de la API para Stripe. La versión API para Stripe será actualizada con los cambios menores en los lanzamientos de software (releases) con el propósito de asegurar la incorporación de las mejoras y nuevas funcionalidades de Stripe.

Instalación

Primero, instala el paquete de Cashier para Stripe Con Composer:

composer require laravel/cashier

Para asegurar que Cashier maneje todos los eventos de Stripe apropiadamente, recuerda configurar el manejo de webhook de Cashier.

Migraciones de bases de datos

El proveedor de servicio de Cashier registra su propio directorio de migración de base de datos, así que recuerda migrar tu base de datos después de instalar el paquete. Las migraciones de Cashier añadirán varias columnas a tu tabla users al igual que crearán una nueva tabla subscriptions para manejar todas las suscripciones de tus clientes:

php artisan migrate

Si necesitas sobrescribir las migraciones que vienen con el paquete de Cashier, puedes publicarlas usando el comando Artisan vendor:publish:

php artisan vendor:publish --tag="cashier-migrations"

Si prefieres prevenir que las migraciones de Cashier se ejecuten completamente, puedes usar el método ignoreMigrations proporcionado por Cashier. Típicamente, este método debería ser ejecutado en el método register de tu AppServiceProvider:

use Laravel\Cashier\Cashier;

Cashier::ignoreMigrations();

Stripe recomienda que cualquier columna usada para almacenar los identificadores de Stripe debería ser sensible a mayúsculas. Como consecuencia, deberías asegurarte que el ordenamiento de columna para la columna stripe_id sea puesto a, por ejemplo, utf8_bin en MySQL. Puedes buscar más información en la documentación de Stripe.

Configuración

Ver post

Suscríbete a nuestro boletín

Te enviaremos publicaciones con consejos útiles y múltiples recursos para que sigas aprendiendo.

Suscríbete a nuestro boletín

Recibe consejos útiles, promos y múltiples recursos directamente en tu correo.

Tu nombre y correo serán enviados directamente a MailChimp. No compartiremos tus datos con otras empresas.