Getting started section. Work on 4.3 doc updates.

Sheby · Aug 21, 2014 · 51f5944 · 51f5944
1 parent 159f226
commit 51f5944
Show file tree

Hide file tree

Showing 9 changed files with 221 additions and 114 deletions.
diff --git a/configuration.md b/configuration.md
@@ -9,7 +9,7 @@
 <a name="introduction"></a>
 ## Introduction
 
-All of the configuration files for the Laravel framework are stored in the `app/config` directory. Each option in every file is documented, so feel free to look through the files and get familiar with the options available to you.
+All of the configuration files for the Laravel framework are stored in the `config` directory. Each option in every file is documented, so feel free to look through the files and get familiar with the options available to you.
 
 Sometimes you may need to access configuration values at run-time. You may do so using the `Config` class:
 
@@ -34,7 +34,7 @@ Configuration values that are set at run-time are only set for the current reque
 
 It is often helpful to have different configuration values based on the environment the application is running in. For example, you may wish to use a different cache driver on your local development machine than on the production server. It is easy to accomplish this using environment based configuration.
 
-Simply create a folder within the `config` directory that matches your environment name, such as `local`. Next, create the configuration files you wish to override and specify the options for that environment. For example, to override the cache driver for the local environment, you would create a `cache.php` file in `app/config/local` with the following content:
+Simply create a folder within the `config` directory that matches your environment name, such as `local`. Next, create the configuration files you wish to override and specify the options for that environment. For example, to override the cache driver for the local environment, you would create a `cache.php` file in `config/local` with the following content:
 
 	<?php
 
@@ -122,7 +122,7 @@ Now, on your production server, create a `.env.php` file in your project root th
 <a name="maintenance-mode"></a>
 ## Maintenance Mode
 
-When your application is in maintenance mode, a custom view will be displayed for all routes into your application. This makes it easy to "disable" your application while it is updating or when you are performing maintenance. A maintenamce mode check is included in the default `App::before` filter in `app/routing/filters.php`. The response from this check will be sent to users when your application is in maintenance mode.
+When your application is in maintenance mode, a custom view will be displayed for all routes into your application. This makes it easy to "disable" your application while it is updating or when you are performing maintenance. A maintenamce mode check is included in the default `App::before` filter in `app/Http/Filters/MaintenanceFilter.php`. The response from this check will be sent to users when your application is in maintenance mode.
 
 To enable maintenance mode, simply execute the `down` Artisan command:
 

diff --git a/controllers.md b/controllers.md
@@ -11,11 +11,15 @@
 
 Instead of defining all of your route-level logic in a single `routes.php` file, you may wish to organize this behavior using Controller classes. Controllers can group related route logic into a class, as well as take advantage of more advanced framework features such as automatic [dependency injection](/docs/ioc).
 
-Controllers are typically stored in the `app/controllers` directory, and this directory is registered in the `classmap` option of your `composer.json` file by default. However, controllers can technically live in any directory or any sub-directory. Route declarations are not dependent on the location of the controller class file on disk. So, as long as Composer knows how to autoload the controller class, it may be placed anywhere you wish.
+Controllers are typically stored in the `app/Http/Controllers` directory. However, controllers can technically live in any directory or any sub-directory. Route declarations are not dependent on the location of the controller class file on disk. So, as long as Composer knows how to autoload the controller class, it may be placed anywhere you wish.
 
 Here is an example of a basic controller class:
 
