Overview of PHP Development Environments

Laravel is built on PHP and can run on any compatible PHP environment. While popular all-in-one solutions like WAMP, MAMP, and phpStudy work well, the Laravel team officially recommends two development environments for better compatibility and smoother deployment workflows: Homestead and Valet. Homestead supports Windows and macOS, while Valet is exclusively designed for macOS users. This guide focuses on configuring the Homestead environment.

Understanding Laravel Homestead

Laravel Homestead is an official pre-packaged Vagrant box that provides a complete development environment. The key advantage is that you don't need to install PHP, web servers, or other server software directly on your machine. Since Vagrant boxes are disposable, any configuration issues can be resolved by destroying and recreating the box within minutes.

Homestead runs on Windows, macOS, or Linux and includes:

• Nginx web server
• PHP 7.4, 7.3, 7.2, 7.1
• MySQL and PostgreSQL databases
• Redis and Memcached
• Node.js and additional development tools

Prerequisites Installation

Installing Git

Download Git from the official repository. Choose the appropriate version for you're system architecture (32-bit or 64-bit). Complete the installation and keep the default settings.

Installing VirtualBox

VirtualBox is Oracle's open-source virtualization software that provides excellent performence and feature completeness. It supports major operating systems including macOS, Windows, and Linux.

Download VirtualBox 6.x from the official downloads page and install it using the standard Windows installer package.

Installing Vagrant

Vagrant is a tool for managing virtual machines that supports VirtualBox, VMware, AWS, and other virtualization platforms. It provides configurable, portable, and reproducible software environments through a Vagrantfile configuration. In team projects, sharing the Vagrantfile ensures all developers work with identical environments.

Installing the Homestead Box

Method 1: Online Installation (Not Recommended)

Execute the following command in Git Bash:

vagrant box add laravel/homestead

Select VirtualBox when prompted. This method often experiences slow download speeds and frequent failures.

Method 2: Local File Installation (Recommended)

Download the offline homestead.box file (approximately 1.25 GB) from the official source. Place the file in a local directory such as G:/homestead/.

Run the following command to add the box locally:

vagrant box add laravel/homestead g:/homestead.box

Wait for the installation to complete. A success message will appear upon completion.

Setting Up Homestead Management Scripts

Clone the Homestead repository to your home directory:

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

Initialize the configuration files:

./init.bat

For locally installed boxes with version 0, modify /Homestead/scripts/homestead.rb to update the version constraint:

config.vm.box_version = settings["version"] || ">= 0"

Configuring Synchronized Folders

Edit the Homestead.yaml file in the ~/Homestead directory to configure folder synchronization between your host machine and the virtual environment:

folders:
    - map: ~/projects/app1
      to: /home/vagrant/app1
    - map: ~/projects/app2
      to: /home/vagrant/app2

This configuration maps local directories to the virtual machine, allowing you to edit code locally while running it in the VM.

Important: Do not map directly to the vagrant root directory. The mapping must target a subdirectory within /home/vagrant/ for synchronization to work correctly.

Configuring SSH Key Authentication

Generate an SSH key pair for passwordless authentication:

ssh-keygen -t rsa -C "developer@example.com"

Press Enter to accept default settings and optionally set a passphrase. Update the Homestead.yaml configuration:

keys:
    - ~/.ssh/id_rsa
    - ~/.ssh/id_rsa.pub

Database Connection Configuration

Homestead comes pre-configured with MySQL and PostgreSQL. Connect from your host machine using these default credentials and ports:

• MySQL: Host 127.0.0.1, Port 33060, User homestead, Password secret
• PostgreSQL: Host 127.0.0.1, Port 54320, User homestead, Password secret

When connecting from Laravel running inside the VM, use standard ports 3306 and 5432 instead.

Configuring Sites and Domains

Add multiple Laravel applications to your Homestead environment by configuring sites in Homestead.yaml:

sites:
    - map: myapp.test
      to: /home/vagrant/app1/public
    - map: secondapp.test
      to: /home/vagrant/app2/public

Update your system's hosts file with the following entries:

192.168.10.10  myapp.test
192.168.10.10  secondapp.test

Setting Up Global Commands

To run Vagrant commands from any directory in Git Bash, add this function to your ~/.bash_profile:

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

Essential Vagrant Commands

Start the virtual machine:

cd ~/Homestead && vagrant up

Reload after configuration changes:

vagrant reload --provision

Shutdown the machine:

vagrant halt

Connect via SSH:

vagrant ssh

List installed boxes:

vagrant box list

Remove a box:

vagrant box remove laravel/homestead

Remove specific version:

vagrant box remove laravel/homestead --box-version 6.4.0

Check VM status:

vagrant status

With these configurations in place, your Homestead environment is ready for Laravel development.