Write 4->5 upgrade guide.

upgrade.md

@@ -9,12 +9,241 @@
 <a name="upgrade-5.0"></a>
 ## Upgrading To 5.0 From 4.2
 
-Information coming soon.
+### Fresh Install, Then Migrate
+
+The recommended method of upgrading is to create a new Laravel `5.0` install and then to copy your `4.2` site's unique application files--controllers, routes, commands, assets, and domain code--into it.
+
+To start, [install a new Laravel 5 application](/docs/master/installation) into a fresh directory in your local environment.
+
+The remaining steps are to find all of the application-specific code from your `4.2` site and move it to your `5.0` site.
+
+### PSR-4 namespace
+
+If you already have a top-level PSR-0/4 namespace set up, or if you intend to set one up, use `artisan app:name` to set an [application namespace](/docs/master/structure#namespacing-your-application):
+
+```bash
+php artisan app:name SocialNet
+```
+
+> **Note**: This upgrade guide will reference the `App` namespace in any directions; if you've already set `app:name`, replace `App` in the examples with your own app's namespace instead.
+
+Laravel 5's `app:name` namespacing presumes that the top level of your application's domain code will be the `app` folder. So, if you had a folder in your `4.2` application that was mapped to your PSR-0/4 namespace (e.g. an `app/SocialNet` folder that was mapped to the `SocialNet` namespace), move all of its folders and files to the `app` folder.
+
+### Composer dependencies
+
+Copy your `4.2` app's `composer.json` dependencies into the `5.0` app's composer.json (or require them one-by-one with `composer require`).
+
+Now, run `composer update`.
+
+### Artisan Commands
+
+Move all of your command classes from `4.2`'s `app/commands` directory to `5.0`'s `app/Console/Commands`.
+
+Either [namespace your commands](#namespace-artisan-commands), or add the `app/Console/Commands` directory to the `composer.json` classmap autoloader.
+
+Copy your list of artisan commands from `start/artisan.php` into `app/Console/Kernel.php`'s `$commands` array.
+
+### Controllers
+
+Move all of your controller classes from `4.2`'s' `app/controllers` directory to `5.0`'s `app/Http/Controllers`.
+
+Either [namespace your controllers](#namespace-controllers) or remove the namespace from the abstract `app/Http/Controllers/Controller.php`, add the `app/Http/Controllers` directory to the `composer.json` classmap autoloader, and update `app/Providers/RouteServiceProvider.php`'s `$namespace` property to `null`.
+
+### Database Migrations & Seeds
+
+Move all of your migration classes from `4.2`'s `app/database/migrations` directory to `5.0`'s `database/migrations` and all of your seed classes from `app/database/seeds` to `database/seeds`.
+
+Delete the `2014_10_12_00000_create_users_table` migration, since you should already have the users table in your database.
+
+### Filters
+
+Copy your filter bindings from `app/filters.php` and place them into the `boot()` method of `app/Providers/RouteServiceProvider.php`. Add `use Illuminate\Support\Facades\Route;` in `app/Providers/RouteServiceProvider.php` in order to continue using the `Route` Facade.
+
+You don't need to move over any of the filters that come in by default; they're all here, but now as Middleware. Edit any routes in `routes.php` that call the native Laravel filters (e.g. `['before' => 'auth']`) and change them to reference them as middleware (e.g. `['middleware' => 'auth'].`) You can still bind your own custom filters using `before` and `after`.
+
+### Language files
+
+Move your language files from `4.2`'s `app/lang` directory to `5.0`'s `resources/lang`.
+
+### Models
+
+If your `4.2` application relies on the `app/models` folder for autoloading, create an `app/models` directory in the `5.0` install and add it to `composer.json`'s classmap autoloader.
+
+Note that the `User.php` that comes with Laravel 5 lives in the `app` directory, which means it's namespaced `app\User`.
+
+Update any models using the `SoftDeletingTrait` to use `SoftDeletes`.
+
+### Routes
+
+Move `app/routes.php` to `app/Http/routes.php`.
+
+### Global bindings
+
+If you have any bindings in `start/global.php`, start by moving them all to the `register()` method of `App\Providers\AppServiceProvider`. However, the best practice is to perform bindings in Service Providers specific to the context that is being bound for.
+
+### Tests
+
+Move your tests from `4.2`'s `app/tests` directory to `5.0`'s `tests`.
+
+### Views
+
+Move your views from `4.2`'s `app/views` directory to `5.0`'s `resources/views`.
+
+### Namespacing controllers and commands
+
+<a name="namespace-controllers"></a>
+#### Namespacing controllers
+
+If your controllers weren't namespaced in your `4.2` codebase, you can either bring them in with no namespace, or add namespaces to them.
+
+If you want to add namespaces, edit each controller and add `App\Http\Controllers` as its namespace.
+
+If you want to go without, edit `app/Providers/RouteServiceProvider.php` and set its `$namespace` property equal to `null`. Then edit the `map()` method in that same file to be *just* this line (replace the entire `$this->loadRoutesFrom` line):
+
+```php
+ include app_path('Http/routes.php');
+```
+
+Finally, add the controllers directory to `composer.json`'s classmap autoloader. 
+
+> **Note**: If you namespace your controllers, **all of your internal facade calls will fail**; facades are imported at the top of the namespace. If you see something like `Class 'App\Http\Controllers\Auth' not found.`, you need to either `use Auth`, `use Session`, etc. at the top of the controller, or prepend `\` to each inline facade use (e.g. convert `Session::flash('stuff', 'other stuff');` to `\Session::flash('stuff', 'other stuff');`.)
+
+<a name="namespace-artisan-commands"></a>
+#### Namespacing Artisan commands
+
+Just like controllers, you can either namespace all of your imported commands so they're autoloaded by PSR-4, or you can add the `app/Console/Commands` directory to `composer.json`'s classmap autoloader.
+
+### Configuration
+
+### Migrating environment-specific files
+
+Copy the new `5.0` `.env.example` file `.env`, which is the `5.0` equivalent of `.env.php`. Set any appropriate values there, like your `APP_ENV` (the environment name--for example, "local" or "production"), `APP_KEY` (your encryption key), your database credentials, and your cache and session drivers.
+
+Additionally, copy any custom values you had in your `4.2`'s `.env.php` file and place them in both `.env` (the real value) and `.env.example` (a sample instructional value).
+
+### Config files
+
+Laravel 5.0 no longer uses `app/config/environmentName/` directories to provide specific configuration files for the given environment. Instead, move any configuration values that vary by environment into `.env`, and then access them in your configuration files using `env('keyNameHere', 'default fallback value here')`.
+
+Set the config files in the `config/` directory to represent either the values that are consistent across all of your environments, or set them to use `env()` to load varying values. If you add more keys to `.env` to account for this, remember to add them to `.env.example` as well.
+
+### Auth & Users
+
+Either delete your old `Auth` model and just use the new one (the easiest option), or follow these instructions:
+
+**Delete the following from your `use` block:**
+```php
+use Illuminate\Auth\UserInterface;
+use Illuminate\Auth\Reminders\RemindableInterface;
+```
+
+**Add the following to your `use` block:**
+```php
+use Illuminate\Auth\Authenticatable;
+use Illuminate\Auth\Passwords\CanResetPassword;
+use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
+use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;
+```
+
+**Remove the UserInterface and RemindableInterface interfaces**
+
+**Mark it as implementing the following interfaces:**
+```php
+implements AuthenticatableContract, CanResetPasswordContract
+```
+
+**Include the following *within the class declaration, to use them as traits*:**
+```php
+use Authenticatable, CanResetPassword;
+```
+
+Either change the namespace of your `User` model to your app namespace, or change the `"model"` property in `config/auth.php` to the correct namespace (e.g. `User` instead of `SocialNet\User`).
+
+Finally, if you're using your own User model, you can delete `app/user.php`.
+
+### Bootstrap directory
+
+If you’ve made any customizations to files in the `bootstrap` directory—and if you made any, it was likely only `start.php`—you’ll want to move them over. Note that `detectEnvironment` behaves differently in Laravel 5--an application's current environment string is now entirely defined by the `APP_ENV` value of the `.env` file.
+
+### Public directory
+
+Copy your `4.2` application's public assets from the `4.2` `public` directory to the `5.0` `public` directory. Be sure to keep the `5.0` version of `index.php`.
+
+### Loose files
+
+Copy in any loose files in your project--for example, `.scrutinizer.yml` or `bower.json` in the top level, or your Sass or Less directories, or anything else--into your new application at the appropriate location.
+
+### Form & HTML Helpers
+
+If you're using Form or Html helpers, you'll see an error stating `class 'Form' not found` or `class 'Html' not found`. To fix this, `composer require` `"illuminate/html": "~5.0"`.
+
+You'll also need to get the Form and Html Facades and Service Srovider working. Edit `config/app.php`, and add this line to the 'providers' array:
+
+```php
+ 'Illuminate\Html\HtmlServiceProvider',
+```
+
+And add these lines to the 'aliases' array:
+
+```php
+ 'Form' => 'Illuminate\Html\FormFacade',
+ 'Html' => 'Illuminate\Html\HtmlFacade',
+```
+
+### Change Blade tags
+
+The best way to handle the changes to Blade's tags is to search through anywhere in your site you *know* you need to allow HTML (for example, if you're using HTML or Form helpers) and replace `{{` with `{!!` and `}}` with `!!}`. Otherwise, allow Laravel to auto-escape all of your output by default.
+
+However, if for some reason you *need* to use the old Blade syntax, you can define that. Just add the following lines at the bottom of `AppServiceProvider@register()`:
+
+```php
+ \Blade::setRawTags('{{', '}}');
+ \Blade::setContentTags('{{{', '}}}');
+ \Blade::setEscapedContentTags('{{{', '}}}');
+```
+
+Note that if you change the raw tags this way, your comments with `{{--` will no longer work.
 
 ### Beanstalk Queuing
 
 Laravel 5.0 now requires `"pda/pheanstalk": "~3.0"` instead of `"pda/pheanstalk": "~2.1"` that Laravel 4.2 required.
 
+### Global CSRF
+
+By default, [CSRF protection](/docs/routing#csrf-protection) is enabled on all routes. If you'd like to disable this, or only manually enable it on certain routes, remove this line from `App\Http\Kernel`'s `$middleware` array:
+
+```php
+ 'Illuminate\Foundation\Http\Middleware\VerifyCsrfToken',
+```
+
+If you want to use it elsewhere, add this line to `$routeMiddleware`:
+
+```php
+ 'csrf' => 'Illuminate\Foundation\Http\Middleware\VerifyCsrfToken',
+```
+
+Now you can [add this to any route](/docs/master/middleware#registering-middleware) using `['middleware' => 'csrf']` on the route.
+
+### CacheManager
+
+If your application code was injecting `Illuminate\Cache\CacheManager` to get a non-facade version of Laravel's cache, change it to inject `Illuminate\Cache\Repository`.
+
+### Eloquent caching through `remember()` no longer available
+
+Eloquent no longer provides the `remember()` method for caching queries. You now are responsible for caching your queries manually.
+
+### Pagination
+
+Replace any calls to `$paginator->links()` with `$paginator->render()`.
+
+### Remote
+
+The Remote component has been deprecated.
+
+### Workbench
+
+The Workbench component has been deprecated.
+
 <a name="upgrade-4.2"></a>
 ## Upgrading To 4.2 From 4.1