Basic Project Scaffolding for Laravel 5, PHP, or HTML

As a freelancer I frequently work on a lot of new projects. It can become very tedious and time consuming to recreate the project structure for every new job, especially when the requirements really don't change that much. I decided to create a few open source repositories to speed up the process and help everyone else who has the same problem or just wants a good, solid place to start.

Versions

I have made 3 different repositories for different use cases. There is a repository for:

HTML Scaffolding

  • Basic HTML project scaffolding with Gulp, Bower, & LESS.
  • This is to be used for easy projects with static content that only require a simple HTML website.
  • Alternatively, it could be used for basic single-page JS apps.

PHP Scaffolding

  • Basic PHP project scaffolding with Composer, LESS, Gulp, & Bower.
  • Uses Composer to pull in PHP packages to build relatively simple PHP projects.
  • I use this for when I need to add Mailers or other simple things in a project.

Laravel 5 Scaffolding

  • Basic Laravel 5 project scaffolding with Gulp, Elixer, Bower, LESS, & Bootstrap.
  • This is the ultimate app scaffolding and takes away all the bad parts from the default Laravel 5 project structure.
  • It already includes Bootstrap and sets up a maintainable LESS structure.

Technology

These repositories use Gulp as their build system and Bower to fetch front-end frameworks, libraries, assets, etc. The Laravel repository extends Gulp with Laravel Elixer to make it a bit easier. PHP and Laravel projects also use Composer to pull in PHP packages.

My preferred CSS framework is Twitter Bootstrap but you could replace it with whatever you want. All the projects come with examples and comments.

Project Tree

The project tree is a little different for each project but it has some key principles. The most important one is the need to separate project files from vendor files. It's bad practice to alter vendor files, so instead they are imported and overriden with the help of LESS and Gulp. This will ensure if a component needs to be updated no drastic code changes will be necessary to accomodate for it. All vendor files from the different package systems are kept together when possible.

The general tree is as follows:

.
├── assets
|   ├── js
|   |   └── application.js
|   └── less
|       ├── application.less
|       ├── bootstrap.less
|       └── variables.less
├── public
|   └── assets
|       ├── css
|       ├── fonts
|       ├── images
|       └── js
└── vendor
    └── bower_components

Note: For HTML /vendor/bower_components is moved to /assets/vendor for easability since we have no other package systems, and for Laravel the /assets directory is moved to /resources/assets

Extending Bootstrap LESS Examples

The principals shown here can be used for any other framework you decide to use. We've just done it for Bootstrap automatically in the Laravel repository.

application.less

This is the core application file that imports everything and compiles to application.css.

// Vendor
@import 'bootstrap.less';

// Partials
@import 'partials/_component.less';

// Theme
@import 'theme.less';
bootstrap.less

Copies the vendor bootstrap.less file and updates the URLs to use our modified versions. If you need to make changes to any other Bootstrap files they should be imported and overridden the same way as variables.less.

// Core variables and mixins
@import "variables.less";
@import "../../../vendor/bower_components/bootstrap/less/mixins.less";

// Reset and dependencies
@import "../../../vendor/bower_components/bootstrap/less/normalize.less";
...
variables.less

Imports and overrides Bootstraps variables.less. This works because in LESS any variable you define with the same name will override the previous one, similar to how CSS works.

// Import
@import "../../../vendor/bower_components/bootstrap/less/variables.less";

// Override
@gray-base:              #222;
@brand-primary:          #ff00ff;
...

Conclusion

Give these repositories a try the next time you need to start a new project and let me know what you think in the comments or on Twitter. Feel free to submit a pull request on GitHub if you have any other best practices you'd like to share.

comments powered by Disqus