Introducción

Laravel se ha esforzado en hacer que toda la experiencia del desarrollo de PHP sea placentera, incluyendo el entorno de desarrollo local. Vagrant provee una manera simple y elegante de administrar y aprovisionar máquinas virtuales.

Laravel Homestead es el box de Vagrant pre-empaquetado oficial que brinda un maravilloso entorno de desarrollo sin la necesidad de que tengas que instalar PHP, un servidor web, ni ningún otro software de servidor en tu máquina local. ¡Basta de preocuparte por estropear tu sistema operativo! Los boxes de Vagrant son completamente desechables. Si algo sale mal, simplemente puedes destruir y volver a crear el box en cuestión de minutos.

Homestead puede ejecutarse en sistemas Windows, Mac y Linux e incluye Nginx, PHP, MySQL, PostgreSQL, Redis, Memcached, Node y todas las demás herramientas que necesitas para desarrollar aplicaciones de Laravel sorprendentes.

Si estás utilizando Windows, puede que necesites habilitar la virtualización por hardware (VT-x). Usualmente puede habilitarse en el BIOS. Si estás utilizando Hyper-V en un sistema UEFI puede que requieras también deshabilitar Hyper-V para poder acceder a VT-x.

Software incluido

  • Ubuntu 18.04
  • Git
  • PHP 7.4
  • PHP 7.3
  • PHP 7.2
  • PHP 7.1
  • PHP 7.0
  • PHP 5.6
  • Nginx
  • MySQL
  • lmm para instantáneas de bases de datos MySQL o MariaDB
  • Sqlite3
  • PostgreSQL
  • Composer
  • Node (Con Yarn, Bower, Grunt, y Gulp)
  • Redis
  • Memcached
  • Beanstalkd
  • Mailhog
  • avahi
  • ngrok
  • Xdebug
  • XHProf / Tideways / XHGui
  • wp-cli

Software opcional

  • Apache
  • Blackfire
  • Cassandra
  • Chronograf
  • CouchDB
  • Crystal & Lucky Framework
  • Docker
  • Elasticsearch
  • Gearman
  • Go
  • Grafana
  • InfluxDB
  • MariaDB
  • MinIO
  • MongoDB
  • MySQL 8
  • Neo4j
  • Oh My Zsh
  • Open Resty
  • PM2
  • Python
  • RabbitMQ
  • Solr
  • Webdriver & Laravel Dusk Utilities

Instalación y configuración

Primeros pasos

Antes de iniciar tu entorno de Homestead, debes instalar VirtualBox 6.x, VMWare, Parallels o Hyper-V además de Vagrant. Todos estos paquetes de software cuentan con un instalador fácil de usar para todos los sistemas operativos populares.

Para utilizar el proveedor de VMware, necesitarás comprar tanto VMware Fusion / Workstation como el plugin de Vagrant para VMware. A pesar de que esto no es gratuito, VMware ofrece un mayor desempeño en velocidad al compartir directorios.

Para utilizar el proveedor de Parallels, debes instalar el plugin de Vagrant para Parallels. Es totalmente gratuito.

Debido a las limitaciones de Vagrant, el proveedor de Hyper-V ignora todas las configuraciones de red.

Instalar el Box de Vagrant para Homestead

Una vez que estén instalados VirtualBox / VMWare y Vagrant, deberás añadir el box laravel/homestead a tu instalación de Vagrant ejecutando el siguiente comando en la terminal. Esto tomará algunos minutos para descargar el box, dependiendo de tu velocidad de internet:

vagrant box add laravel/homestead

Si el comando falla, asegúrate de que tu instalación de Vagrant esté actualizada.

Homestead publica periódicamente boxes «alpha» / «beta» para las pruebas, lo que puede interferir con el comando vagrant box add. Si tienes problemas para ejecutar vagrant box add, puedes ejecutar el comando vagrant up y el box correcto se descargará cuando Vagrant intente iniciar la máquina virtual.

Instalar Homestead

Puedes instalar Homestead clonando el repositorio en tu máquina host. Considera clonar el repositorio en una carpeta Homestead dentro de tu directorio «home», ya que el box de Homestead actuará como host para todos tus proyectos de Laravel:

git clone https://github.com/laravel/homestead.git ~/Homestead

