Working with Laravel projects and git

Stephan Köllen 22-02-2019

laravel configuration

The Laravel documentation does a very good job when it comes to installation and usage scenarios. There are some additional hurdles to jump when pulling a "WIP" project from git, mainly because some files and configuration don't belong inside version control.

With this short post I want to give a handy checklist you can use next time working on a version controlled Laravel project.

1. Clone the repository

First of all, you don't want a fresh Laravel installation. You want an app that is work in progress. So let's imagine you want to install your Laravel app on a new computer. We can clone the code base to our local machine.

git clone git@github:username/repository.git folder-name

Of course you need to provide the actual username and repository names. You can find the path to the repository at your github account where you are hosting your application code, when clicking the "Clone or Download" - Button.

folder-name will be the directory git clones the project into, so make sure you're cloning inside your webserver configured environment.

Now you should have a copy of the app on your local machine. Change the directory to your new Laravel app.

cd ~/path/to/your/app

Have a look in there (ls -la). Per default Laravel ships with sane .gitignore rules in order to prevent submitting sensitive data to git (and by that to the eyes of all possible collaborators). Some examples that are and should be ignored via the .gitignore file:

This is great and intended. Without these rules, we would have to submit all 3rd party libraries to version control.

What a mess, imagine all the updates etc.! Furthermore all collaborators would need to have the same credentials or overwrite them locally.

2. Get all vendors / composer dependencies

Luckily we have composer and can install our dependencies like so:

composer install

When creating a new project with the Laravel installer for example, this step happens "automatically". So you might have seen the installation of composer packages before if you already have installed Laravel.

Instead of versioning and sharing all packages via git, you can think of sharing a list of dependencies with composer.json where your dependencies are listed. The composer.lock file helps composer to use the exact version of packages and be consistent for every collaborator at the project.

3. Install your node modules

Similar to our composer installation, npm and our /node_modules process works like this:

npm install

You should get a new /node_modules folder in your project root that is usually populated with a lot of dependencies. The main package.json file lists your main dependencies for npm.

If the project is using Laravel Mix or some other tool to compile your assets to the public folder and your compiled files are ignored by git, you need to run npm run dev in order to get stylesheets, javascript etc. in place

4. Set your environment configuration

Now we have our dependencies in place but we need to provide configuration for our app, so let's create the environment file by copying .env.example.

This file is present in a fresh Laravel installation but should also be updated with needed configuration variables along the development process.

cp .env.example .env

Now you can examine the configuration file and set your credentials. Remember this file is (should be) ignored in .gitignore so that your sensitive data is not committed to version control. For the APP_KEY I'd suggest using the artisan command:

5. Generate your APP_KEY

In order to make your user sessions and other encrypted data secure, you should set your APP_KEY inside .env. We are doing this now, because with all composer dependencies installed (also Laravel) we can run an artisan command in order to generate our key:

php artisan key:generate

You should now see your key inside .env.

6. Migrate the database (maybe seed some example data)

Last but not least, one thing that is not versioned with git and therefore not on your machine yet, is the required database.

Laravel provides migration files, that are committed to version control, with a chronological order and the required database structure. This helps to "transfer" database (-structure) information.

After you created your local database for the project, add (if you have not already) your respective credentials to .env. You migrate the database with:

php artisan migrate

or, if the project provides some sample data for development, you can seed example data defined within the application seeder files with one command:

php artisan migrate --seed

With these steps you should hopefully get your cloned Laravel app running.

There might be some problems with a step itself, but this should provide a short overview. Of course there might be some additional requirements for your environment, branching etc., so keep that in mind, too.

Have a great day!