Laravel 5 is already out, but the fear of change is taking everyone. We keep hearing people complaining about some radical changes. Like, why this new folder structure? Will my application break if I do a composer update
?
In this article, we’re going to look at how to migrate your existing Laravel 4 application to Laravel 5 and understand the new folder structure.
Installation
My existing Laravel 4 application is a demo from a previous article about using Google Analytics API. The application doesn’t have too much code, but it will do the job for our tutorial.
Let’s first install Laravel 5 on our computer and create a temporary folder to hold our Laravel 4 version of the application.
composer create-project laravel/laravel --prefer-dist
I prefer to install Laravel via composer, but you can visit the documentation to read more about the Laravel installer.
You can use the Vagrant box from the repository, or use Homestead Improved. If everything goes well, you should see the Laravel 5 welcome page.
Configuration Files
The old app/config
folder now lives under the root of your application, thus we have to move our app/config/analytics.php
to config/analytics.php
. The credentials are pasted directly to the file, so why not use environment variables.
// config/analytics.php
return [
'app_name' => env('app_name'),
'client_id' => env('client_id'),
'client_secret' => env('client_secret'),
'api_key' => env('api_key')
];
// .env
app_name='YOUR APP NAME'
client_id='YOUR CLIENT ID'
client_secret='CLIENT SECRET'
api_key='API KEY'
The .env
file is automatically loaded and can be used to separate your local environment configuration from production, tests, etc.
Routing
Laravel 4 routes are registered inside app/routes.php
. In Laravel 5, everything that is HTTP related is grouped under the app/Http
folder, including routes, so let’s move our app/routes.php
to app/Http/routes.php
.
Filters
Laravel 5 has moved from filters to middlewares, so if you have any filters inside your routes, make sure you change to middlewares.
Route::get(‘/report’, [‘middleware’ => ‘auth’, function()
{
//
}]);
If you have a custom filter, you can migrate it to be a middleware. I have a GoogleLogin
middleware that I’m using in my routes, the implementation will be like the following.
// app/Http/Middleware/GoogleLogin.php
class GoogleLogin
{
public function handle($request, Closure $next)
{
$ga = \App::make('\App\Services\GoogleLogin');
if (!$ga->isLoggedIn()) {
return redirect('login');
}
return $next($request);
}
}
// app/Http/Kernel.php
protected $routeMiddleware = [
'google_login' => 'App\Http\Middleware\GoogleLogin',
];
// app/Http/routes.php
Route::any('/search', ['middleware' => 'google_login', 'as' => 'search', 'uses' => 'GoogleController@search']);
The CRSF protection middleware is added by default. If you want to remove it, you can go to the app/Http/Kernel.php
file and comment out the proper line.
Controllers
Because our controllers are considered part of the Http logic, we need to move our app/controllers/*
to app/Http/Controllers
and namespace them with App\Http\Controllers
. One last problem you need to fix is to change the BaseController
to the Controller
class.
If you don’t like the App
root namespace, you can change it globally using the following artisan command.
php artisan app:name MyApp
Migrations
Our Google Analytics application doesn’t have any local database interactions, but the upgrade process is worth mentioning.
The app/database
directory now lives inside the /database
folder, and you only need to move your file there. The directory already contains a users
and a password_resets
table that you may want to delete or update depending on your needs.
Models
The models folder from Laravel 4 is gone, and Laravel 5 puts the User
model directly inside the app
folder as an example. You can copy your models in there too, and namespace them with App
.
However, if you don’t like the idea of having your models there, you can create a new folder under the app
directory called Models
, but don’t forget to namespace your classes with the App\Models
namespace.
namespace App\Models;
class User extends Eloquent {
…
}
Application Services
Our src
folder contains a GA_Service
and a GA_Utils
class. If we consider them to be services, we can put them inside app/Services
. Otherwise, we can create a new folder called app/GA
where we’re going to store our service classes. This will cause a problem since we didn’t use PSR-4 autoloading at first, so we need to update our class references inside the controller with the proper new namespace.
Views
The application views are moved from the app/views
folder to the resources/views
folder.
The resources
folder also contain the lang
folder for your application’s localization, and an assets
folder for your front-end assets. Laravel 5 introduced Elixir which adapts the Gulp task runner to the Laravel development environment.
Composer
Make sure you copy your application’s composer dependencies and do any necessary upgrades. For our demo, I’m going to move my "google/apiclient": "1.1.*"
to the new composer.json
and do a composer update
to reflect the changes.
Forms and HTML
The illuminate/html
package is removed from the default installation on Laravel 5 and you will need to install it separately.
To bring back the HTML helpers to your project, you need to add the "illuminate/html": "5.0.*"
package to your composer.json
and run composer update
, then you need to add the 'Illuminate\Html\HtmlServiceProvider'
to your config/app.php
providers array. If you would like to use the Html
and Form
facades inside your blade templates, you can append the following facades to your config/app.php
facades array.
// config/app.php
'aliases' => [
'Form'=> 'Illuminate\Html\FormFacade',
'HTML'=> 'Illuminate\Html\HtmlFacade',
],
Conclusion
The complexity and duration of the process of upgrading to Laravel 5 always depends on your application’s size, and maybe the process will be much longer than this example for your particular case. In this article, we tried to explain the common process which should take care of most if not all things that need changing.
You are not forced to upgrade to the new folder structure, and you can keep the old one and only update your composer dependencies, but this is not the recommended way of doing it. If you have any questions or comments, make sure to post them below. For more information, see the full version upgrade guide.