Deberías comprobar alguna versión etiquetada de Homestead ya que la rama master no siempre es estable. Puedes encontrar la versión estable más reciente en la Página de Releases de GitHub. De forma alternativa, puedes revisar el branch release el cual siempre es actualizado con la última versión estable.

cd ~/Homestead

git checkout release

Una vez que hayas clonado el repositorio, ejecuta el comando bash init.sh desde el directorio Homestead para crear el archivo de configuración Homestead.yaml. El archivo Homestead.yaml estará situado en el directorio de Homestead:

// Mac / Linux...
bash init.sh

// Windows...
init.bat

Configurar Homestead

Especificando tu proveedor

La clave provider en tu archivo Homestead.yaml indica cuál proveedor de Vagrant será utilizado: virtualbox, vmware_fusion, vmware_workstation, parallels o hyperv. Puedes especificar en esta opción el proveedor de tu preferencia:

provider: virtualbox

Configurar directorios compartidos

La propiedad folders del archivo Homestead.yaml lista todos los directorios que deseas compartir con tu entorno de Homestead. A medida que los archivos dentro de estos directorios cambien, estos se mantendrán sincronizados con tu máquina local y el entorno de Homestead. Puedes configurar tantos directorios compartidos como sean necesarios:

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1

Los usuarios de Windows no deben usar la sintaxis de ruta ~/ y en su lugar deberían usar la ruta completa al proyecto, como C:\Users\user\Code\project1.

Siempre debes mapear proyectos individuales en su propio directorio en lugar de mapear tu directorio ~/code entero. Cuando mapeas un directorio, la máquina virtual debe mantener un seguimiento de todos los I/O que suceden en cada archivo en el directorio. Esto puede llevar a que sucedan problemas de rendimiento si tienes un gran número de archivos en un directorio.

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1

    - map: ~/code/project2
      to: /home/vagrant/project2

Nunca debes montar . (el directorio actual) al usar Homestead. Esto causa que Vagrant no mapee el directorio actual a /vagrant y romperá características adicionales además de causar resultados inesperados al momento del aprovisionamiento.

Para habilitar NFS, solo necesitarás agregar un simple flag en la configuración de tu directorio sincronizado:

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "nfs"

Cuando uses NFS en Windows, debes considerar instalar el plugin vagrant-winnfsd. Este plugin mantendrá los permisos correctos de usuario / grupo para los archivos y directorios dentro del box de Homestead.

También puedes indicar cualquier opción soportada por los Directorios Sincronizados de Vagrant, listándolos bajo la clave options:

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "rsync"
      options:
          rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
          rsync__exclude: ["node_modules"]

Configurar sitios de Nginx

¿No estás familiarizado con Nginx? No hay problema. La propiedad sites te permitirá mapear un «dominio» a un directorio en tu entorno de Homestead de manera sencilla. Una configuración de un sitio de ejemplo está incluida en el archivo Homestead.yaml. Nuevamente, podrás añadir tantos sitios a tu entorno de Homestead como sea necesario. Homestead puede funcionar como un conveniente entorno virtualizado para cada proyecto de Laravel en el que estés trabajando:

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public

Si cambias la propiedad sites después de haber aprovisionado el box de Homestead, deberás volver a ejecutar vagrant reload --provision para actualizar la configuración de Nginx en la máquina virtual.

Los scripts de Homestead son construidos tan idempotente como sea posible. Sin embargo, si estás experimentando problemas al momento del aprovisionamiento, debes destruir y reconstruir la máquina a través de vagrant destroy && vagrant up.

Resolución del hostname

Homestead publica hostnames sobre mDNS para la resolución automática del host. Si estableces hostname: homestead en tu archivo Homestead.yaml, el host estará disponible en homestead.local. Las distribuciones de escritorio de MacOS, iOS, y Linux incluyen soporte mDNS de forma predeterminada. Windows requiere la instalación del Servicio Bonjour Print para Windows.

El uso de hostnames automáticos funciona mejor para las instalaciones «por proyecto» de Homestead. Si alojas varios sitios en una sola instancia de Homestead, puedes agregar los «dominios» de tus sitios web al archivo hosts en tu máquina. El archivo hosts va a redirigir las peticiones de los sitios Homestead hacia tu máquina Homestead. En Mac y Linux, este archivo está ubicado en /etc/hosts. En Windows, este archivo está ubicado en C:\Windows\System32\drivers\etc\hosts. Las líneas que agregues a este archivo deberán verse de la siguiente forma:

