Laravel is currently my PHP framework of choice (in case you couldn't tell) that I look to when building applications. This will most likely change sometime in the future, but it is a fair bet at this moment in time. I know there are numerous articles out there on the best setup and architecture for Laravel applications, and at times there can be differing opinions.
Well in this article, all opinions aside, is how I setup my new Laravel projects. It is fair to note that this also includes Bower and Gulp support.
Note: This assumes that you are cloning and setting up an existing project. If you are attempting to create a new Laravel 5 project, refer to Laravel's documentation. This also assumes that you know how to setup a mySQL or pgSQL database.
Requirements
Below are the necessary packages and commands to install Laravel.
Composer
Composer is a package manager for PHP applications; much like that of PIP for Python and RubyGems for Ruby on Rails. Laravel requires Composer to pull down all of its packages to make the application run. If you do not have Composer installed, use the following steps below.
Install Composer
Assuming you have CURL installed on your computer, open up the terminal command line and enter the following command:
curl -sS https://getcomposer.org/installer | php
This will pull down the installer and install it on your machine. However, this will not install it globably. Meaning you will not be able to access/manage this Composer installation from anywhere on your machine. While this next step is not required, it is highly recommended. To make Composer a global command, enter this command:
mv composer.phar /usr/local/bin/composer
Using Composer
Once Composer is installed, you will now be able to use the composer command(s) anywhere. If you enter the command without any additional attributes, Composer will show all of the available commands/actions you can perform. The majority of commands that you will be using are as follows:
composer installcomposer updatecomposer dump-autoloadcomposer require [developer/package-name]
Refer to the Composer documentation for any additional commands.
NOTE: If you choose to not install Composer globally, the curl command that is above will install Composer in the directory where the command prompt was active before the installation. In doing so requires you to enter php composer.phar before each composer command.
Install packages
Now that Composer is installed, we can now install all of the project dependencies using the install command:
composer install
This may take a little bit to complete.
Front-end assets
All of the Laravel projects that are managed at S|O utilize Bower for front-end asset management and Laravel's Elixer package to compile all of these assets. To install all of the Bower components type:
bower install
If Bower is not installed, refer to this link for the steps to download/install Bower.
Finally in order for Laravel to use these assets we need to install install Elixer. To do so, simply enter:
npm install
Gulp
IMPORTANT: Laravel's Elixer utilizes Gulp for it's task management. If you do not have Gulp installed, enter the following command: npm install --global gulp.
Once all of the node modules have been installed, we need for Gulp to build all of our front-end dependencies so Laravel can use them. You can use one of three commands to do this. They are essentially the same thing, but the final two commands provide additional functionality if desired.
To just simply compile all of the assets, enter the following command:
gulp
If this is a fresh install, this may take a little bit to complete. If you are changing Javascript or SASS and want the application to update your changes, enter this command:
gulp watch
This tells Gulp to watch the contents of the resources folder and updates them whenever a change is detected. Lastly there is a command that should only be used in staging/production environments. That is:
gulp --production
This not only builds all of the assets but also minifies them as well. Due to the minification, this command may take a little bit to complete depending on the type of machine/server you are developing on.
The .env file
Now that the Laravel project has been installed, we need to set up the settings and preferences for this project. If we were to try to view this project by running a server or using MAMP, the project would not run. This is due to some folder permissions and the lack of the ".env file."
This file stores environment variables that are specific to this installation that you are setting up. This allows us to change Laravel's configuration without making changes to the files that are tracked within the repository.
Each Laravel-based repository comes with a .env.example file within the repository, however Laravel will not be able to find it. For the sake of keeping the repository intact, do not simply rename this file, but duplicate and rename it like so:
scp .env.example .env
Once complete, either use your terminal (vim or nano) or your IDE of choice to open up the file. It should look something like this:
APP_ENV=local
APP_DEBUG=true
APP_KEY=SomeRandomString
DB_HOST=localhost
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_DRIVER=sync
MAIL_DRIVER=smtp
MAIL_HOST=mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
NOTE: Depending on the project, the .env file may look a little different. Refer to that project's documenation for additional notes.
For right now, we will ignore all of the variables except for the DB_ prefixed variables.
Chances are the DB_HOST variable will not need to be changed if you are using a "typical" local development environment. Change the DB_DATABASE to the name of the database that you have set up locally, as well as set the DB_USERNAME and DB_PASSWORD with the database server's username and password respectively.
PostgreSQL setups
If you prefer to use pgSQL as your database driver, there is one more database variable that you will need to add/set. Add the following line to your .env file to change the default setting from mySQL to pgSQL:
DB_CONNECTION=pgsql
Set Application Key
Laravel uses a hashing key to encrypt all of the passwords and form data that are used within the database and requests from the framework to the page. This helps ensure security. While there are websites out there that provided randomly generated keys, Laravel provides a method as well. Simply enter the following command to have Laravel set the new key:
php artisan key:generate
Artisan
Laravel uses a library of CLI commands named Artisan to help configure and manipulate the application. To see all of these commands, simply enter php artisan to see the list.
NOTE: You must be within the application's root directory for this to work.
Migrations
Assuming the application uses a local database for its database storage (if you are developing for Parse or Firebase, you may not require one), we will need to create all of the necessary tables and columns within the respective tables. To do this simply enter the following command:
php artisan migrate
Assuming all of the migrations were completed without error, you should see a success message in your terminal. If not, debug as necessary.
Seeding
If you are not importing an existing database with data, we will need to seed the database with some data to aid in development. This could include some users, blog posts, etc. To do so, enter:
php artisan db:seed
NOTE: Database seeding is NOT required for each project. It can vary from application to application. Refer to the database/seeds/DatabaseSeeder.php file for more information. If you do not see any classes listed within the file, database seeding is not used for this project.
Folder permissions
Before we can serve any of the views within the application, we need to make sure that certain directories can be written to by the server. To do so, enter the following command:
sudo chmod -R 777 storage boostrap/cache
Server
NOTE: If you are using a VM such as MAMP, skip this step.
Now that everything is installed and configured, we need for Laravel to serve the application. Laravel comes with its own lightweight Apache server that can be accessed with Artisan like so:
php artisan serve
The nice thing about this is that does provide server errors that you may not see otherwise without looking at your machines PHP error logs.
Finish
Assuming that everything was completed without any issues, you should be able to see the applications homepage when you navigate to the localhost url provided by your server.