From 7d1102dd6e8db21b5203a9e05751d02a58977fd1 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Mon, 21 May 2012 10:48:15 -0500 Subject: [PATCH 1/6] Updated authentication offline docs. --- laravel/documentation/auth/config.md | 54 ++++++++++------------------ laravel/documentation/auth/usage.md | 12 +++---- 2 files changed, 22 insertions(+), 44 deletions(-) diff --git a/laravel/documentation/auth/config.md b/laravel/documentation/auth/config.md index dbeed52d..a1609320 100644 --- a/laravel/documentation/auth/config.md +++ b/laravel/documentation/auth/config.md @@ -3,54 +3,36 @@ ## Contents - [The Basics](#the-basics) -- [The User Function](#user) -- [The Attempt Function](#attempt) -- [The Logout Function](#logout) +- [The Authentication Driver](#driver) +- [The Default "Username"](#username) +- [Authentication Model](#model) +- [Authentication Table](#table) ## The Basics Most interactive applications have the ability for users to login and logout. Laravel provides a simple class to help you validate user credentials and retrieve information about the current user of your application. -To get started, let's look over the **application/config/auth.php** file. The authentication configuration contains three functions: **user**, **attempt**, and **logout**. Let's go over each one individually. +To get started, let's look over the **application/config/auth.php** file. The authentication configuration contains some basic options to help you get started with authentication. - -## The "User" Function + +## The Authentication Driver -The **user** function is called when Laravel needs to retrieve the currently logged in user of your application. When a user logs into your application, Laravel stores the ID of that user in the [session](/docs/session/config). So, on subsequent requests, we can use the ID stored in the session to retrieve the user's information from storage. However, applications use various data stores. For this reason, you are given complete flexibility regarding how to retrieve the user. +Laravel's authentication is driver based, meaning the responsibility for retrieving users during authentication is delegated to various "drivers". Two are included out of the box: Eloquent and Fluent, but you are free to write your own drivers if needed! -Of course, a simple default configuration has been setup for you. Let's take a look: +The **Eloquent** driver uses the Eloquent ORM to load the users of your application, and is the default authentication driver. The **Fluent** driver uses the fluent query builder to load your users. - 'user' => function($id) - { - if ( ! is_null($id) and filter_var($id, FILTER_VALIDATE_INT) !== false) - { - return DB::table('users')->find($id); - } - } + +## The Default "Username" -As you probably noticed, the user's ID is passed to the function. The default configuration utilizes the [fluent query builder](/docs/database/fluent) to retrieve and return the user from the database. Of course, you are free to use other methods of retrieving the user. If no user is found in storage for the given ID, the function should simply return **null**. +The second option in the configuration file determines the default "username" of your users. This will typically correspond to a database column in your "users" table, and will usually be "email" or "username". - -## The "Attempt" Function + +## Authentication Model -Anytime you need to validate the credentials of a user, the **attempt** function is called. When attempting to authenticate a user, you will typically retrieve the user out of storage, and check the hashed password against the given password. However, since applications may use various methods of hashing or even third-party login providers, you are free to implement the authentication however you wish. Again, a simple and sensible default has been provided: +When using the **Eloquent** authentication driver, this option determines the Eloquent model that should be used when loading users. - 'attempt' => function($username, $password) - { - $user = DB::table('users')->where_username($username)->first(); + +## Authentication Table - if ( ! is_null($user) and Hash::check($password, $user->password)) - { - return $user; - } - } - -Like the previous example, the fluent query builder is used to retrieve the user out of the database by the given username. If the user is found, the given password is hashed and compared against the hashed password stored on the table, and if the passwords match, the user model is returned. If the credentials are invalid or the user does not exist, **null** should be returned. - -> **Note:** Any object may be returned by this function as long as it has an **id** property. - - -## The "Logout" Function - -The **logout** function is called whenever a user is logged out of your application. This function gives you a convenient location to interact with any third-party authentication providers you may be using. \ No newline at end of file +When using the **Fluent** authentication drivers, this option determines the database table containing the users of your application. \ No newline at end of file diff --git a/laravel/documentation/auth/usage.md b/laravel/documentation/auth/usage.md index 677432cb..4fb3ce51 100644 --- a/laravel/documentation/auth/usage.md +++ b/laravel/documentation/auth/usage.md @@ -31,19 +31,17 @@ You can compare an unhashed value against a hashed one using the **check** metho ## Logging In -Logging a user into your application is simple using the **attempt** method on the Auth class. Simply pass the username and password of the user to the method. The login method will return **true** if the credentials are valid. Otherwise, **false** will be returned: +Logging a user into your application is simple using the **attempt** method on the Auth class. Simply pass the username and password of the user to the method. The credentials should be contained in an array, which allows for maximum flexibility across drivers, as some drivers may require a different number of arguments. The login method will return **true** if the credentials are valid. Otherwise, **false** will be returned: - if (Auth::attempt('example@gmail.com', 'password')) + $credentials = array('username' => 'example@gmail.com', 'password' => 'secret'); + + if (Auth::attempt($credentials)) { return Redirect::to('user/profile'); } If the user's credentials are valid, the user ID will be stored in the session and the user will be considered "logged in" on subsequent requests to your application. -You probably noticed this method name corresponds to the **attempt** function you [configured earlier](/docs/auth/config#attempt). Each time you call the **attempt** method on the **Auth** class, the **attempt** function in the configuration file will be called to check the user's credentials. - -> **Note:** To provide more flexiblity when working with third-party authentication providers, you are not required to pass a password into the **attempt** method. - To determine if the user of your application is logged in, call the **check** method: if (Auth::check()) @@ -75,8 +73,6 @@ Once a user has logged in to your application, you can access the user model via return Auth::user()->email; -This method calls the [**user** function](/docs/auth/config#user) in the configuration file. Also, you don't need to worry about performance when using this method. The user is only retrieved from storage the first time you use the method. - > **Note:** If the user is not logged in, the **user** method will return NULL. From 0f0c291ffbc9091b7bad9ea3d02f5529bbbfe7ce Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Mon, 21 May 2012 10:53:28 -0500 Subject: [PATCH 2/6] updating docs for merge and replace input methods. --- laravel/documentation/auth/usage.md | 1 + laravel/documentation/input.md | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/laravel/documentation/auth/usage.md b/laravel/documentation/auth/usage.md index 4fb3ce51..e02747a0 100644 --- a/laravel/documentation/auth/usage.md +++ b/laravel/documentation/auth/usage.md @@ -7,6 +7,7 @@ - [Protecting Routes](#filter) - [Retrieving The Logged In User](#user) - [Logging Out](#logout) +- [Writing Custom Drivers](#drivers) > **Note:** Before using the Auth class, you must [specify a session driver](/docs/session/config). diff --git a/laravel/documentation/input.md b/laravel/documentation/input.md index fb35e0ee..06343f23 100644 --- a/laravel/documentation/input.md +++ b/laravel/documentation/input.md @@ -7,6 +7,7 @@ - [Old Input](#old-input) - [Redirecting With Old Input](#redirecting-with-old-input) - [Cookies](#cookies) +- [Merging & Replacing](#merge) ## Input @@ -121,4 +122,17 @@ Laravel provides a nice wrapper around the $_COOKIE array. However, there are a #### Deleting a cookie: - Cookie::forget('name'); \ No newline at end of file + Cookie::forget('name'); + + +## Merging & Replacing + +Sometimes you may wish to merge or replace the current input. Here's how: + +#### Merging new data into the current input: + + Input::merge(array('name' => 'Spock')); + +#### Replacing the entire input array with new data: + + Input::merge(array('doctor' => 'Bones', 'captain' => 'Kirk')); \ No newline at end of file From e7ee6865b1c69596b1c84dd403ab43a331589515 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Mon, 21 May 2012 10:55:08 -0500 Subject: [PATCH 3/6] Updating docs. --- laravel/documentation/input.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/laravel/documentation/input.md b/laravel/documentation/input.md index 06343f23..14221ecd 100644 --- a/laravel/documentation/input.md +++ b/laravel/documentation/input.md @@ -3,6 +3,7 @@ ## Contents - [Input](#input) +- [JSON Input](#json) - [Files](#files) - [Old Input](#old-input) - [Redirecting With Old Input](#redirecting-with-old-input) @@ -44,6 +45,15 @@ By default, *null* will be returned if the input item does not exist. However, y > **Note:** The "has" method will return *false* if the input item is an empty string. + +## JSON Input + +When working with JavaScript MVC frameworks like Backbone.js, you will need to get the JSON posted by the application. To make your life easier, we've included the `Input::json` method: + +#### Get JSON input to the application: + + $data = Input::json(); + ## Files From a7959ebc3df362e9be2bbce942866d636634515b Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Mon, 21 May 2012 10:57:23 -0500 Subject: [PATCH 4/6] Updating docs. --- laravel/documentation/views/home.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/laravel/documentation/views/home.md b/laravel/documentation/views/home.md index 1032c7b2..be646393 100644 --- a/laravel/documentation/views/home.md +++ b/laravel/documentation/views/home.md @@ -58,6 +58,14 @@ Sometimes you will need a little more control over the response sent to the brow return Response::view('home', 200, $headers); +#### Returning a JSON response: + + return Response::json(array('name' => 'Batman')); + +#### Returning Eloquent models as JSON: + + return Response::eloquent(User::find(1)); + ## Binding Data To Views From e7a40c0cafe0beb31941215142b591f108731409 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Mon, 21 May 2012 11:02:43 -0500 Subject: [PATCH 5/6] Updating event docs. --- laravel/documentation/events.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/laravel/documentation/events.md b/laravel/documentation/events.md index dc74745f..e678bb5e 100644 --- a/laravel/documentation/events.md +++ b/laravel/documentation/events.md @@ -5,6 +5,7 @@ - [The Basics](#the-basics) - [Firing Events](#firing-events) - [Listening To Events](#listening-to-events) +- [Queued Events](#queued-events) - [Laravel Events](#laravel-events) @@ -51,6 +52,32 @@ So, what good are events if nobody is listening? Register an event handler that The Closure we provided to the method will be executed each time the "loaded" event is fired. + +## Queued Events + +Sometimes you may wish to "queue" an event for firing, but not fire it immediately. This is possible using the `queue` and `flush` methods. First, throw an event on a given queue with a unique identifier: + +#### Registering a queued event: + + Event::queue('foo', $user->id, array($user)); + +This method accepts three parameters. The first is the name of the queue, the second is a unique identifier for this item on the queue, and the third is an array of data to pass to the queue flusher. + +Next, we'll register a flusher for the `foo` queue: + +#### Registering an event flusher: + + Event::flusher('foo', function($key, $user) + { + // + }); + +Note that the event flusher receives two arguments. The first, is the unique identifier for the queued event, which in this case would be the user's ID. The second (and any remaining) parameters would be the payload items for the queued event. + +Finally, we can run our flusher and flush all queued events using the `flush` method: + + Event::flush('foo'); + ## Laravel Events From 5ba802d4733194ca2ed4539e1e085c940da391fa Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Mon, 21 May 2012 11:05:59 -0500 Subject: [PATCH 6/6] Update environment documentation. --- laravel/documentation/install.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/laravel/documentation/install.md b/laravel/documentation/install.md index 3f462e88..12f12951 100644 --- a/laravel/documentation/install.md +++ b/laravel/documentation/install.md @@ -52,11 +52,15 @@ It's **extremely** important that you change the **application key** option befo ## Environments -Most likely, the configuration options you need for local development are not the same as the options you need on your production server. Laravel's default environment handling mechanism is the **LARAVEL_ENV** environment variable. To get started, set the environment variable in your **httpd.conf** file: +Most likely, the configuration options you need for local development are not the same as the options you need on your production server. Laravel's default environment handling mechanism is URL based, which will make setting up environments a breeze. Pop open the `paths.php` file in the root of your Laravel installation. You should see an array like this: - SetEnv LARAVEL_ENV local + $environments = array( -> **Note:** Using a web server other than Apache? Check your server's documentation to learn how to set environment variables. + 'local' => array('http://localhost*', '*.dev'), + + ); + +This tells Laravel that any URLs beginning with "localhost" or ending with ".dev" should be considered part of the "local" environment. Next, create an **application/config/local** directory. Any files and options you place in this directory will override the options in the base **application/config** directory. For example, you may wish to create an **application.php** file within your new **local** configuration directory: @@ -68,9 +72,7 @@ Next, create an **application/config/local** directory. Any files and options yo In this example, the local **URL** option will override the **URL** option in **application/config/application.php**. Notice that you only need to specify the options you wish to override. -If you do not have access to your server's configuration files, you may manually set the **LARAVEL_ENV** variable at the top of Laravel's **paths.php** file: - - $_SERVER['LARAVEL_ENV'] = 'local'; +Isn't it easy? Of course, you are free to create as many environments as you wish! ## Cleaner URLs