192.168.10.10  homestead.test

Debes asegurarte que la IP indicada sea la misma que está en el archivo Homestead.yaml. Una vez que hayas añadido el dominio a tu archivo hosts y hayas iniciado el box de Vagrant podrás acceder al sitio desde el navegador web:

http://homestead.test

Iniciando el box de Vagrant

Una vez que hayas editado el archivo Homestead.yaml a tu gusto, ejecuta el comando vagrant up desde tu directorio Homestead. Vagrant va a iniciar la máquina virtual y a configurar automáticamente tus directorios compartidos y sitios de Nginx.

Para destruir la máquina, debes utilizar el comando vagrant destroy --force.

Instalación por proyecto

En lugar de instalar Homestead globalmente y compartir el mismo box de Homestead para todos tus proyectos, también es posible configurar una instancia de Homestead para cada proyecto que necesites. Instalar Homestead por proyecto puede ser beneficioso si deseas crear un Vagrantfile en tu proyecto, permitiendo así a otras personas trabajar en el mismo proyecto ejecutando simplemente vagrant up.

Para instalar Homestead directamente en tu proyecto, debes hacerlo por medio de Composer:

composer require laravel/homestead --dev

Una vez que Homestead haya sido instalado, usa el comando make para generar el archivo Vagrantfile y Homestead.yaml en la raíz de tu proyecto. El comando make configurará automáticamente las directivas sites y folders en el archivo Homestead.yaml.

Mac / Linux:

php vendor/bin/homestead make

Windows:

vendor\\bin\\homestead make

Después, ejecuta el comando vagrant up en tu terminal y podrás acceder a tu proyecto desde el navegador en http://homestead.test. Recuerda, aún vas a necesitar agregar una entrada para homestead.test en tu archivo /etc/hosts o el dominio de tu elección si no estás usando resolución de hostname automática.

Instalando características opcionales

El software opcional es instalado usando la opción «features» en tu archivo de configuración de Homestead. La mayoría de las características son habilitadas o deshabilitadas con un valor booleano, mientras que algunas características soportan múltiples opciones de configuración:

features:
    - blackfire:
        server_id: "server_id"
        server_token: "server_value"
        client_id: "client_id"
        client_token: "client_value"
    - cassandra: true
    - chronograf: true
    - couchdb: true
    - crystal: true
    - docker: true
    - elasticsearch:
        version: 7
    - gearman: true
    - golang: true
    - grafana: true
    - influxdb: true
    - mariadb: true
    - minio: true
    - mongodb: true
    - mysql8: true
    - neo4j: true
    - ohmyzsh: true
    - openresty: true
    - pm2: true
    - python: true
    - rabbitmq: true
    - solr: true
    - webdriver: true

MariaDB

Activar MariaDB eliminará MySQL e instalará MariaDB. MariDB funciona como reemplazo de MySQL, así que aún serás capaz de usar el driver de base de datos mysql en la configuración de la base de datos de tu aplicación.

MongoDB

La instalación por defecto de MongoDB establecerá el nombre de usuario de base de datos a homestead y su contraseña como secret.

Elasticsearch

Puedes especificar una versión soportada de Elasticsearch, la cual puede ser una versión principal o un número de versión exacto (major.minor.patch). La instalación por defecto creará un clúster llamado ‘homestead’. Nunca debes darle a Elasticsearch más de la mitad de la memoria del sistema operativo, así que asegúrate de que tu máquina Homestead al menos tiene el doble de la cantidad asignada a Elasticsearch.

Da un vistazo a la documentación de Elasticsearch para aprender a personalizar tu configuración.

Neo4j

La instalación por defecto de Neo4j establecerá el nombre de usuario de base de datos como homestead y su contraseña como secret. Para acceder al navegador Neo4j, visita http://homestead.test:7474 mediante tu navegador. Los puertos 7687 (Bolt), 7474 (HTTP), y 7473 (HTTPS) son preparados para manejar peticiones desde el cliente Neo4j.

Alias

Puedes añadir alias de Bash a tu máquina de Homestead modificando el archivo aliases dentro de tu directorio de Homestead:

alias c='clear'
alias ..='cd ..'

