Laravel Valet

• Introducción
• Instalación
  • Actualización de Valet
• Sirviendo Sitios
  • El Comando "Park"
  • El Comando "Link"
  • Asegurar Sitios con TLS
  • Sirviendo un Sitio Predeterminado
  • Versiones de PHP por Sitio
• Compartir Sitios
  • Compartir Sitios en su Red Local
• Variables de Entorno Específicas del Sitio
• Proxy de Servicios
• Controladores Personalizados de Valet
  • Controladores Locales
• Otros Comandos de Valet
• Directorios y Archivos de Valet
  • Acceso a Disco

Introducción

Nota ¿Buscas una manera aún más fácil de desarrollar aplicaciones Laravel en macOS? Echa un vistazo a Laravel Herd. Herd incluye todo lo que necesitas para comenzar con el desarrollo de Laravel, incluyendo Valet, PHP y Composer.

Laravel Valet es un entorno de desarrollo para minimalistas de macOS. Laravel Valet configura tu Mac para ejecutar siempre Nginx en segundo plano cuando tu máquina se inicia. Luego, utilizando DnsMasq, Valet redirige todas las solicitudes en el dominio *.test para que apunten a los sitios instalados en tu máquina local.

En otras palabras, Valet es un entorno de desarrollo de Laravel extremadamente rápido que utiliza aproximadamente 7 MB de RAM. Valet no es un reemplazo completo de Sail o Homestead, pero proporciona una excelente alternativa si deseas tener lo esencial con flexibilidad, prefieres una velocidad extrema o estás trabajando en una máquina con una cantidad limitada de RAM.

Por defecto, el soporte de Valet incluye, pero no se limita a:

Sin embargo, puedes extender Valet con tus propios drivers personalizados.

Instalación

Advertencia Valet requiere macOS y Homebrew. Antes de la instalación, debes asegurarte de que no haya otros programas como Apache o Nginx que estén vinculados al puerto 80 de tu máquina local.

Para comenzar, primero debes asegurarte de que Homebrew esté actualizado usando el comando update:

brew update

A continuación, debes usar Homebrew para instalar PHP:

brew install php

Después de instalar PHP, estás listo para instalar el administrador de paquetes Composer. Además, debes asegurarte de que el directorio $HOME/.composer/vendor/bin esté en el "PATH" del sistema. Después de instalar Composer, puedes instalar Laravel Valet como un paquete global de Composer:

composer global require laravel/valet

Finalmente, puedes ejecutar el comando install de Valet. Esto configurará e instalará Valet y DnsMasq. Además, los demonios en los que depende Valet se configurarán para iniciarse cuando se inicie tu sistema:

valet install

Una vez instalado Valet, intenta hacer ping a cualquier dominio *.test en tu terminal usando un comando como ping foobar.test. Si Valet está instalado correctamente, deberías ver que este dominio responde en 127.0.0.1.

Valet iniciará automáticamente sus servicios requeridos cada vez que tu máquina se reinicie.

Versiones de PHP

Nota En lugar de modificar tu versión global de PHP, puedes indicar a Valet que use versiones de PHP por sitio a través del comando isolate.

Valet te permite cambiar las versiones de PHP usando el comando valet use php@version. Valet instalará la versión de PHP especificada a través de Homebrew si aún no está instalada:

valet use [email protected]
 
valet use php

También puedes crear un archivo .valetrc en la raíz de tu proyecto. El archivo .valetrc debe contener la versión de PHP que el sitio debe usar:

php=php@8.1

Una vez que se haya creado este archivo, simplemente puedes ejecutar el comando valet use y el comando determinará la versión de PHP preferida del sitio leyendo el archivo.

Advertencia Valet solo sirve una versión de PHP a la vez, incluso si tienes varias versiones de PHP instaladas.

Base de Datos

Si tu aplicación necesita una base de datos, echa un vistazo a DBngin, que proporciona una herramienta de gestión de bases de datos gratuita y todo en uno que incluye MySQL, PostgreSQL y Redis. Después de que DBngin haya sido instalado, puedes conectar a tu base de datos en 127.0.0.1 usando el nombre de usuario root y una cadena vacía como contraseña.

