Checklist for setting up a new Laravel app
Recently, I wanted to start a new Laravel project. It had been a couple of months since the last one, and it took my brain a while to get into gear. Time is money, so for next time, this post is a basic checklist of the steps involved. I'm assuming familiarity with Laravel, PHP and the command line interface. If you're not familiar with Laravel and want to get started, I can recommend DevMarketer's YouTube playlist, How to build a blog with Laravel. I haven't done any collaborative projects with Laravel yet, so there might be additional steps for teams. I use WampServer, so there might be differences if you're using some other AMP stack. At time of writing, the current version of Laravel is 5.4.
Create new project
Set up your new project by navigating to the root file in your projects folder and running the following:
Set up database
Create a new database and set up a new user with a random name and password (if you're stuck, try random.org). Here are the commands for MySQL:
Add the database name, username and password to your
.env file. You'll need to repeat this process for your production site.
First model and migration
Set models and migrations up at the same time with this command:
Run first migration
Run your first migration(s). This will set up the authentication tables as well as whatever you created in the above step:
When I run my first migrations, I sometimes get error
1071 Specified key was too long. This is caused by my version of MySQL being out of date (must add to todo list!). The solution is to add this code to
It may take a few refreshes to get it working. See full solution: Laravel 5.4 Key Too Long Error.
To set up a controller with stubs for the seven basic resource methods (
destroy), run the following command:
I wrote about DRY resource controllers. To use this, create a new controller,
GenericResourceController, and copy-paste the sample code. Use this as the parent class for your app's controllers.
Quick reminder: to use a controller, assemble any data you need, then send to view:
Don't forget to include your model at the top, and you may need
Auth, too (see Set up auth), below:
To set up URLs for a new resource type, in
In a resource route, you can omit specific routes like so:
Just a quick reminder, individual routes need a name, and parameters are passed in through curly brackets, e.g.:
You can now output this route as a URL in views and controllers with the function
route('myResource.doMyThing'). The command for checking which routes are available in your app is:
For more on routes, including groups, middleware, regex constraints and so on, see Routing in the Laravel documentation.
Set up auth
Rather than writing your own HTML template from scratch, you can use the one that Laravel creates when you set up
auth. Using this template saves a bit of time, and it's easy enough to customise later. After you've run the command below, find the template at
When you've set up authentication, you can add the following function to controllers to make sure only logged-in users can access private areas:
Create a new view folder for your first resource type,
/resources/views/myresource, and your first Blade file for a view,
Just to get started, here's a basic template for Blade views:
NOTE: To get the page title to appear, add this to
Add HTML form helpers
You can skip this step if you want. Summary:
Next, add your new provider to the providers array of
Finally, add two class aliases to the aliases array of
To use the form helpers, you need to open a form in a view. You can use the
open() method for a new record:
You can use the
model() method to edit an existing record:
Read more at Forms & HTML on Laravel Collective.
Install Node packages
Before you start, you might want to make sure NPM is up to date:
And you might also need to update Node.js.
For your project, decide which packages you want to install. By default,
packages.json includes a lot of extras that you might not need. In particular,
laravel-mix causes problems for Windows because of the insane folder structure (see discussion at How to deploy Node.js application with deep node_modules structure on Windows?). Edit the list under
devDependencies as needed. You can always keep a backup or just comment out the ones you don't need.
When you're happy, install Node packages (this may take a while, so do something else while it's running in the background):
Sass and Bootstrap
If you've installed
bootstrap-sass via npm, go to
resources/assets/sass/app.scss, and update the Bootstrap section:
It may be that you want to customise Bootstrap, for example, by omitting the grid stuff (especially now that CSS Grid is on the rise). Editing
_bootstrap.scss directly in the
node_modules folder isn't a good idea because it could get accidentally overwritten. Instead, make a copy in
resources/assets/sass, adjust the file locations, and import this into your
app.scss. For example:
I hate these fragile relative filepaths. I tried adding a
$sass-bootstrap-filepath variable to tidy it up, but but it turns out you can't use Sass variables in an @import command. I'm sure there's a better way, so answers in the comments, please!
Add your custom CSS at the end of the file. I tend to prefer an ITCSS structure:
When you're happy with
app.scss, run Sass in a new CLI window:
Read more: Laravel and Bootstrap setup (July 2015)
I don't tend to use frontend build tools for JS, so I just add my project's JS scripts to
/public/js, then add a
<script> tag in
resources/layouts/app.blade.php. I may also add
public/js/app.js, which includes jQuery, Bootstrap, Vue.js, and a few other libraries. I try to be careful about forcing site users to download unnecessary crap, and at 285KB,
app.js is off-limits unless I'm really going to use all of it. If not, individual components can be downloaded separately.
Before your first commit, make sure you update
.gitignore. In addition to the default
.gitignore, you might also want to add:
/bootstrap/compiled.php /vendor /build/logs /build/coverage /app/tests/_log composer.phar composer.lock .DS_Store /.idea /.sass-cache /_ide_helper.php /app/config/packages /public/packages /node_modules .env
The guiding principles are to version control only those files which a developer is likely to touch, and to avoid committing anything that could jeopardise security or that's specific to your dev environment. The list of files to ignore includes Laravel's core files, third-party packages, database credentials, and other guff like logs and IDE indicies. Read more: Version controlling Laravel: Which files should I ignore? (August 2016) and .gitignore what should be ignored? (2015).
First commit and push
Some basic commands to get started. First, initialise the project:
Link to Git repo:
Add untracked files:
Final step: give yourself a doughnut. This post is mainly for my benefit, to improve my muscle memory, but I just thought it might be useful to somebody, somewhere. If you've got this far, I've no doubt you'll find there are other steps that I've missed. For example, I'm not particularly sophisticated when it comes to build tools like JS post-processors and image compressors, and I haven't built a Laravel app using a JS framework yet, although that's on my radar. If you feel I've missed anything really crucial, though, do leave a comment.Skip to navigation