Después de haber actualizado el archivo aliases, debes re-aprovisionar la máquina de Homestead usando el comando vagrant reload --provision. Con esto te podrás asegurar de que tus nuevos alias estén disponibles en la máquina.

Uso diario

Acceder a Homestead globalmente

En ocasiones puede que requieras iniciar Homestead con el comando vagrant up desde cualquier parte en tu sistema de archivos. Esto es posible en sistemas Mac / Linux al agregar una función Bash en tu Bash Profile. En Windows, esto puede lograrse al agregar un archivo «batch» en tu PATH. Estos scripts te permitirán ejecutar cualquier comando de Vagrant desde cualquier parte en tu sistema y automáticamente apuntarán el comando hacia tu instalación de Homestead:

Mac / Linux

function homestead() {
    ( cd ~/Homestead && vagrant $* )
}

Asegúrate de modificar la ruta ~/Homestead en la función hacia la ubicación actual de tu instalación de Homestead. Una vez que hayas instalado la función, podrás ejecutar comandos como homestead up o homestead ssh desde cualquier parte en tu sistema de archivos.

Windows

Crea un archivo batch llamado homestead.bat en alguna parte de tu equipo con el siguiente contenido:

@echo off

set cwd=%cd%
set homesteadVagrant=C:\Homestead

cd /d %homesteadVagrant% && vagrant %*
cd /d %cwd%

set cwd=
set homesteadVagrant=

Asegúrate de modificar la ruta de ejemplo C:\Homestead en el script por la ruta actual de tu instalación de Homestead. Después de crear el archivo, agrega la ubicación a tu PATH. Hecho esto, podrás ejecutar comandos como homestead up o homestead ssh desde cualquier lado en tu sistema.

Conexión vía SSH

Puedes conectarte a tu máquina virtual por medio de SSH haciendo uso del comando vagrant ssh en la terminal desde tu directorio Homestead.

Pero, dado que probablemente requieras conectarte frecuentemente a tu máquina de Homestead, deberías considerar agregar la «función» descrita anteriormente en tu equipo host para poder conectarte de manera rápida a tu box de Homestead por medio de SSH.

Conectar a base de datos

Una base de datos homestead es configurada por defecto tanto para MySQL como para PostgreSQL. Para conectarte a tu base de datos de MySQL o de PostgreSQL desde el cliente de base de datos de tu equipo host, deberás conectarte hacia 127.0.0.1 en el puerto 33060 (MySQL) o 54320 (PostgreSQL). El nombre de usuario y contraseña para ambas bases de datos son homestead / secret.

Solo deberías utilizar estos puertos no estándares para conectarte a tus bases de datos desde tu equipo host. Deberás utilizar los puertos por defecto 3306 y 5432 en tu archivo de configuración para la base de datos de Laravel que se encuentra ejecutándose dentro de la máquina virtual.

Respaldos de base de datos

Homestead puede hacer respaldos de tu base de datos automáticamente cuando tu box de Vagrant es destruida. Para utilizar esta característica, debes estar usando Vagrant 2.1.0 o una versión superior. O, si estás usando una versión inferior, debes instalar el plugin vagrant-triggers. Para activar los respaldos de base de datos automáticos, agrega la siguiente línea a tu archivo Homestead.yaml:

backup: true

Una vez esté configurado, Homestead exportará tus bases de datos a los directorios mysql_backup y postgres_backup cuando se ejecute el comando vagrant destroy. Estos directorios pueden ser encontrados en la carpeta donde clonaste Homestead o en el root de tu proyecto si estás usando el método de instalación por proyecto.

Instantáneas de la base de datos

Homestead admite la congelación del estado de las bases de datos MySQL y MariaDB y se ramifica entre ellas con Logical MySQL Manager. Por ejemplo, imagina trabajar en un sitio con una base de datos de varios gigabytes. Puedes importar la base de datos y tomar una instantánea. Después de realizar un trabajo y crear un contenido de prueba localmente, puedes restaurar rápidamente al estado original.

Por debajo, LMM usa la funcionalidad de instantáneas delgadas de LVM con soporte de copia en escritura. En la práctica, esto significa que el cambio de una sola fila en una tabla sólo hará que los cambios que realice se escriban en el disco, ahorrando tiempo y espacio de disco significativos durante las restauraciones.