Restablecer su Instalación

Si tienes problemas para que tu instalación de Valet funcione correctamente, ejecutar el comando composer global require laravel/valet seguido de valet install restablecerá tu instalación y puede resolver una variedad de problemas. En casos raros, puede ser necesario "restablecer" Valet ejecutando valet uninstall --force seguido de valet install.

Actualización de Valet

Puedes actualizar tu instalación de Valet ejecutando el comando composer global require laravel/valet en tu terminal. Después de la actualización, es una buena práctica ejecutar el comando valet install para que Valet pueda realizar actualizaciones adicionales en tus archivos de configuración si es necesario.

Actualización a Valet 4

Si estás actualizando de Valet 3 a Valet 4, sigue los siguientes pasos para actualizar correctamente tu instalación de Valet:

Sirviendo Sitios

Una vez instalado Valet, estás listo para comenzar a servir tus aplicaciones Laravel. Valet proporciona dos comandos para ayudarte a servir tus aplicaciones: park y link.

El Comando park

El comando park registra un directorio en tu máquina que contiene tus aplicaciones. Una vez que el directorio ha sido "aparcado" con Valet, todos los directorios dentro de ese directorio serán accesibles en tu navegador web en http://<nombre-del-directorio>.test:

cd ~/Sites
 
valet park

Eso es todo. Ahora, cualquier aplicación que crees dentro de tu directorio "aparcado" se servirá automáticamente utilizando la convención http://<nombre-del-directorio>.test. Entonces, si tu directorio aparcado contiene un directorio llamado "laravel", la aplicación dentro de ese directorio será accesible en http://laravel.test. Además, Valet te permite acceder automáticamente al sitio utilizando subdominios de comodín (http://foo.laravel.test).

El Comando link

El comando link también se puede utilizar para servir tus aplicaciones Laravel. Este comando es útil si deseas servir un solo sitio en un directorio y no todo el directorio:

cd ~/Sites/laravel
 
valet link

Una vez que una aplicación ha sido vinculada a Valet usando el comando link, puedes acceder a la aplicación utilizando el nombre de su directorio. Así que, el sitio que se vinculó en el ejemplo anterior se puede acceder en http://laravel.test. Además, Valet te permite acceder al sitio utilizando subdominios de comodín (http://foo.laravel.test).

Si deseas servir la aplicación en un nombre de host diferente, puedes pasar el nombre de host al comando link. Por ejemplo, puedes ejecutar el siguiente comando para hacer que una aplicación esté disponible en http://application.test:

cd ~/Sites/laravel
 
valet link application

Por supuesto, también puedes servir aplicaciones en subdominios utilizando el comando link:

valet link api.application

Puedes ejecutar el comando links para mostrar una lista de todos tus directorios vinculados:

valet links

El comando unlink se puede utilizar para destruir el enlace simbólico de un sitio:

cd ~/Sites/laravel
 
valet unlink

Asegurar Sitios con TLS

Por defecto, Valet sirve sitios a través de HTTP. Sin embargo, si deseas servir un sitio a través de TLS cifrado utilizando HTTP/2, puedes usar el comando secure. Por ejemplo, si tu sitio está siendo servido por Valet en el dominio laravel.test, debes ejecutar el siguiente comando para asegurarlo:

valet secure laravel

Para "quitar" la seguridad de un sitio y volver a servir su tráfico a través de HTTP normal, utiliza el comando unsecure. Al igual que el comando secure, este comando acepta el nombre de host que deseas quitar la seguridad:

valet unsecure laravel

Sirviendo un Sitio Predeterminado

A veces, es posible que desees configurar Valet para servir un sitio "predeterminado" en lugar de un 404 al visitar un dominio test desconocido. Para lograr esto, puedes agregar una opción default a tu archivo de configuración ~/.config/valet/config.json que contenga la ruta del sitio que debería servir como tu sitio predeterminado:

"default": "/Users/Sally/Sites/example-site",

Versiones de PHP por Sitio