-	class UserController extends BaseController {
+	namespace App\Http\Controllers;
+
+	use View, App\User;
+
+	class UserController extends Controller {
 
 		/**
 		 * Show the profile for the given user.
@@ -24,32 +28,37 @@ Here is an example of a basic controller class:
 		{
 			$user = User::find($id);
 
-			return View::make('user.profile', array('user' => $user));
+			return View::make('user.profile', ['user' => $user]);
 		}
 
 	}
 
-All controllers should extend the `BaseController` class. The `BaseController` is also stored in the `app/controllers` directory, and may be used as a place to put shared controller logic. The `BaseController` extends the framework's `Controller` class. Now, we can route to this controller action like so:
+All controllers should extend the `Illuminate\Routing\Controller` class, which is aliased to `App\Http\Controllers\Controller` for convenience. Now, we can route to this controller action like so:
 
 	Route::get('user/{id}', 'UserController@showProfile');
 
-If you choose to nest or organize your controller using PHP namespaces, simply use the fully qualified class name when defining the route:
+It is very important to note that we did not need to specify the full controller namespace, only the portion of the class name that comes after the `App\Http\Controllers` namespace "root". Because of the call to the `namespaced` helper in your `App\Providers\RouteServiceProvider` class, this "root" namespace will automatically be prepended to all controller routes you register.
+
+If you choose to nest or organize your controllers using PHP namespaces deeper into the `App\Http\Controllers` directory, simply use the specify the class name relative to the `App\Http\Controllers` root namespace. So, if your full controller class is `App\Http\Controllers\Photos\AdminController`, you would register a route like so:
 
-	Route::get('foo', 'Namespace\FooController@method');
+	Route::get('foo', 'Photos\AdminController@method');
 
 > **Note:** Since we're using [Composer](http://getcomposer.org) to auto-load our PHP classes, controllers may live anywhere on the file system, as long as composer knows how to load them. The controller directory does not enforce any folder structure for your application. Routing to controllers is entirely de-coupled from the file system.
 
 You may also specify names on controller routes:
 
-	Route::get('foo', array('uses' => 'FooController@method',
-											'as' => 'name'));
+	Route::get('foo', ['uses' => 'FooController@method', 'as' => 'name']);
 
 To generate a URL to a controller action, you may use the `URL::action` method or the `action` helper method:
 
 	$url = URL::action('FooController@method');
 
 	$url = action('FooController@method');
 
+**Again**, you only need to specify the portion of the class that that comes after the `App\Http\Controllers` namespace "root". If you wish to generate a URL to a controller action while using the fully qualified class name, without the URL generator automatically preprending the default namespace, you may use a leading slash:
+
+	$url = action('\Namespace\FooController@method');
+
 You may access the name of the controller action being run using the `currentRouteAction` method:
 
 	$action = Route::currentRouteAction();
@@ -59,12 +68,11 @@ You may access the name of the controller action being run using the `currentRou
 
 [Filters](/docs/routing#route-filters) may be specified on controller routes similar to "regular" routes:
 
-	Route::get('profile', array('before' => 'auth',
-				'uses' => 'UserController@showProfile'));
+	Route::get('profile', ['before' => 'auth', 'uses' => 'UserController@showProfile']);
 
 However, you may also specify filters from within your controller:
 
-	class UserController extends BaseController {
+	class UserController extends Controller {
 
 		/**
 		 * Instantiate a new UserController instance.
@@ -83,7 +91,7 @@ However, you may also specify filters from within your controller:
 
 You may also specify controller filters inline using a Closure:
 
-	class UserController extends BaseController {
+	class UserController extends Controller {
 
 		/**
 		 * Instantiate a new UserController instance.
@@ -100,7 +108,7 @@ You may also specify controller filters inline using a Closure:
 
 If you would like to use another method on the controller as a filter, you may use `@` syntax to define the filter:
 
-	class UserController extends BaseController {
+	class UserController extends Controller {
 
 		/**
 		 * Instantiate a new UserController instance.
@@ -129,7 +137,7 @@ Laravel allows you to easily define a single route to handle every action in a c
 
 The `controller` method accepts two arguments. The first is the base URI the controller handles, while the second is the class name of the controller. Next, just add methods to your controller, prefixed with the HTTP verb they respond to:
 
-	class UserController extends BaseController {
+	class UserController extends Controller {
 
 		public function getIndex()
 		{
@@ -140,7 +148,7 @@ The `controller` method accepts two arguments. The first is the base URI the con
 		{
 			//
 		}
-		
+
 		public function anyLogin()
 		{
 			//
@@ -181,24 +189,18 @@ GET       | /resource/{resource}/edit   | edit         | resource.edit
 PUT/PATCH | /resource/{resource}        | update       | resource.update
 DELETE    | /resource/{resource}        | destroy      | resource.destroy
 
-Sometimes you may only need to handle a subset of the resource actions:
-
-	php artisan controller:make PhotoController --only=index,show
-
-	php artisan controller:make PhotoController --except=index
-
-And, you may also specify a subset of actions to handle on the route:
+Additionally, you may specify only a subset of actions to handle on the route:
 
 	Route::resource('photo', 'PhotoController',
-					array('only' => array('index', 'show')));
+					['only' => ['index', 'show']]);
 
 	Route::resource('photo', 'PhotoController',
-					array('except' => array('create', 'store', 'update', 'destroy')));
+					['except' => ['create', 'store', 'update', 'destroy']]);
 
 By default, all resource controller actions have a route name; however, you can override these names by passing a `names` array with your options:
 
 	Route::resource('photo', 'PhotoController',
-					array('names' => array('create' => 'photo.build')));
+					['names' => ['create' => 'photo.build']]);
 
 #### Handling Nested Resource Controllers
 
@@ -208,7 +210,7 @@ To "nest" resource controllers, use "dot" notation in your route declaration:
 
 This route will register a "nested" resource that may be accessed with URLs like the following: `photos/{photoResource}/comments/{commentResource}`.
 
-	class PhotoCommentController extends BaseController {
+	class PhotoCommentController extends Controller {
 
 		public function show($photoId, $commentId)
 		{

diff --git a/errors.md b/errors.md
@@ -9,7 +9,7 @@
 <a name="configuration"></a>
 ## Configuration
 
-The logging handler for your application is registered in the `app/start/global.php` [start file](/docs/lifecycle#start-files). By default, the logger is configured to use a single log file; however, you may customize this behavior as needed. Since Laravel uses the popular [Monolog](https://github.com/Seldaek/monolog) logging library, you can take advantage of the variety of handlers that Monolog offers.
+The logging handler for your application is registered in the `App\Providers\ErrorServiceProvider` [service provider](/docs/ioc#service-providers). By default, the logger is configured to use a single log file; however, you may customize this behavior as needed. Since Laravel uses the popular [Monolog](https://github.com/Seldaek/monolog) logging library, you can take advantage of the variety of handlers that Monolog offers.
 
 For example, if you wish to use daily log files instead of a single, large file, you can make the following change to your start file:
 
@@ -19,14 +19,14 @@ For example, if you wish to use daily log files instead of a single, large file,
 
 ### Error Detail
 
-By default, error detail is enabled for your application. This means that when an error occurs you will be shown an error page with a detailed stack trace and error message. You may turn off error details by setting the `debug` option in your `app/config/app.php` file to `false`.
+By default, error detail is enabled for your application. This means that when an error occurs you will be shown an error page with a detailed stack trace and error message. You may turn off error details by setting the `debug` option in your `config/app.php` file to `false`.
 
 > **Note:** It is strongly recommended that you turn off error detail in a production environment.
 
 <a name="handling-errors"></a>
 ## Handling Errors
 
-By default, the `app/start/global.php` file contains an error handler for all exceptions:
+By default, the `ErrorServiceProvider` class contains an error handler for all exceptions:
 
 	App::error(function(Exception $exception)
 	{
@@ -58,10 +58,6 @@ To listen for PHP fatal errors, you may use the `App::fatal` method:
 
 If you have several exception handlers, they should be defined from most generic to most specific. So, for example, a handler that handles all exceptions of type `Exception` should be defined before a custom exception type such as `Illuminate\Encryption\DecryptException`.
 
-### Where To Place Error Handlers
-
-There is no default "home" for error handler registrations. Laravel offers you freedom in this area. One option is to define the handlers in your `app/src/Providers/ErrorServiceProvider.php` file. In general, this is a convenient location to place any "bootstrapping" error handling code.
-
 <a name="http-exceptions"></a>
 ## HTTP Exceptions
 
@@ -88,7 +84,7 @@ You may register an error handler that handles all "404 Not Found" errors in you
 <a name="logging"></a>
 ## Logging
 
-The Laravel logging facilities provide a simple layer on top of the powerful [Monolog](http://github.com/seldaek/monolog) library. By default, Laravel is configured to create a single log file for your application, and this file is stored in `app/storage/logs/laravel.log`. You may write information to the log like so:
+The Laravel logging facilities provide a simple layer on top of the powerful [Monolog](http://github.com/seldaek/monolog) library. By default, Laravel is configured to create a single log file for your application, and this file is stored in `storage/logs/laravel.log`. You may write information to the log like so:
 
 	Log::info('This is some useful information.');
 

diff --git a/installation.md b/installation.md
@@ -49,15 +49,15 @@ As of PHP 5.5, some OS distributions may require you to manually install the PHP
 <a name="configuration"></a>
 ## Configuration
 
-Laravel needs almost no configuration out of the box. You are free to get started developing! However, you may wish to review the `app/config/app.php` file and its documentation. It contains several options such as `timezone` and `locale` that you may wish to change according to your application.
+Laravel needs almost no configuration out of the box. You are free to get started developing! However, you may wish to review the `config/app.php` file and its documentation. It contains several options such as `timezone` and `locale` that you may wish to change according to your application.
 
 Once Laravel is installed, you should also [configure your local environment](/docs/configuration#environment-configuration). This will allow you to receive detailed error messages when developing on your local machine. By default, detailed error reporting is disabled in your production configuration file.
 
 > **Note:** You should never have `app.debug` set to `true` for a production application. Never, ever do it.
 
 <a name="permissions"></a>
 ### Permissions
-Laravel may require one set of permissions to be configured: folders within `app/storage` require write access by the web server.
+Laravel may require one set of permissions to be configured: folders within `storage` require write access by the web server.
 
 <a name="paths"></a>
 ### Paths