Como lmm interactúa con LVM, debe ejecutarse como root. Para ver todos los comandos disponibles, ejecute sudo lmm dentro de la caja de Vagrant. Un flujo de trabajo común sería:

  1. Importe una base de datos a la rama predeterminada de master lmm.
  2. Guarde una instantánea de la base de datos sin cambios usando sudo lmm branch prod-YYYY-MM-DD.
  3. Modifica la Base de Datos.
  4. Ejecute sudo lmm merge prod-YYYY-MM-DD para deshacer todos los cambios.
  5. Ejecute sudo lmm delete <branch> para eliminar todas las ramas que no se necesiten.

Agregar sitios adicionales

Una vez que tu entorno de Homestead haya sido aprovisionado y esté en ejecución, es probable que requieras agregar sitios adicionales de Nginx para tu aplicación de Laravel. Puedes ejecutar tantas instalaciones de Laravel como desees en un único entorno Homestead. Para añadir un sitio adicional, agrega el sitio a tu archivo Homestead.yaml.

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
    - map: another.test
      to: /home/vagrant/project2/public

Si Vagrant no está manejando tu archivo «hosts» de manera automática, también deberás agregar el nuevo sitio a este archivo:

192.168.10.10  homestead.test
192.168.10.10  another.test

Una vez que el sitio ha sido agregado, ejecuta el comando vagrant reload --provision desde tu directorio de Homestead.

Tipos de sitios

Homestead soporta varios tipos de sitios permitiéndote ejecutar fácilmente proyectos que no estén basados en Laravel. Por ejemplo, puedes agregar fácilmente una aplicación de Symfony en Homestead utilizando el tipo de sitio symfony2:

sites:
    - map: symfony2.test
      to: /home/vagrant/my-symfony-project/web
      type: "symfony2"

Los tipos de sitios disponibles son: apache, apigility, expressive, laravel (por defecto), proxy, silverstripe, statamic, symfony2, symfony4 y zf.

Parámetros de los sitios

También puedes agregar valores adicionales de fastcgi_param en Nginx para tus sitios por medio de la directiva params en el sitio. Por ejemplo, añadiremos el parámetro FOO con el valor de BAR:

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      params:
          - key: FOO
            value: BAR

Variables de entorno

Puedes especificar variables de entorno globales al agregarlas en tu archivo Homestead.yaml:

variables:
    - key: APP_ENV
      value: local
    - key: FOO
      value: bar

Después de actualizar el archivo Homestead.yaml, deberás re-aprovisionar la máquina ejecutando el comando vagrant reload --provision. Esto actualizará la configuración de PHP-FPM para todas las versiones instaladas de PHP y también actualizará el entorno para el usuario vagrant.

Configurar tareas programadas

Laravel proporciona una manera conveniente de ejecutar tareas programadas al configurar las tareas por medio del comando de Artisan schedule:run para que se ejecute cada minuto. El comando schedule:run va a examinar las tareas programadas definidas en tu clase App\Console\Kernel para determinar cuáles tareas deben ser ejecutadas.

Si deseas que el comando schedule:run sea ejecutado en un sitio de Homestead, debes indicar la opción schedule como true cuando definas el sitio:

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      schedule: true

La tarea programada para este sitio estará definida en el directorio /etc/cron.d de tu máquina virtual.

Configuración de Mailhog

Mailhog te permite capturar fácilmente el correo saliente y examinarlo sin que éste sea enviado hacia sus destinatarios. Para comenzar, actualiza tu archivo .env con la siguiente configuración:

MAIL_DRIVER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

Una vez que Mailhog ha sido configurado, puedes acceder al dashboard de Mailhog en http://localhost:8025.

Configuración de Minio

Minio es un servidor de almacenamiento de objetos de código libre con una API compatible con Amazon S3. Para instalar Minio, actualiza tu archivo Homestead.yaml con la siguiente opción de configuración en la sección features:

minio: true

Por defecto, Minio está disponible en el puerto 9600. Puedes acceder al panel de control de Minio visitando http://localhost:9600/. La clave de acceso por defecto es homestead, mientras que la clave secreta por defecto es secretkey. Al acceder a Minio, siempre debes usar la región us-east-1.

Para usar Minio necesitarás ajustar la configuración de disco S3 en tu archivo de configuración config/filesystems.php. Necesitarás añadir la opción use_path_style_endpoint a la configuración del disco, así como cambiar la clave url a endpoint:

's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
    'bucket' => env('AWS_BUCKET'),
    'endpoint' => env('AWS_URL'),
    'use_path_style_endpoint' => true
]

Por último, asegúrate de que tu archivo .env tenga las siguientes opciones:

AWS_ACCESS_KEY_ID=homestead
AWS_SECRET_ACCESS_KEY=secretkey
AWS_DEFAULT_REGION=us-east-1
AWS_URL=http://localhost:9600

Para proveer buckets, agrega una directiva buckets a tu archivo de configuración Homestead:

buckets:
    - name: your-bucket
      policy: public
    - name: your-private-bucket
      policy: none

Los valores soportados por policy incluyen: none, download, upload y public.

Puertos

Por defecto, los siguientes puertos están redirigidos a tu entorno de Homestead:

  • SSH: 2222 → Redirige a 22
  • ngrok UI: 4040 → Redirige a 4040
  • HTTP: 8000 → Redirige a 80
  • HTTPS: 44300 → Redirige a 443
  • MySQL: 33060 → Redirige a 3306
  • PostgreSQL: 54320 → Redirige a 5432
  • MongoDB: 27017 → Redirige a 27017
  • Mailhog: 8025 → Redirige a 8025
  • Minio: 9600 → Redirige a 9600

Redirigir puertos adicionales

Si lo deseas, puedes redirigir puertos adicionales a tu box de Vagrant, así como su protocolo:

ports:
    - send: 50000
      to: 5000
    - send: 7777
      to: 777
      protocol: udp

Compartir tu entorno

En ocasiones, podrás requerir compartir lo que estás haciendo con algún compañero de trabajo o algún cliente. Vagrant tiene incorporado una manera de hacer esto por medio del comando vagrant share; sin embargo, esto no funcionará si se tienen configurados múltiples sitios en tu archivo Homestead.yaml.

Para resolver este problema, Homestead incluye su propio comando share. Para utilizarlo, conéctate por SSH a tu máquina virtual de Homestead con el comando vagrant ssh y ejecuta el comando share homestead.test. Esto va a compartir el sitio homestead.test especificado en el archivo de configuración Homestead.yaml. Puedes sustituir cualquiera de tus otros sitios configurados por homestead.test.

share homestead.test

Después de ejecutar este comando, podrás ver que aparece una ventana de Ngrok, la cual contiene el log de actividad y las URLs accesibles de manera pública para el sitio compartido. Si deseas especificar una región personalizada, un subdominio o el tiempo de ejecución de Ngrok, puedes hacerlo desde el comando share:

share homestead.test -region=eu -subdomain=laravel

Recuerda, Vagrant es inherentemente inseguro y estarás compartiendo tu máquina virtual en Internet cuando ejecutes el comando share.

Múltiples versiones de PHP

Homestead 6 introduce soporte para múltiples versiones de PHP en una misma máquina virtual. Puedes especificar qué versión de PHP deseas utilizar para un sitio en particular desde tu archivo Homestead.yaml. Las versiones disponibles de PHP son: «5.6», «7.0», «7.1», «7.2», «7.3» y «7.4» (por defecto):

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      php: "7.1"

Además, puedes utilizar cualquiera de las versiones soportadas de PHP desde el CLI:

php5.6 artisan list
php7.0 artisan list
php7.1 artisan list
php7.2 artisan list
php7.3 artisan list
php7.4 artisan list

También puedes actualizar la versión por defecto de la línea de comandos ejecutando los siguientes comandos dentro de tu máquina virtual de Homestead:

php56
php70
php71
php72
php73
php74

Servidores web

Homestead utiliza por defecto el servidor web Nginx. Sin embargo, también se puede instalar Apache si se especifica el tipo de sitio como apache. Ambos servidores pueden instalarse al mismo tiempo, pero no pueden ejecutarse al mismo tiempo. El comando flip está disponible en el shell para facilitar el proceso de cambiar entre servidores web. El comando flip automáticamente va a determinar cuál servidor web está en ejecución, después lo va a detener y por último va a iniciar el otro servidor. Para utilizar este comando, primero deberás conectarte a la máquina virtual de Homestead por medio de SSH y ejecutar el comando en la terminal:

flip

Correo electrónico