Por defecto, Valet utiliza tu instalación global de PHP para servir tus sitios. Sin embargo, si necesitas admitir varias versiones de PHP en varios sitios, puedes usar el comando isolate para especificar qué versión de PHP debería usar un sitio en particular. El comando isolate configura Valet para usar la versión de PHP especificada para el sitio ubicado en tu directorio de trabajo actual:

cd ~/Sites/example-site
 
valet isolate [email protected]

Si el nombre de tu sitio no coincide con el nombre del directorio que lo contiene, puedes especificar el nombre del sitio usando la opción --site:

valet isolate [email protected] --site="site-name"

Para mayor comodidad, puedes utilizar los comandos valet php, composer y which-php para enviar llamadas al CLI o herramienta de PHP apropiados según la versión de PHP configurada para el sitio:

valet php
valet composer
valet which-php

Puedes ejecutar el comando isolated para mostrar una lista de todos tus sitios aislados y sus versiones de PHP:

valet isolated

Para revertir un sitio a la versión global de PHP instalada por Valet, puedes invocar el comando unisolate desde el directorio raíz del sitio:

valet unisolate

Compartir Sitios

Valet incluye un comando para compartir tus sitios locales con el mundo, proporcionando una forma fácil de probar tu sitio en dispositivos móviles o compartirlo con miembros del equipo y clientes.

Por defecto, Valet admite compartir tus sitios a través de ngrok o Expose. Antes de compartir un sitio, debes actualizar la configuración de Valet usando el comando share-tool, especificando ya sea ngrok o expose:

valet share-tool ngrok

Si eliges una herramienta y no la tienes instalada a través de Homebrew (para ngrok) o Composer (para Expose), Valet te pedirá automáticamente que la instales. Por supuesto, ambas herramientas requieren que autentiques tu cuenta de ngrok o Expose antes de poder comenzar a compartir sitios.

Para compartir un sitio, navega al directorio del sitio en tu terminal y ejecuta el comando share de Valet. Se colocará una URL públicamente accesible en tu portapapeles y estará lista para pegar directamente en tu navegador o para compartirla con tu equipo:

cd ~/Sites/laravel
 
valet share

Para dejar de compartir tu sitio, puedes presionar Control + C.

Advertencia Si estás utilizando un servidor DNS personalizado (como 1.1.1.1), el uso compartido de ngrok puede no funcionar correctamente. Si este es el caso en tu máquina, abre la configuración del sistema de tu Mac, ve a la configuración de red, abre la configuración avanzada, luego ve a la pestaña DNS y agrega 127.0.0.1 como tu primer servidor DNS.

Compartir Sitios a través de Ngrok

Para compartir tu sitio usando ngrok, debes crear una cuenta en ngrok y configurar un token de autenticación. Una vez que tengas un token de autenticación, puedes actualizar la configuración de Valet con ese token:

valet set-ngrok-token YOUR_TOKEN_HERE

Nota Puedes pasar parámetros adicionales de ngrok al comando share, como valet share --region=eu. Para obtener más información, consulta la documentación de ngrok.

Compartir Sitios a través de Expose

Para compartir tu sitio usando Expose, debes crear una cuenta en Expose y autenticarte con Expose a través de tu token de autenticación.

Puedes consultar la documentación de Expose para obtener información sobre los parámetros adicionales admitidos por la línea de comandos.

Compartir Sitios en su Red Local

Valet restringe el tráfico entrante a la interfaz interna 127.0.0.1 por defecto para que tu máquina de desarrollo no esté expuesta a riesgos de seguridad desde Internet.

Si deseas permitir que otros dispositivos en tu red local accedan a los sitios de Valet en tu máquina a través de la dirección IP de tu máquina (por ejemplo, 192.168.1.10/application.test), deberás editar manualmente el archivo de configuración de Nginx correspondiente para ese sitio para quitar la restricción en la directiva listen. Debes eliminar el prefijo 127.0.0.1: en la directiva listen para los puertos 80 y 443.

Si no has ejecutado valet secure en el proyecto, puedes abrir el acceso de red para todos los sitios que no utilizan HTTPS editando el archivo /usr/local/etc/nginx/valet/valet.conf. Sin embargo, si estás sirviendo el sitio del proyecto a través de HTTPS (has ejecutado valet secure para el sitio), entonces debes editar el archivo ~/.config/valet/Nginx/app-name.test.

