Part of PHP’s success has been because it’s hard to find a web server that can’t serven PHP. However, modern PHP tools have stricter requirements than those of the past. The best way to develop Laravel is to ensure a consistent local and remote server environment for your code, and thankfully, the Laravel ecosystem has a few tools for this.
Table of Contents
System Requirements
All of the following is possible with Windows systems, but many pages of instructions
and caveats need to be made for Windows systems. As such, I’ll leave those caveats to
better-equipped writers online, and just focus on Unix/Linux/OS X developers.
Even with access to the command line and with the ability to install PHP and MySQL
and other tools locally, you’ll likely still run into version mismatches at some point or
another, and it’s highly recommended to do all of your local development on virtual
machines using a tool like Vagrant. Regardless of what tool you use, here are the minimum requirements for running Laravel 5.1:
Setting Up a Laravel Development Environment
Part of PHP’s success has been because it’s hard to find a web server that
can’t serve PHP. However, modern PHP tools have stricter requirements than those of the past.
The best way to develop Laravel is to ensure a consistent local and remote server
environment for your code, and thankfully, the Laravel ecosystem has a few tools for
this.
System Requirements
All of the following is possible with Windows systems, but many pages of instructions and caveats need to be made for Windows systems. As such, I’ll leave those caveats to better-equipped writers online, and just focus on Unix/Linux/OS X developers.
Even with access to the command line and with the ability to install PHP and MySQL and other tools locally, you’ll likely still run into version mismatches at some point or another, and it’s highly recommended to do all of your local development on virtual machines using a tool like Vagrant.
Regardless of what tool you use, here are the minimum requirements for running Laravel 5.1:
•PHP >= 5.5.9
•OpenSSL PHP Extension
•PDO PHP Extension
•Mbstring PHP Extension
•Tokenizer PHP Extension
Tools Composer
Whatever machine you’re developing on will need to have Composer installed globally. If you’re not familiar with Composer, it’s the foundation of most modern PHP development. Composer is a dependency manager for PHP, much like NPM for Node or Ruby Gems for Ruby. You’ll need Composer to install Laravel, update Laravel, and
bring in external dependencies.
Vagrant, VMWare, and VirtualBox
If you’re not familiar with Vagrant, it’s a configuration tool that sits on top of either VMWare
or Virtual Box and makes it easy to spin up virtual machines with predefined configurations. This means you can develop websites locally without having to even run a web server on your local machine, and you can ensure your server configuration is in close sync with your production environment.
Laravel Homestead
Laravel Homestead is another tool that sits on top of Vagrant and provides a pre-configured virtual machine image that is perfectly set up for Laravel development and mirrors the most common VPS server that many Laravel sites run on.
Setting up Homestead
If you’re new to Laravel development, getting started with VirtualBox, Vagrant, and
Homestead will give you the best development experience regardless of your own
computer’s configuration.
What tools does Homestead offer?
You can always upgrade your Homestead box, but here’s what it comes with by
default:
•Ubuntu
•PHP
•Nginx
•MySQL
•Postgres
•Redis
•Memcached
•Node
•Beanstalkd
Installing Homestead’s dependencies
First, you’ll need to download and install either VirtualBox or VMWare. VirtualBox is most common because it’s free. Next, download and install Vagrant.
Vagrant is convenient because it makes it easy for you to create a new local virtual machine from a pre-created “box”, which is essentially a template for a virtual machine. So the next step is to run
vagrant box adds laravel/homestead from the Terminal to download the box.
Example 2-1. Installing Homestead
git clone https://github.com/laravel/homestead.git ~/Homestead
Now, run the initialization script from wherever you put the
Homestead directory like in Example 2-2.
Example 2-2. Initializing Homestead bash ~/Homestead/init.sh This will place Homestead’s primary configuration file, Homestead.YAML, in a new ~/.homestead directory.
Configuring Homestead Open up Homestead.YAML and configure it how you’d like. You’ll need to tell it your
provider (likely VirtualBox), point it to your public SSH key (likely ~/.ssh/id_rsa.pub), map folders and sites to their local machine equivalents, and provision a database.
Mapping folders in Homestead allows you to edit files on your local machine and have those files show up in your Vagrant box so they can be served. For example, if you have a ~/Sites directory where you put all of your code, you would map the folders in Homestead like in Example 2-3.
Example 2-3. Mapping folders in Homestead.YAML
folders:
– map: ~/Sites
to: /home/vagrant/Sites
We’ve now just created a directory in your Homestead virtual machine at
/home/vagrant/Sites that will mirror your computer’s directory at ~/Sites.
Now, let’s set up our first example website. Let’s say our live site is going to be projectName.com. Let’s map our local development folder to the projectName.app, so we have a separate URL to visit for local development.
Example 2-4. Mapping sites in Homestead.yaml
sites:
– map: projectName.app
to: /home/vagrant/Sites/projectName/public
As you can see, we’re mapping the URL projectName.app to the virtual machine
directory /home/vagrant/Sites/projectName/public, which is the public folder within our Laravel install. We’ll learn more about that later.
Finally, we’re going to need to teach your local machine that, when you try to visit
projectName.app, it should look at your computer’s local IP Address to resolve it.
Mac and Linux users should edit /etc/hosts, Windows users C:\Windows\System32\drivers\etc\hosts. We’ll just add a line to this file that looks like
Example 2-5.
Example 2-5. Adding a local development site to your host’s file
192.168.10.10 projectName.app
Once we’ve provisioned Homestead, your site will be available to browse (on your
machine) at http://projectName.app/
Creating databases in Homestead Just like you can define a site in Homestead.YAML, you can also define a database. Databases are a lot simpler because you’re only telling the provisioner to create a database with that name, nothing else.
Example 2-6. Creating databases in Homestead.YAML
databases:-
project name
Provisioning Homestead
Since this is our first time actually turning on our Homestead box, we need to tell
Vagrant to initialize it. Navigate to your Homestead directory and run vagrant up:
Example 2-7. Provisioning a Homestead box
cd ~/Homestead
vagrant up
Your Homestead box is now up and running, it’s mirroring a local folder, and it’s
serving it to a URL you can visit in any browser on your computer. It also has added a
MySQL database. Now that you have that environment running, you’re ready to set
up your first Laravel project; but first, a quick note about using Homestead day-to-
day.
Using Homestead day-to-day
It’s common to leave your Homestead virtual machine up and running at all times,
but if you don’t, or if you have recently restarted your computer, you’ll need to know
how to spin the box up and down.
Since Homestead is based on Vagrant commands, you’ll just use basic Vagrant commands for most Homestead actions.
cd to the directory where you installed Homestead and then run the following commands:
• vagrant up spins up the Homestead box
• vagrant suspend takes a snapshot of where the box is and then shuts it down; like “hibernating” a desktop machine
• vagrant halt shuts the entire box down; like turning off a desktop machine
• vagrant destroy deletes the entire box; like formatting a desktop machine
• vagrant provision re-runs the provisioners on the preexisting box
Connecting to Homestead databases from desktop applications
If you use a desktop application like Sequel Pro, you’ll likely want to connect to your
Homestead MySQL databases from your host machine. These settings will get you
going:
•Connection Type:Standard (non-SSH)
•Host: 127.0.0.1
•Username:homestead
•Password: secret
•Port:33060
Creating a new Laravel project
There are two ways to create a new Laravel project, but both are run from the command line. The first is to globally install the Laravel installer tool (using Composer); the second is to use Composer’s create-project feature.
You can learn about both options in more detail at the Installation Documentation:
http://laravel.com/docs/installation
Installing Laravel with the Laravel installer tool
If you have Composer globally required, installing the Laravel installer tool is as simple as running the following command:
Example 2-8. Installing the Laravel installer tool
composer global require “laravel/installer=~1.1”
Once you have the Laravel installer tool installed, spinning up a new Laravel project
is simple. Just run laravel new ProjectName from your command line.
Example 2-9. Creating a new Laravel project using the installer tool laravel new projectName
This will create a new subdirectory of your current directory named projectName and install a bare Laravel project in it.
Installing Laravel with Composer’s create-project feature
The composer also offers a feature called create-project for creating new projects with the particular skeleton. To use this tool to create a new Laravel project, issue the command shown in Example 2-10.
Example 2-10. Creating a new Laravel project using the installer tool composer create-project laravel/laravel projectName –prefer-dist
Just like the installer tool, this will create a subdirectory of your current directory
named projectName that contains a skeleton Laravel install, ready for you to develop.
Laravel’s Directory structure
When you open up a directory that contains a skeleton Laravel application, you’ll see
the following files and directories
Installing Laravel with Composer’s
create-project
feature
The composer also offers a feature called
create-project
for creating new projects with
a particular skeleton. To use this tool to create a new Laravel project, issue the com‐mand showed in Example 2-10
.
Example 2-10. Creating a new Laravel project using the installer tool
composer create-project laravel/laravel projectName –prefer-dist
Just like the installer tool, this will create a subdirectory of your current directory
named
projectName
that contains a skeleton Laravel install, ready for you to develop.
Laravel’s Directory structure
When you open up a directory that contains a skeleton Laravel application, you’ll see
the following files and directories:
app
bootstrap
config
database
public
resources
storage
tests
vendor
.env
.env.example
.gitattributes
.gitignore
artisan
composer.json
composer. lock
gulpfile.js
package.json
phpspec.yml
phpunit.xml
readme. MD
server.php
Let’s walk through them one-by-one to get familiar.
The loose files
.env and .env.example is the files that dictate the environment variables, variables which are expected to be different in each environment and are therefore not committed to version control. .env. an example is a template that each environment should duplicate to create its own .env file, which is Git ignored.
artisan is the file that allows you to run Artisan commands from the command line.
.gitignore and .gitattributes are Git configuration files.
composer.json and composer. lock are the configuration files for Composer;
composer.json is user-editable and composer. a lock is not. These files share some basic information about this project and also define its PHP dependencies.
gulpfile.js is the (optional) configuration file for Elixir and gulp. This is for managing your front-end assets.
package.json is like composer.json but for frontend assets.
phpspec.yml and phpunit.xml are configuration files for testing tools.
readme. MD is a Markdown file giving a basic introduction to Laravel.
server.php is a backup server that tries to allow less-capable servers to still preview the Laravel application.
The folders app is where the bulk of your actual application will go. Models, controllers, route definitions, commands, and your PHP domain code all go in here.
bootstrap contains the files that the Laravel framework solutions uses to boot every time it
runs.
config is where all configuration files live.
the database is where database migrations and seeds live.
the public is the directory the server points to when it’s serving the website. This contains
index.php, which is the front controller that kicks off the bootstrapping process and routes all requests appropriately. It’s also where any public-facing files like images, stylesheets, scripts, or downloads go.
resources are where non PHP files that are needed for other scripts live. Views, language files, and (optionally) Sass/LESS and source JavaScript files live here.
storage is where caches, logs, and compiled system files live.
tests are where unit and integration tests live.
the vendor is where Composer installs its dependencies. It’s Git ignored, as Composer is expected to run as a part of your deployment process on the remote server.
Up and Running
You’re now up and running with a bare Laravel install. Run git init, commit the bare files, and you’re ready to start coding.