Homestead incluye el agente de transferencia de correo Postfix, que está escuchando por defecto en el puerto 1025. Así que puedes indicarle a tu aplicación que use el controlador de correo smtp en el puerto 1025 de localhost. Entonces, todos los correos enviados serán manejados por Postfix y atrapados por Mailhog. Para ver tus correos enviados, abre en tu navegador http://localhost:8025.

Depuración y perfilado

Depuración de solicitudes web con Xdebug

Homestead incluye soporte para la depuración por pasos usando Xdebug. Por ejemplo, puedes cargar una página web desde un navegador y PHP se conectará nuevamente a su IDE para permitir la inspección y modificación del código en ejecución.

De forma predeterminada, Xdebug ya se está ejecutando y está listo para aceptar conexiones. Si necesitas habilitar Xdebug en la CLI, ejecuta el comando sudo phpenmod xdebug dentro de tu caja de Vagrant. Luego, sigue las instrucciones de tu IDE para habilitar la depuración. Finalmente, configura tu navegador para activar Xdebug con una extensión o bookmarklet.

Xdebug puede ralentizar significativamente a PHP. Para deshabilitar Xdebug, ejecuta sudo phpdismod xdebug dentro de tu caja de Vagrant y reinicia el servicio FPM nuevamente.

Depuración de aplicaciones CLI

Para depurar una aplicación CLI de PHP, usa el alias de shell xphp dentro de la caja Vagrant:

xphp path/to/script

Auto iniciando Xdebug

Al depurar pruebas funcionales que realizan solicitudes al servidor web, es más fácil iniciar automáticamente la depuración en lugar de modificar las pruebas para pasar a través de un encabezado personalizado o una cookie para activar la depuración. Para forzar el inicio de Xdebug, modifica /etc/php/7.x/fpm/conf.d/20-xdebug.ini dentro de tu caja Vagrant y agrega la siguiente configuración:

; If Homestead.yaml contains a different subnet for the IP address, this address may be different...
xdebug.remote_host = 192.168.10.1
xdebug.remote_autostart = 1

Perfilar aplicaciones con Blackfire

Blackfire es un servicio SaaS para perfilar solicitudes web, aplicaciones de línea de comandos y escribir aserciones de rendimiento. Ofrece una interfaz de usuario interactiva que muestra datos de perfiles en call-graphs y líneas de tiempo. Está construido para ser usado en desarrollo, staging y producción, sin sobrecarga para usuarios finales. Proporciona comprobaciones de rendimiento, calidad y seguridad del código y opciones de configuración para php.ini.

Blackfire Player es una aplicación de Web Crawling, Pruebas Web y Web Scraping que puede funcionar junto con Blackfire para perfilar escenarios.

Para habilitar Blackfire, usa la opción «features» en tu archivo de configuración Homestead:

features:
    - blackfire:
        server_id: "server_id"
        server_token: "server_value"
        client_id: "client_id"
        client_token: "client_value"

Las credenciales de servidor y las credenciales de clientes requieren una cuenta de usuario. Blackfire ofrece varias opciones para perfilar una aplicación, incluyendo una herramienta de línea de comandos y extensión de navegador. Por favor revisa la documentación de Blackfire para más detalles.

Perfilando el rendimiento de PHP usando XHGui

XHGui es una interfaz de usuario para explorar el rendimiento de tus aplicaciones PHP. Para habilitar XHGui, agrega xhgui: 'true' a la configuración de tu sitio:

sites:
    -
        map: your-site.test
        to: /home/vagrant/your-site/public
        type: "apache"
        xhgui: 'true'

Si el sitio ya existe, asegúrate de ejecutar vagrant provision después de actualizar tu configuración.

Para perfilar una solicitud web, agrega xhgui=on como parámetro de consulta a una solicitud. XHGui automáticamente adjuntará una cookie a la respuesta para que las solicitudes posteriores no necesiten el valor de la cadena de consulta. Puede ver los resultados de tu perfil de aplicación navegando a http://your-site.test/xhgui.

Para perfilar una solicitud de CLI usando XHGui, prefija el comando con XHGUI=on:

XHGUI=on path/to/script

Los resultados del perfil CLI pueden ser vistos en la misma forma como los resultados del perfil web.