Una vez que hayas actualizado tu configuración de Nginx, ejecuta el comando valet restart para aplicar los cambios de configuración.

Variables de Entorno Específicas del Sitio

Algunas aplicaciones que utilizan otros marcos pueden depender de variables de entorno del servidor pero no proporcionan una forma de configurar esas variables dentro de tu proyecto. Valet te permite configurar variables de entorno específicas del sitio agregando un archivo .valet-env.php en la raíz de tu proyecto. Este archivo debe devolver un array de pares de sitio / variable de entorno que se agregarán al array global $_SERVER para cada sitio especificado en el array:

<?php
 
return [
    // Establecer $_SERVER['key'] en \"value\" para el sitio laravel.test...
    'laravel' => [
        'key' => 'value',
    ],
 
    // Establecer $_SERVER['key'] en \"value\" para todos los sitios...
    '*' => [
        'key' => 'value',
    ],
];

Proxy de Servicios

A veces puede que desees hacer un proxy de un dominio Valet a otro servicio en tu máquina local. Por ejemplo, es posible que ocasionalmente necesites ejecutar Valet mientras ejecutas simultáneamente un sitio separado en Docker; sin embargo, Valet y Docker no pueden ambos enlazar al puerto 80 al mismo tiempo.

Para resolver esto, puedes usar el comando proxy para generar un proxy. Por ejemplo, puedes hacer un proxy de todo el tráfico de http://elasticsearch.test a http://127.0.0.1:9200:

# Proxy over HTTP...
valet proxy elasticsearch http://127.0.0.1:9200
 
# Proxy over TLS + HTTP/2...
valet proxy elasticsearch http://127.0.0.1:9200 --secure

Puedes quitar un proxy usando el comando unproxy:

valet unproxy elasticsearch

Puedes usar el comando proxies para enumerar todas las configuraciones de sitios que están en modo de proxy:

valet proxies

Controladores Personalizados de Valet

Puedes escribir tu propio "driver" de Valet para servir aplicaciones PHP que se ejecutan en un marco o CMS que no es compatible nativamente con Valet. Cuando instalas Valet, se crea un directorio ~/.config/valet/Drivers que contiene un archivo SampleValetDriver.php. Este archivo contiene una implementación de driver de ejemplo para demostrar cómo escribir un driver personalizado. Escribir un driver solo requiere que implementes tres métodos: serves, isStaticFile y frontControllerPath.

Los tres métodos reciben los valores $sitePath, $siteName y $uri como sus argumentos. El $sitePath es la ruta totalmente calificada al sitio que se está sirviendo en tu máquina, como /Users/Lisa/Sites/my-project. El $siteName es la porción de "host" / "nombre del sitio" del dominio (my-project). El $uri es la URI de la solicitud entrante (/foo/bar).

Una vez que hayas completado tu driver personalizado de Valet, colócalo en el directorio ~/.config/valet/Drivers utilizando la convención de nomenclatura FrameworkValetDriver.php. Por ejemplo, si estás escribiendo un driver personalizado de Valet para WordPress, el nombre de archivo debería ser WordPressValetDriver.php.

Veamos una implementación de ejemplo de cada método que tu driver personalizado de Valet debería implementar.

El Método serves

El método serves debe devolver true si tu driver debe manejar la solicitud entrante. De lo contrario, el método debe devolver false. Por lo tanto, dentro de este método, debes intentar determinar si el $sitePath dado contiene un proyecto del tipo que estás tratando de servir.

Por ejemplo, imaginemos que estamos escribiendo un WordPressValetDriver. Nuestro método serves podría parecer algo así:

/**
 * Determinar si el controlador sirve la solicitud.
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

El Método isStaticFile

El método isStaticFile debe determinar si la solicitud entrante es para un archivo que es "estático", como una imagen o una hoja de estilo. Si el archivo es estático, el método debe devolver la ruta totalmente calificada al archivo estático en el disco. Si la solicitud entrante no es para un archivo estático, el método debe devolver false:

/**
 * Determinar si la solicitud entrante es para un archivo estático.
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }
 
    return false;
}

Advertencia El método isStaticFile solo se llamará si el método serves devuelve true para la solicitud entrante y la URI de la solicitud no es /.

El Método frontControllerPath

El método frontControllerPath debe devolver la ruta totalmente calificada al "front controller" de tu aplicación, que suele ser un archivo "index.php" o equivalente:

/**
 * Obtener la ruta completamente resuelta al controlador frontal de la aplicación.
 */
public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
{
    return $sitePath.'/public/index.php';
}

Controladores Locales

Si deseas definir un driver personalizado de Valet para una sola aplicación, crea un archivo LocalValetDriver.php en el directorio raíz de la aplicación. Tu driver personalizado puede extender la clase base ValetDriver o extender un driver específico de la aplicación existente como el LaravelValetDriver:

use Valet\Drivers\LaravelValetDriver;
 
class LocalValetDriver extends LaravelValetDriver
{
    /**
     * Determinar si el controlador sirve la solicitud.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }
 
    /**
     * Obtener la ruta completamente resuelta al controlador frontal de la aplicación.
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        return $sitePath.'/public_html/index.php';
    }
}

Otros Comandos de Valet

Directorios y Archivos de Valet

Puedes encontrar la siguiente información de directorios y archivos útil al solucionar problemas con tu entorno de Valet:

~/.config/valet

Contiene toda la configuración de Valet. Puede ser útil mantener una copia de seguridad de este directorio.

~/.config/valet/dnsmasq.d/

Este directorio contiene la configuración de DNSMasq.

~/.config/valet/Drivers/

Este directorio contiene los drivers de Valet. Los drivers determinan cómo se sirve un marco o CMS en particular.

~/.config/valet/Nginx/

Este directorio contiene todas las configuraciones de sitio de Nginx de Valet. Estos archivos se reconstruyen al ejecutar los comandos install y secure.

~/.config/valet/Sites/

Este directorio contiene todos los enlaces simbólicos para tus proyectos vinculados.

~/.config/valet/config.json

Este archivo es el archivo de configuración principal de Valet.

~/.config/valet/valet.sock

Este archivo es el socket PHP-FPM utilizado por la instalación de Nginx de Valet. Esto solo existirá si PHP se está ejecutando correctamente.

~/.config/valet/Log/fpm-php.www.log

Este archivo es el registro de usuario para errores de PHP.

~/.config/valet/Log/nginx-error.log

Este archivo es el registro de usuario para errores de Nginx.

/usr/local/var/log/php-fpm.log

Este archivo es el registro del sistema para errores de PHP-FPM.

/usr/local/var/log/nginx

Este directorio contiene los registros de acceso y error de Nginx.

/usr/local/etc/php/X.X/conf.d

Este directorio contiene los archivos *.ini para varias configuraciones de PHP.

/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf

Este archivo es el archivo de configuración de la piscina PHP-FPM.

~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf

Este archivo es la configuración predeterminada de Nginx utilizada para construir certificados SSL para tus sitios.

Acceso a Disco

Desde macOS 10.14, el acceso a algunos archivos y directorios está restringido por defecto. Estas restricciones incluyen los directorios de Escritorio, Documentos y Descargas. Además, el acceso a volúmenes de red y volúmenes extraíbles está restringido. Por lo tanto, Valet recomienda que las carpetas de tus sitios se encuentren fuera de estas ubicaciones protegidas.

Sin embargo, si deseas servir sitios desde dentro de una de esas ubicaciones, deberás darle a Nginx "Acceso completo al disco". De lo contrario, puedes encontrar errores del servidor u otro comportamiento impredecible por parte de Nginx, especialmente al servir activos estáticos. Normalmente, macOS te pedirá automáticamente que otorgues a Nginx acceso completo a estas ubicaciones. O puedes hacerlo manualmente a través de Preferencias del sistema > Seguridad y privacidad > Privacidad y seleccionar Acceso completo al disco. Luego, habilita cualquier entrada de nginx en la ventana principal.