Tenga en cuenta que el acto de perfilar ralentiza la ejecución del script y los tiempos absolutos pueden ser el doble de las solicitudes del mundo real. Por lo tanto, siempre compare el porcentaje de las mejoras y no los números absolutos. Además, tenga en cuenta que el tiempo de ejecución incluye cualquier tiempo que se pase en pausa en un depurador.

Dado que los perfiles de rendimiento ocupan un espacio de disco significativo, se eliminan automáticamente después de unos días.

Interfaces de red

La propiedad networks del archivo Homestead.yaml configura las interfaces de red de tu entorno Homestead. Puedes configurar tantas interfaces como sea necesario:

networks:
    - type: "private_network"
      ip: "192.168.10.20"

Para habilitar una interfaz en puente, debes indicar la propiedad bridge y cambiar el tipo de red a public_network:

networks:
    - type: "public_network"
      ip: "192.168.10.20"
      bridge: "en1: Wi-Fi (AirPort)"

Para habilitar DHCP, sólo debes remover la opción ip de tu configuración:

networks:
    - type: "public_network"
      bridge: "en1: Wi-Fi (AirPort)"

Extender Homestead

Puedes extender Homestead usando el script after.sh en la raíz de tu directorio Homestead. Dentro de este archivo, puedes agregar cualquier comando shell que sea necesario para configurar y personalizar apropiadamente tu máquina virtual.

Al personalizar Homestead, Ubuntu puede preguntar si deseas conservar la configuración original de un paquete o sobrescribirla con un nuevo archivo de configuración. Para evitar esto, debes usar el siguiente comando al instalar paquetes para evitar sobrescribir cualquier configuración escrita previamente por Homestead:

sudo apt-get -y \
    -o Dpkg::Options::="--force-confdef" \
    -o Dpkg::Options::="--force-confold" \
    install your-package

Personalizaciones de usuario

Al usar Homestead en un ambiente de equipo, puedes querer configurar Homestead para que se ajuste mejor a tu estilo de desarrollo personal. Puedes crear un archivo user-customizations.sh en la raíz de tu directorio Homestead (el mismo directorio que contiene tu Homestead.yaml). Dentro de este archivo, puedes hacer cualquier personalización que quieras; sin embargo, user-customizations.sh no debe ser versionado.

Actualizar Homestead

Antes de comenzar a actualizar Homestead, asegúrate de eliminar tu máquina virtual actual ejecutando el siguiente comando en tu directorio de Homestead:

vagrant destroy

Después, debes actualizar el código fuente de Homestead. Si clonaste el repositorio puedes ejecutar los siguientes comandos en la ubicación donde clonaste originalmente el repositorio:

git fetch

git pull origin release

Estos comandos traen el código más reciente de Homestead del repositorio de GitHub, recuperan las últimas etiquetas y luego revisan la última versión etiquetada. Puedes encontrar la última versión de lanzamiento estable en la página de lanzamientos de GitHub.

Si realizaste la instalación de Homestead en tu proyecto por medio del archivo composer.json, debes asegurarte de que tu archivo composer.json contenga la dependencia "laravel/homestead": "^10" y después debes actualizar dichas dependencias:

composer update

Luego, debes actualizar el box de Vagrant usando el comando vagrant box update:

vagrant box update

Finalmente, debes regenerar tu box de Homestead para utilizar la última instalación de Vagrant:

vagrant up

Configuraciones específicas de proveedor

VirtualBox

natdnshostresolver

Por defecto, Homestead configura la opción natdnshostresolver como on. Esto permite a Homestead utilizar la configuración del DNS de tu sistema operativo. Si lo deseas, puedes sobrescribir este comportamiento, agregando las siguientes líneas al archivo Homestead.yaml:

provider: virtualbox
natdnshostresolver: 'off'

Enlaces simbólicos en Windows

Si los enlaces simbólicos no funcionan correctamente en equipos Windows, puede que requieras agregar el siguiente bloque a tu Vagrantfile:

config.vm.provider "virtualbox" do |v|
    v.customize ["setextradata", :id, "VBoxInternal2/SharedFoldersEnableSymlinksCreate/v-root", "1"]
end

Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.

Duilio Palacios

Publicado por:

Programador y profesor de PHP y Laravel. Creador de Styde.net.

Lección anterior Configuración - Documentación de Laravel 6 Lección siguiente Laravel Valet - Documentación de Laravel 6