Description: <a href="http://daringfireball.net/projects/markdown/syntax">Markdown syntax</a> allows you to write using an easy-to-read, easy-to-write plain text format. Based on the original Perl version by <a href="http://daringfireball.net/">John Gruber</a>. <a href="http://michelf.com/projects/php-markdown/">More...</a>
'description'=>'A text-to-HTML conversion tool for web writers',
'authors'=>'Michel Fortin and John Gruber',
'licence'=>'BSD-like',
'version'=>MARKDOWN_VERSION,
'help'=>'<a href="http://daringfireball.net/projects/markdown/syntax">Markdown syntax</a> allows you to write using an easy-to-read, easy-to-write plain text format. Based on the original Perl version by <a href="http://daringfireball.net/">John Gruber</a>. <a href="http://michelf.com/projects/php-markdown/">More...</a>'
);
}
### Smarty Modifier Interface ###
functionsmarty_modifier_markdown($text){
returnMarkdown($text);
}
### Textile Compatibility Mode ###
# Rename this file to "classTextile.php" and it can replace Textile everywhere.
Generate a secure application key. An application key will not be generated unless the field in **config/application.php** is empty. | `php artisan key:generate`
Laravel's command-line tool is called Artisan. Artisan can be used to run "tasks" such as migrations, cronjobs, unit-tests, or anything that want.
<aname="creating-tasks"></a>
## Creating & Running Tasks
To create a task create a new class in your **application/tasks** directory. The class name should be suffixed with "_Task", and should at least have a "run" method, like this:
#### Creating a task class:
class Notify_Task {
public function run($arguments)
{
// Do awesome notifying...
}
}
Now you can call the "run" method of your task via the command-line. You can even pass arguments:
#### Calling a task from the command line:
php artisan notify
#### Calling a task and passing arguments:
php artisan notify taylor
Remember, you can call specific methods on your task, so, let's add an "urgent" method to the notify task:
#### Adding a method to the task:
class Notify_Task {
public function run($arguments)
{
// Do awesome notifying...
}
public function urgent($arguments)
{
// This is urgent!
}
}
Now we can call our "urgent" method:
#### Calling a specific method on a task:
php artisan notify:urgent
<aname="bundle-tasks"></a>
## Bundle Tasks
To create a task for your bundle just prefix the bundle name to the class name of your task. So, if your bundle was named "admin", a task might look like this:
#### Creating a task class that belongs to a bundle:
class Admin_Generate_Task {
public function run($arguments)
{
// Generate the admin!
}
}
To run your task just use the usual Laravel double-colon syntax to indicate the bundle:
#### Running a task belonging to a bundle:
php artisan admin::generate
#### Running a specific method on a task belonging to a bundle:
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.
<aname="user"></a>
## The "User" Function
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.
Of course, a simple default configuration has been setup for you. Let's take a look:
'user' => function($id)
{
if ( ! is_null($id) and filter_var($id, FILTER_VALIDATE_INT) !== false)
{
return DB::table('users')->find($id);
}
}
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**.
<aname="attempt"></a>
## The "Attempt" Function
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:
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.
<aname="logout"></a>
## 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.
> **Note:** Before using the Auth class, you must [specify a session driver](/docs/session/config).
<aname="hash"></a>
## Salting & Hashing
If you are using the Auth class, you are strongly encouraged to hash and salt all passwords. Web development must be done responsibly. Salted, hashed passwords make a rainbow table attack against your user's passwords impractical.
Salting and hashing passwords is done using the **Hash** class. The Hash class is uses the **bcrypt** hashing algorithm. Check out this example:
$password = Hash::make('secret');
The **make** method of the Hash class will return a 60 character hashed string.
You can compare an unhashed value against a hashed one using the **check** method on the **Hash** class:
if (Hash::check('secret', $hashed_value))
{
return 'The password is valid!';
}
<aname="login"></a>
## 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:
if (Auth::attempt('example@gmail.com', 'password'))
{
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())
{
return "You're logged in!";
}
Use the **login** method to login a user without checking their credentials, such as after a user first registers to use your application. Just pass your user object or the user's ID:
Auth::login($user);
Auth::login(15);
<aname="filter"></a>
## Protecting Routes
It is common to limit access to certain routes only to logged in users. In Laravel this is accomplished using the [auth filter](/docs/routing#filters). If the user is logged in, the request will proceed as normal; however, if the user is not logged in, they will be redirected to the "login" [named route](/docs/routing#named-routes).
To protect a route, simply attach the **auth** filter:
> **Note:** You are free to edit the **auth** filter however you like. A default implementation is located in **application/routes.php**.
<aname="user"></a>
## Retrieving The Logged In User
Once a user has logged in to your application, you can access the user model via the **user** method on the Auth class:
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.
<aname="logout"></a>
## Logging Out
Ready to log the user out of your application?
Auth::logout();
This method will remove the user ID from the session, and the user will no longer be considered logged in on subsequent requests to your application.
-[Bundles & Class Loading](#bundles-and-class-loading)
-[Starting Bundles](#starting-bundles)
-[Routing To Bundles](#routing-to-bundles)
-[Using Bundles](#using-bundles)
-[Bundle Assets](#bundle-assets)
-[Installing Bundles](#installing-bundles)
-[Upgrading Bundles](#upgrading-bundles)
<aname="the-basics"></a>
## The Basics
Bundles are the heart of the improvements that were made in Laravel 3.0. They are a simple way to group code into convenient "bundles". A bundle can have it's own views, configuration, routes, migrations, tasks, and more. A bundle could be everything from a database ORM to a robust authentication system. Modularity of this scope is an important aspect that has driven virtually all design decisions within Laravel. In many ways you can actually think of the application folder as the special default bundle with which Laravel is pre-programmed to load and use.
<aname="creating-and-registering"></a>
## Creating Bundles
The first step in creating a bundle is to create a folder for the bundle within your **bundles** directory. For this example, let's create an "admin" bundle, which could house the administrator back-end to our application. The **application/start.php** file provides some basic configuration that helps to define how our application will run. Likewise we'll create a **start.php** file within our new bundle folder for the same purpose. It is run everytime the bundle is loaded. Let's create it:
#### Creating a bundle start.php file:
<?php
Autoloader::namespaces(array(
'Admin' => Bundle::path('admin').'models',
));
In this start file we've told the auto-loader that classes that are namespaced to "Admin" should be loaded out of our bundle's models directory. You can do anything you want in your start file, but typically it is used for registering classes with the auto-loader. **In fact, you aren't required to create a start file for your bundle.**
Next, we'll look at how to register this bundle with our application!
<aname="registering-bundles"></a>
## Registering Bundles
Now that we have our admin bundle, we need to register it with Laravel. Pull open your **application/bundles.php** file. This is where you register all bundles used by your application. Let's add ours:
#### Registering a simple bundle:
return array('admin'),
By convention, Laravel will assume that the Admin bundle is located at the root level of the bundle directory, but we can specify another location if we wish:
Now Laravel will look for our bundle in **bundles/userscape/admin**.
<aname="bundles-and-class-loading"></a>
## Bundles & Class Loading
Typically, a bundle's **start.php** file only contains auto-loader registrations. So, you may want to just skip **start.php** and declare your bundle's mappings right in its registration array. Here's how:
#### Defining auto-loader mappings in a bundle registration:
return array(
'admin' => array(
'autoloads' => array(
'map' => array(
'Admin' => '(:bundle)/admin.php',
),
'namespaces' => array(
'Admin' => '(:bundle)/lib',
),
'directories' => array(
'(:bundle)/models',
),
),
),
);
Notice that each of these options corresponds to a function on the Laravel [auto-loader](/docs/loading). In fact, the value of the option will automatically be passed to the corresponding function on the auto-loader.
You may have also noticed the **(:bundle)** place-holder. For convenience, this will automatically be replaced with the path to the bundle. It's a piece of cake.
<aname="starting-bundles"></a>
## Starting Bundles
So our bundle is created and registered, but we can't use it yet. First, we need to start it:
#### Starting a bundle:
Bundle::start('admin');
This tells Laravel to run the **start.php** file for the bundle, which will register its classes in the auto-loader. The start method will also load the **routes.php** file for the bundle if it is present.
> **Note:** The bundle will only be started once. Subsequent calls to the start method will be ignored.
If you use a bundle throughout your application, you may want it to start on every request. If this is the case, you can configure the bundle to auto-start in your **application/bundles.php** file:
#### Configuration a bundle to auto-start:
return array(
'admin' => array('auto' => true),
);
You do not always need to explicitly start a bundle. In fact, you can usually code as if the bundle was auto-started and Laravel will take care of the rest. For example, if you attempt to use a bundle views, configurations, languages, routes or filters, the bundle will automatically be started!
Each time a bundle is started, it fires an event. You can listen for the starting of bundles like so:
It is also possible to "disable" a bundle so that it will never be started.
#### Disabling a bundle so it can't be started:
Bundle::disable('admin');
<aname="routing-to-bundles"></a>
## Routing To Bundles
Refer to the documentation on [bundle routing](/docs/routing#bundle-routes) and [bundle controllers](/docs/controllers#bundle-controllers) for more information on routing and bundles.
<aname="using-bundles"></a>
## Using Bundles
As mentioned previously, bundles can have views, configuration, language files and more. Laravel uses a double-colon syntax for loading these items. So, let's look at some examples:
#### Loading a bundle view:
return View::make('bundle::view');
#### Loading a bundle configuration item:
return Config::get('bundle::file.option');
#### Loading a bundle language line:
return Lang::line('bundle::file.line');
Sometimes you may need to gather more "meta" information about a bundle, such as whether it exists, its location, or perhaps its entire configuration array. Here's how:
#### Determine whether a bundle exists:
Bundle::exists('admin');
#### Retrieving the installation location of a bundle:
$location = Bundle::path('admin');
#### Retrieving the configuration array for a bundle:
$config = Bundle::get('admin');
#### Retrieving the names of all installed bundles:
$names = Bundle::names();
<aname="bundle-assets"></a>
## Bundle Assets
If your bundle contains views, it is likely you have assets such as JavaScript and images that need to be available in the **public** directory of the application. No problem. Just create **public** folder within your bundle and place all of your assets in this folder.
Great! But, how do they get into the application's **public** folder. The Laravel "Artisan" command-line provides a simple command to copy all of your bundle's assets to the public directory. Here it is:
#### Publish bundle assets into the public directory:
php artisan bundle:publish
This command will create a folder for the bundle's assets within the application's **public/bundles** directory. For example, if your bundle is named "admin", a **public/bundles/admin** folder will be created, which will contain all of the files in your bundle's public folder.
For more information on conveniently getting the path to your bundle assets once they are in the public directory, refer to the documentation on [asset management](/docs/views/assets#bundle-assets).
<aname="installing-bundles"></a>
## Installing Bundles
Of course, you may always install bundles manually; however, the "Artisan" CLI provides an awesome method of installing and upgrading your bundle. The framework uses simple Zip extraction to install the bundle. Here's how it works.
#### Installing a bundle via Artisan:
php artisan bundle:install eloquent
Great! Now that you're bundle is installed, you're ready to [register it](#registering-bundles) and [publish its assets](#bundle-assets).
Need a list of available bundles? Check out the Laravel [bundle directory](http://bundles.laravel.com)
<aname="upgrading-bundles"></a>
## Upgrading Bundles
When you upgrade a bundle, Laravel will automatically remove the old bundle and install a fresh copy.
#### Upgrading a bundle via Artisan:
php artisan bundle:upgrade eloquent
> **Note:** After upgrading the bundle, you may need to [re-publish its assets](#bundle-assets).
**Important:** Since the bundle is totally removed on an upgrade, you must be aware of any changes you have made to the bundle code before upgrading. You may need to change some configuration options in a bundle. Instead of modifying the bundle code directly, use the bundle start events to set them. Place something like this in your **application/start.php** file.
Imagine your application displays the ten most popular songs as voted on by your users. Do you really need to look up these ten songs every time someone visits your site? What if you could store them for 10 minutes, or even an hour, allowing you to dramatically speed up your application? Laravel's caching makes it simple.
Laravel provides five cache drivers out of the box:
- File System
- Database
- Memcached
- APC
- Redis
- Memory (Arrays)
By default, Laravel is configured to use the **file** system cache driver. It's ready to go out of the box with no configuration. The file system driver stores cached items as files in the **cache** directory. If you're satisfied with this driver, no other configuration is required. You're ready to start using it.
> **Note:** Before using the file system cache driver, make sure your **storage/cache** directory is writeable.
<aname="database"></a>
## Database
The database cache driver uses a given database table as a simple key-value store. To get started, first set the name of the database table in **application/config/cache.php**:
'database' => array('table' => 'laravel_cache'),
Next, create the table on your database. The table should have three columns:
- key (varchar)
- value (text)
- expiration (integer)
That's it. Once your configuration and table is setup, you're ready to start caching!
<aname="memcached"></a>
## Memcached
[Memcached](http://memcached.org) is an ultra-fast, open-source distributed memory object caching system used by sites such as Wikipedia and Facebook. Before using Laravel's Memcached driver, you will need to install and configure Memcached and the PHP Memcache extension on your server.
Once Memcached is installed on your server you must set the **driver** in the **application/config/cache.php** file:
'driver' => 'memcached'
Then, add your Memcached servers to the **servers** array:
[Redis](http://redis.io) is an open source, advanced key-value store. It is often referred to as a data structure server since keys can contain [strings](http://redis.io/topics/data-types#strings), [hashes](http://redis.io/topics/data-types#hashes), [lists](http://redis.io/topics/data-types#lists), [sets](http://redis.io/topics/data-types#sets), and [sorted sets](http://redis.io/topics/data-types#sorted-sets).
Before using the Redis cache driver, you must [configure your Redis servers](/docs/database/redis#config). Now you can just set the **driver** in the **application/config/cache.php** file:
'driver' => 'redis'
<aname="keys"></a>
### Cache Keys
To avoid naming collisions with other applications using APC, Redis, or a Memcached server, Laravel prepends a **key** to each item stored in the cache using these drivers. Feel free to change this value:
'key' => 'laravel'
<aname="memory"></a>
### In-Memory Cache
The "memory" cache driver does not actually cache anything to disk. It simply maintains an internal array of the cache data for the current request. This makes it perfect for unit testing your application in isolation from any storage mechanism. It should never be used as a "real" cache driver.
Storing items in the cache is simple. Simply call the **put** method on the Cache class:
Cache::put('name', 'Taylor', 10);
The first parameter is the **key** to the cache item. You will use this key to retrieve the item from the cache. The second parameter is the **value** of the item. The third parameter is the number of **minutes** you want the item to be cached.
You may also cache something "forever" if you do not want the cache to expire:
Cache::forever('name', 'Taylor');
> **Note:** It is not necessary to serialize objects when storing them in the cache.
<aname="get"></a>
## Retrieving Items
Retrieving items from the cache is even more simple than storing them. It is done using the **get** method. Just mention the key of the item you wish to retrieve:
$name = Cache::get('name');
By default, NULL will be returned if the cached item has expired or does not exist. However, you may pass a different default value as a second parameter to the method:
$name = Cache::get('name', 'Fred');
Now, "Fred" will be returned if the "name" cache item has expired or does not exist.
What if you need a value from your database if a cache item doesn't exist? The solution is simple. You can pass a closure into the **get** method as a default value. The closure will only be executed if the cached item doesn't exist:
Let's take this example a step further. Imagine you want to retrieve the number of registered users for your application; however, if the value is not cached, you want to store the default value in the cache using the **remember** method:
Let's talk through that example. If the **count** item exists in the cache, it will be returned. If it doesn't exist, the result of the closure will be stored in the cache for five minutes **and** be returned by the method. Slick, huh?
Laravel even gives you a simple way to determine if a cached item exists using the **has** method:
if (Cache::has('name'))
{
$name = Cache::get('name');
}
<aname="forget"></a>
## Removing Items
Need to get rid of a cached item? No problem. Just mention the name of the item to the **forget** method:
Sometimes you may need to get and set configuration options at runtime. For this you'll use the **Config** class, which utilizes Laravel's "dot" syntax for accessing configuration files and items.
<aname="retrieving-options"></a>
## Retrieving Options
#### Retrieve a configuration option:
$value = Config::get('application.url');
#### Return a default value if the option doesn't exist:
Controllers are classes that are responsible for accepting user input and managing interactions between models, libraries, and views. Typically, they will ask a model for data, and then return a view that presents that data to the user.
The usage of controllers is the most common method of implementingapplication logic in modern web-development. However, Laravel also empowers developers to implement their application logic within routing declarations. This is explored in detail in the [routing document](/docs/routing). New users are encourage to start with controllers. There is nothing that route-based application logic can do that controllers can't.
Controller classes should be stored in **application/controllers** and should extend the Base\_Controller class. A Home\_Controller class is included with Laravel.
#### Creating a simple controller:
class Admin_Controller extends Base_Controller
{
public function action_index()
{
//
}
}
**Actions** are the name of controller methods that are intended to be web-accessible. Actions should be prefixed with "action\_". All other methods, regardless of scope, will not be web-accessible.
> **Note:** The Base\_Controller class extends the main Laravel Controller class, and gives you a convenient place to put methods that are common to many controllers.
<aname="controller-routing"></a>
## Controller Routing
It is important to be aware that all routes in Laravel must be explicitly defined, including routes to controllers.
This means that controller methods that have not been exposed through route registration **cannot** be accessed. It's possible to automatically expose all methods within a controller using controller route registration. Controller route registrations are typically defined in **application/routes.php**.
Check [the routing page](/docs/routing#controller-routing) for more information on routing to controllers.
<aname="bundle-controllers"></a>
## Bundle Controllers
Bundles are Laravel's modular package system. Bundles can easily configured to handle requests to your application. We'll be going over [bundles in more detail](/docs/bundles) in another document.
Creating controllers that belong to bundles is almost identical to creating your application controllers. Just prefix the controller class name with the name of the bundle, so if your bundle is named "admin", your controller classes would look like this:
#### Creating a bundle controller class:
class Admin_Home_Controller extends Base_Controller
{
public function action_index()
{
return "Hello Admin!";
}
}
But, how do you register a bundle controller with the router? It's simple. Here's what it looks like:
#### Registering a bundle's controller with the router:
Route::controller('admin::home');
Great! Now we can access our "admin" bundle's home controller from the web!
> **Note:** Throughout Laravel the double-colon syntax is used to denote bundles. More information on bundles can be found in the [bundle documentation](/docs/bundles).
<aname="action-filters"></a>
## Action Filters
Action filters are methods that can be run before or after a controller action. With Laravel you don't only have control over which filters are assigned to which actions. But, you can also choose which http verbs (post, get, put, and delete) will activate a filter.
You can assign "before" and "after" filters to controller actions within the controller's constructor.
#### Attaching a filter to all actions:
$this->filter('before', 'auth');
In this example the 'auth' filter will be run before every action within this controller. The auth action comes out-of-the-box with Laravel and can be found in **application/routes.php**. The auth filter verifies that a user is logged in and redirects them to 'login' if they are not.
In this example the auth filter will be run before the action_index() or action_list() methods are run. Users must be logged in before having access to these pages. However, no other actions within this controller require an authenticated session.
#### Attaching a filter to all except a few actions:
Much like the previous example, this declaration ensures that the auth filter is run on only some of this controller's actions. Instead of declaring to which actions the filter applies we are instead declaring the actions that will not require authenticated sessions. It can sometimes be safer to use the 'except' method as it's possible to add new actions to this controller and to forget to add them to only(). This could potentially lead your controller's action being unintentionally accessible by users who haven't been authenticated.
#### Attaching a filter to run on POST:
$this->filter('before', 'csrf')->on('post');
This example shows how a filter can be run only on a specific http verb. In this case we're running the csrf filter only when a form post is made. The csrf filter is designed to prevent form posts from other systems (spam bots for example) and comes by default with Laravel. You can find the csrf filter in **application/routes.php**.
*Further Reading:*
-*[Route Filters](/docs/routing#filters)*
<aname="nested-controllers"></a>
## Nested Controllers
Controllers may be located within any number of sub-directories within the main **application/controllers** folder.
Define the controller class and store it in **controllers/admin/panel.php**.
class Admin_Panel_Controller extends Base_Controller
{
public function action_index()
{
//
}
}
#### Register the nested controller with the router using "dot" syntax:
Route::controller('admin.panel');
> **Note:** When using nested controllers, always register your controllers from most nested to least nested in order to avoid shadowing controller routes.
#### Access the "index" action of the controller:
http://localhost/admin/panel
<aname="controller-layouts"></a>
## Controller Layouts
Full documentation on using layouts with Controllers [can be found on the Templating page](http://laravel.com/docs/views/templating).
<aname="restful-controllers"></a>
## RESTful Controllers
Instead of prefixing controller actions with "action_", you may prefix them with the HTTP verb they should respond to.
#### Adding the RESTful property to the controller:
class Home_Controller extends Base_Controller
{
public $restful = true;
}
#### Building RESTful controller actions:
class Home_Controller extends Base_Controller
{
public $restful = true;
public function get_index()
{
//
}
public function post_index()
{
//
}
}
This is particularly useful when building CRUD methods as you can separate the logic which populates and renders a form from the logic that validates and stores the results.
<aname="dependency-injection"></a>
## Dependency Injection
If you are focusing on writing testable code, you will probably want to inject dependencies into the constructor of your controller. No problem. Just register your controller in the [IoC container](/docs/ioc). When registering the controller with the container, prefix the key with **controller**. So, in our **application/start.php** file, we could register our user controller like so:
IoC::register('controller: user', function()
{
return new User_Controller;
});
When a request to a controller enters your application, Laravel will automatically determine if the controller is registered in the container, and if it is, will use the container to resolve an instance of the controller.
> **Note:** Before diving into controller dependency injection, you may wish to read the documentation on Laravel's beautiful [IoC container](/docs/ioc).
<aname="controller-factory"></a>
## Controller Factory
If you want even more control over the instantiation of your controllers, such as using a third-party IoC container, you'll need to use the Laravel controller factory.
**Register an event to handle controller instantiation:**
Laravel supports the following databases out of the box:
- MySQL
- PostgreSQL
- SQLite
- SQL Server
All of the database configuration options live in the **application/config/database.php** file.
<aname="quick"></a>
## Quick Start Using SQLite
[SQLite](http://sqlite.org) is an awesome, zero-configuration database system. By default, Laravel is configured to use a SQLite database. Really, you don't have to change anything. Just drop a SQLite database named **application.sqlite** into the **application/storage/database** directory. You're done.
Of course, if you want to name your database something besides "application", you can modify the database option in the SQLite section of the **application/config/database.php** file:
'sqlite' => array(
'driver' => 'sqlite',
'database' => 'your_database_name',
)
If your application receives less than 100,000 hits per day, SQLite should be suitable for production use in your application. Otherwise, consider using MySQL or PostgreSQL.
> **Note:** Need a good SQLite manager? Check out this [Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/sqlite-manager/).
<aname="server"></a>
## Configuring Other Databases
If you are using MySQL, SQL Server, or PostgreSQL, you will need to edit the configuration options in **application/config/database.php**. In the configuration file you can find sample configurations for each of these systems. Just change the options as necessary for your server and set the default connection name.
<aname="default"></a>
## Setting The Default Connection Name
As you have probably noticed, each database connection defined in the **application/config/database.php** file has a name. By default, there are three connections defined: **sqlite**, **mysql**, **sqlsrv**, and **pgsql**. You are free to change these connection names. The default connection can be specified via the **default** option:
'default' => 'sqlite';
The default connection will always be used by the [fluent query builder](/docs/database/fluent). If you need to change the default connection during a request, use the **Config::set** method.
An ORM is an [object-relational mapper](http://en.wikipedia.org/wiki/Object-relational_mapping), and Laravel has one that you will absolutely love to use. It is named "Eloquent" because it allows you to work with your database objects and relationships using an eloquent and expressive syntax. In general, you will define one Eloquent model for each table in your database. To get started, let's define a simple model:
class User extends Eloquent {}
Nice! Notice that our model extends the **Eloquent** class. This class will provide all of the functionality you need to start working eloquently with your database.
> **Note:** Typically, Eloquent models live in the **application/models** directory.
<aname="conventions"></a>
## Conventions
Eloquent makes a few basic assumptions about your database structure:
- Each table should have a primary key named **id**.
- Each table name should be the plural form of its corresponding model name.
Sometimes you may wish to use a table name other than the plural form of your model. No problem. Just add a static **table** property your model:
class User extends Eloquent {
public static $table = 'my_users';
}
<aname="get"></a>
## Retrieving Models
Retrieving models using Eloquent is refreshingly simple. The most basic way to retrieve an Eloquent model is the static **find** method. This method will return a single model by primary key with properties corresponding to each column on the table:
$user = User::find(1);
echo $user->email;
The find method will execute a query that looks something like this:
SELECT * FROM "users" WHERE "id" = 1
Need to retrieve an entire table? Just use the static **all** method:
$users = User::all();
foreach ($users as $user)
{
echo $user->email;
}
Of course, retrieving an entire table isn't very helpful. Thankfully, **every method that is available through the fluent query builder is available in Eloquent**. Just begin querying your model with a static call to one of the [query builder](/docs/database/query) methods, and execute the query using the **get** or **first** method. The get method will return an array of models, while the first method will return a single model:
> **Note:** If no results are found, the **first** method will return NULL. The **all** and **get** methods return an empty array.
<aname="aggregates"></a>
## Aggregates
Need to get a **MIN**, **MAX**, **AVG**, **SUM**, or **COUNT** value? Just pass the column to the appropriate method:
$min = User::min('id');
$max = User::max('id');
$avg = User::avg('id');
$sum = User::sum('id');
$count = User::count();
Of course, you may wish to limit the query using a WHERE clause first:
$count = User::where('id', '>', 10)->count();
<aname="save"></a>
## Inserting & Updating Models
Inserting Eloquent models into your tables couldn't be easier. First, instantiate a new model. Second, set its properties. Third, call the **save** method:
$user = new User;
$user->email = 'example@gmail.com';
$user->password = 'secret';
$user->save();
Alternatively, you may use the **create** method, which will insert a new record into the database and return the model instance for the newly inserted record, or **false** if the insert failed.
Updating models is just as simple. Instead of instantiating a new model, retrieve one from your database. Then, set its properties and save:
$user = User::find(1);
$user->email = 'new_email@gmail.com';
$user->password = 'new_secret';
$user->save();
Need to maintain creation and update timestamps on your database records? With Eloquent, you don't have to worry about it. Just add a static **timestamps** property to your model:
class User extends Eloquent {
public static $timestamps = true;
}
Next, add **created_at** and **updated_at** date columns to your table. Now, whenever you save the model, the creation and update timestamps will be set automatically. You're welcome.
> **Note:** You can change the default timezone of your application in the **application/config/application.php** file.
<aname="relationships"></a>
## Relationships
Unless you're doing it wrong, your database tables are probably related to one another. For instance, an order may belong to a user. Or, a post may have many comments. Eloquent makes defining relationships and retrieving related models simple and intuitive. Laravel supports three types of relationships:
-[One-To-One](#one-to-one)
-[One-To-Many](#one-to-many)
-[Many-To-Many](#many-to-many)
To define a relationship on an Eloquent model, you simply create a method that returns the result of either the **has\_one**, **has\_many**, **belongs\_to**, or **has\_many\_and\_belongs\_to** method. Let's examine each one in detail.
<aname="one-to-one"></a>
### One-To-One
A one-to-one relationship is the most basic form of relationship. For example, let's pretend a user has one phone. Simply describe this relationship to Eloquent:
class User extends Eloquent {
public function phone()
{
return $this->has_one('Phone');
}
}
Notice that the name of the related model is passed to the **has_one** method. You can now retrieve the phone of a user through the **phone** method:
$phone = User::find(1)->phone()->first();
Let's examine the SQL performed by this statement. Two queries will be performed: one to retrieve the user and one to retrieve the user's phone:
SELECT * FROM "users" WHERE "id" = 1
SELECT * FROM "phones" WHERE "user_id" = 1
Note that Eloquent assumes the foreign key of the relationship will be **user\_id**. Most foreign keys will follow this **model\_id** convention; however, if you want to use a different column name as the foreign key, just pass it in the second parameter to the method:
return $this->has_one('Phone', 'my_foreign_key');
Want to just retrieve the user's phone without calling the first method? No problem. Just use the **dynamic phone property**. Eloquent will automatically load the relationship for you, and is even smart enough to know whether to call the get (for one-to-many relationships) or first (for one-to-one relationships) method:
$phone = User::find(1)->phone;
What if you need to retrieve a phone's user? Since the foreign key (**user\_id**) is on the phones table, we should describe this relationship using the **belongs\_to** method. It makes sense, right? Phones belong to users. When using the **belongs\_to** method, the name of the relationship method should correspond to the foreign key (sans the **\_id**). Since the foreign key is **user\_id**, your relationship method should be named **user**:
class Phone extends Eloquent {
public function user()
{
return $this->belongs_to('User');
}
}
Great! You can now access a User model through a Phone model using either your relationship method or dynamic property:
echo Phone::find(1)->user()->first()->email;
echo Phone::find(1)->user->email;
<aname="one-to-many"></a>
### One-To-Many
Assume a blog post has many comments. It's easy to define this relationship using the **has_many** method:
class Post extends Eloquent {
public function comments()
{
return $this->has_many('Comment');
}
}
Now, simply access the post comments through the relationship method or dynamic property:
$comments = Post::find(1)->comments()->get();
$comments = Post::find(1)->comments;
Both of these statements will execute the following SQL:
SELECT * FROM "posts" WHERE "id" = 1
SELECT * FROM "comments" WHERE "post_id" = 1
Want to join on a different foreign key? No problem. Just pass it in the second parameter to the method:
You may be wondering: _If the dynamic properties return the relationship and require less keystokes, why would I ever use the relationship methods?_ Actually, relationship methods are very powerful. They allow you to continue to chain query methods before retrieving the relationship. Check this out:
Many-to-many relationships are the most complicated of the three relationships. But don't worry, you can do this. For example, assume a User has many Roles, but a Role can also belong to many Users. Three database tables must be created to accomplish this relationship: a **users** table, a **roles** table, and a **role_user** table. The structure for each table looks like this:
**Users:**
id - INTEGER
email - VARCHAR
**Roles:**
id - INTEGER
name - VARCHAR
**Roles_Users:**
user_id - INTEGER
role_id - INTEGER
Now you're ready to define the relationship on your models using the **has\_many\_and\_belongs\_to** method:
class User extends Eloquent {
public function roles()
{
return $this->has_many_and_belongs_to('Role');
}
}
Great! Now it's time to retrieve a user's roles:
$roles = User::find(1)->roles()->get();
Or, as usual, you may retrieve the relationship through the dynamic roles property:
$roles = User::find(1)->roles;
As you may have noticed, the default name of the intermediate table is the singular names of the two related models arranged alphabetically and concatenated by an underscore. However, you are free to specify your own table name. Simply pass the table name in the second parameter to the **has\_and\_belongs\_to\_many** method:
Let's assume you have a **Post** model that has many comments. Often you may want to insert a new comment for a given post. Instead of manually setting the **post_id** foreign key on your model, you may insert the new comment from it's owning Post model. Here's what it looks like:
$comment = new Comment(array('message' => 'A new comment.'));
$post = Post::find(1);
$post->comments()->insert($comment);
When inserting related models through their parent model, the foreign key will automatically be set. So, in this case, the "post_id" was automatically set to "1" on the newly inserted comment.
This is even more helpful when working with many-to-many relationships. For example, consider a **User** model that has many roles. Likewise, the **Role** model may have many users. So, the intermediate table for this relationship has "user_id" and "role_id" columns. Now, let's insert a new Role for a User:
$role = new Role(array('title' => 'Admin'));
$user = User::find(1);
$user->roles()->insert($role);
Now, when the Role is inserted, not only is the Role inserted into the "roles" table, but a record in the intermediate table is also inserted for you. It couldn't be easier!
However, you may often only want to insert a new record into the intermediate table. For example, perhaps the role you wish to attach to the user already exists. Just use the attach method:
$user->roles()->attach($role_id);
<aname="intermediate-tables"></a>
## Working With Intermediate Tables
As your probably know, many-to-many relationships require the presence of an intermediate table. Eloquent makes it a breeze to maintain this table. For example, let's assume we have a **User** model that has many roles. And, likewise, a **Role** model that has many users. So the intermediate table has "user_id" and "role_id" columns. We can access the pivot table for the relationship like so:
$user = User::find(1);
$pivot = $user->roles()->pivot();
Once we have an instance of the pivot table, we can use it just like any other Eloquent model:
foreach ($user->roles()->pivot()->get() as $row)
{
//
}
You may also access the specific intermediate table row associated with a given record. For example:
$user = User::find(1);
foreach ($user->roles as $role)
{
echo $role->pivot->created_at;
}
Notice that each related **Role** model we retrieved is automatically assigned a **pivot** attribute. This attribute contains a model representing the intermediate table record associated with that related model.
Sometimes you may wish to remove all of the record from the intermediate table for a given model relationship. For instance, perhaps you want to remove all of the assigned roles from a user. Here's how to do it:
$user = User::find(1);
$user->roles()->delete();
Note that this does not delete the roles from the "roles" table, but only removes the records from the intermediate table which associated the roles with the given user.
<aname="eager"></a>
## Eager Loading
Eager loading exists to alleviate the N + 1 query problem. Exactly what is this problem? Well, pretend each Book belongs to an Author. We would describe this relationship like so:
class Book extends Eloquent {
public function author()
{
return $this->belongs_to('Author');
}
}
Now, examine the following code:
foreach (Book::all() as $book)
{
echo $book->author->name;
}
How many queries will be executed? Well, one query will be executed to retrieve all of the books from the table. However, another query will be required for each book to retrieve the author. To display the author name for 25 books would require **26 queries**. See how the queries can add up fast?
Thankfully, you can eager load the author models using the **with** method. Simply mention the **function name** of the relationship you wish to eager load:
foreach (Book::with('author')->get() as $book)
{
echo $book->author->name;
}
In this example, **only two queries will be executed**!
SELECT * FROM "books"
SELECT * FROM "authors" WHERE "id" IN (1, 2, 3, 4, 5, ...)
Obviously, wise use of eager loading can dramatically increase the performance of your application. In the example above, eager loading cut the execution time in half.
Need to eager load more than one relationship? It's easy:
> **Note:** When eager loading, the call to the static **with** method must always be at the beginning of the query.
You may even eager load nested relationships. For example, let's assume our **Author** model has a "contacts" relationship. We can eager load both of the relationships from our Book model like so:
Call a setter method as a variable (without parenthesis) using the name of the method without the "set_" prefix.
$this->password = "my new password";
Getters are very similar. They can be used to modify attributes before they're returned. Define a getter by appending "get_" to the intended attribute's name.
Call the getter method as a variable (without parenthesis) using the name of the method without the "get_" prefix.
echo $this->published_date;
<aname="mass-assignment"></a>
## Mass-Assignment
Mass-assignment is the practice of passing an associative array to a model method which then fills the model's attributes with the values from the array. Mass-assignment can be done by passing an array to the model's constructor:
$user = new User(array(
'username' => 'first last',
'password' => 'disgaea'
));
$user->save();
Or, mass-assignment may be accomplished using the **fill** method.
$user = new User;
$user->fill(array(
'username' => 'first last',
'password' => 'disgaea'
));
$user->save();
By default, all attribute key/value pairs will be store during mass-assignment. However, it is possible to create a white-list of attributes that will be set. If the accessible attribute white-list is set then no attributes other than those specified will be set during mass-assignment.
You can specify accessible attributes by assigning the **$accessible** static array. Each element contains the name of a white-listed attribute.
public static $accessible = array('email', 'password', 'name');
Alternatively, you may use the **accessible** method from your model:
The Fluent Query Builder is Laravel's powerful fluent interface for building SQL queries and working with your database. All queries use prepared statements and are protected against SQL injection.
You can begin a fluent query using the **table** method on the DB class. Just mention the table you wish to query:
$query = DB::table('users');
You now have a fluent query builder for the "users" table. Using this query builder, you can retrieve, insert, update, or delete records from the table.
<aname="get"></a>
## Retrieving Records
#### Retrieving an array of records from the database:
$users = DB::table('users')->get();
> **Note:** The **get** method returns an array of objects with properties corresponding to the column on the table.
#### Retrieving a single record from the database:
$user = DB::table('users')->first();
#### Retrieving a single record by its primary key:
$user = DB::table('users')->find($id);
> **Note:** If no results are found, the **first** method will return NULL. The **get** method will return an empty array.
#### Retrieving the value of a single column from the database:
#### Only selecting certain columns from the database:
$user = DB::table('users')->get(array('id', 'email as user_email'));
#### Selecting distinct results from the database:
$user = DB::table('users')->distinct()->get();
<aname="where"></a>
## Building Where Clauses
### where and or\_where
There are a variety of methods to assist you in building where clauses. The most basic of these methods are the **where** and **or_where** methods. Here is how to use them:
return DB::table('users')
->where('id', '=', 1)
->or_where('email', '=', 'example@gmail.com')
->first();
Of course, you are not limited to simply checking equality. You may also use **greater-than**, **less-than**, **not-equal**, and **like**:
return DB::table('users')
->where('id', '>', 1)
->or_where('name', 'LIKE', '%Taylor%')
->first();
As you may have assumed, the **where** method will add to the query using an AND condition, while the **or_where** method will use an OR condition.
### where\_in, where\_not\_in, or\_where\_in, and or\_where\_not\_in
The suite of **where_in** methods allows you to easily construct queries that search an array of values:
You may discover the need to group portions of a WHERE clause within parentheses. Just pass a Closure as parameter to the **where** or **or_where** methods:
$users = DB::table('users')
->where('id', '=', 1)
->or_where(function($query)
{
$query->where('age', '>', 25);
$query->where('votes' '>', 100);
})
->get();
The example above would generate a query that looks like:
SELECT * FROM "users" WHERE "id" = ? OR ("age" > ? AND "votes" > ?)
<aname="dynamic"></a>
## Dynamic Where Clauses
Dynamic where methods are great way to increase the readability of your code. Here are some examples:
Sometimes you may need to set the value of a column to a SQL function such as **NOW()**. Usually a reference to now() would automatically be quoted and escaped. To prevent this use the **raw** method on the **DB** class. Here's what it looks like:
The **raw** method tells the query to inject the contents of the expression into the query as a string rather than a bound parameter. For example, you can also use expressions to increment column values:
-[Prepping Your Database](#prepping-your-database)
-[Creating Migrations](#creating-migrations)
-[Running Migrations](#running-migrations)
-[Rolling Back](#rolling-back)
<aname="the-basics"></a>
## The Basics
Think of migrations as a type of version control for your database. Let's say your working on a team, and you all have local databases for development. Good ole' Eric makes a change to the database and checks in his code that uses the new column. You pull in the code, and your application breaks because you don't have the new column. What do you do? Migrations are the answer. Let's dig in deeper to find out how to use them!
<aname="prepping-your-database"></a>
## Prepping Your Database
Before you can run migrations, we need to do some work on your database. Laravel uses a special table to keep track of which migrations have already run. To create this table, just use the Artisan command-line:
**Creating the Laravel migrations table:**
php artisan migrate:install
<aname="creating-migrations"></a>
## Creating Migrations
You can easily create migrations through Laravel's "Artisan" CLI. It looks like this:
**Creating a migration**
php artisan migrate:make create_users_table
Now, check your **application/migrations** folder. You should see your brand new migration! Notice that it also contains a timestamp. This allows Laravel to run your migrations in the correct order.
**Running all outstanding migrations in application and bundles:**
php artisan migrate
**Running all outstanding migrations in the application:**
php artisan migrate application
**Running all outstanding migrations in a bundle:**
php artisan migrate bundle
<aname="rolling-back"></a>
## Rolling Back
When you roll back a migration, Laravel rolls back the entire migration "operation". So, if the last migration command ran 122 migrations, all 122 migrations would be rolled back.
[Redis](http://redis.io) is an open source, advanced key-value store. It is often referred to as a data structure server since keys can contain [strings](http://redis.io/topics/data-types#strings), [hashes](http://redis.io/topics/data-types#hashes), [lists](http://redis.io/topics/data-types#lists), [sets](http://redis.io/topics/data-types#sets), and [sorted sets](http://redis.io/topics/data-types#sorted-sets).
<aname="config"></a>
## Configuration
The Redis configuration for your application lives in the **application/config/database.php** file. Within this file, you will see a **redis** array containing the Redis servers used by your application:
The default server configuration should suffice for development. However, you are free to modify this array based on your environment. Simply give each Redis server a name, and specify the host and port used by the server.
<aname="usage"></a>
## Usage
You may get a Redis instance by calling the **db** method on the **Redis** class:
$redis = Redis::db();
This will give you an instance of the **default** Redis server. You may pass the server name to the **db** method to get a specific server as defined in your Redis configuration:
$redis = Redis::db('redis_2');
Great! Now that we have an instance of the Redis client, we may issue any of the [Redis commands](http://redis.io/commands) to the instance. Laravel uses magic methods to pass the commands to the Redis server:
$redis->set('name', 'Taylor');
$name = $redis->get('name');
$values = $redis->lrange('names', 5, 10);
Notice the arguments to the comment are simply passed into the magic method. Of course, you are not required to use the magic methods, you may also pass commands to the server using the **run** method:
$values = $redis->run('lrange', array(5, 10));
Just want to execute commands on the default Redis server? You can just use static magic methods on the Redis class:
Redis::set('name', 'Taylor');
$name = Redis::get('name');
$values = Redis::lrange('names', 5, 10);
> **Note:** Redis [cache](/docs/cache/config#redis) and [session](/docs/session/config#redis) drivers are included with Laravel.
The Schema Bulder provides methods for creating and modifying your database tables. Using a fluent syntax, you can work with your tables without using any vendor specific SQL.
*Further Reading:*
-[Migrations](/docs/database/migrations)
<aname="creating-dropping-tables"></a>
## Creating & Dropping Tables
The **Schema** class is used to create and modify tables. Let's jump right into an example:
#### Creating a simple database table:
Schema::create('users', function($table)
{
$table->increments('id');
});
Let's go over this example. The **create** method tells the Schema builder that this is a new table, so it should be created. In the second argument, we passed a Closure which receives a Table instance. Using this Table object, we can fluently add and drop columns and indexes on the table.
#### Dropping a table from the database:
Schema::drop('users');
Sometimes you may need to specify the database connection on which the schema operation should be performed.
#### Specifying the connection to run the operation on:
Schema::create('users', function($table)
{
$table->on('connection');
});
<aname="adding-columns"></a>
## Adding Columns
The fluent table builder's methods allow you to add columns without using vendor specific SQL. Let's go over it's methods:
Command | Description
------------- | -------------
`$table->increments('id');` | Incrementing ID to the table
`$table->string('name', 100);` | VARCHAR equivalent with a length
`$table->integer('votes');` | INTEGER equivalent to the table
`$table->float('amount');` | FLOAT equivalent to the table
`$table->boolean('confirmed');` | BOOLEAN equivalent to the table
`$table->date('created_at');` | DATE equivalent to the table
`$table->timestamp('added_on');` | TIMESTAMP equivalent to the table
`$table->timestamps();` | Adds **created\_at** and **updated\_at** columns
`$table->text('description');` | TEXT equivalent to the table
`$table->blob('data');` | BLOB equivalent to the table
`->nullable()` | Designate that the column allows NULL values
> **Note:** Laravel's "boolean" type maps to a small integer column on all database systems.
#### Example of creating a table and adding columns
Schema::table('users', function($table)
{
$table->create();
$table->increments('id');
$table->string('username');
$table->string('email');
$table->string('phone')->nullable();
$table->text('about');
$table->timestamps();
});
<aname="dropping-columns"></a>
## Dropping Columns
#### Dropping a column from a database table:
$table->drop_column('name');
#### Dropping several columns from a database table:
$table->drop_column(array('name', 'email'));
<aname="adding-indexes"></a>
## Adding Indexes
The Schema builder supports several types of indexes. There are two ways to add the indexes. Each type of index has its method; however, you can also fluently define an index on the same line as a column addition. Let's take a look:
#### Fluently creating a string column with an index:
$table->string('email')->unique();
If defining the indexes on a separate line is more your style, here are example of using each of the index methods:
`$table->unique('email');` | Adding a unique index
`$table->fulltext('description');` | Adding a full-text index
`$table->index('state');` | Adding a basic index
<aname="dropping-indexes"></a>
## Dropping Indexes
To drop indexes you must specify the index's name. Laravel assigns a reasonable name to all indexes. Simply concatenate the table name and the names of the columns in the index, then append the type of the index. Let's take a look at some examples:
Command | Description
------------- | -------------
`$table->drop_primary('users_id_primary');` | Dropping a primary key from the "users" table
`$table->drop_unique('users_email_unique');` | Dropping a unique index from the "users" table
`$table->drop_fulltext('profile_description_fulltext');` | Dropping a full-text index from the "profile" table
`$table->drop_index('geo_state_index');` | Dropping a basic index from the "geo" table
<aname="foreign-keys"></a>
## Foreign Keys
You may easily add foreign key constraints to your table using Schema's fluent interface. For example, let's assume you have a **user_id** on a **posts** table, which references the **id** column of the **users** table. Here's how to add a foreign key constraint for the column:
You may also easily drop a foreign key constraint. The default foreign key names follow the [same convention](#dropping-indexes) as the other indexes created by the Schema builder. Here's an example:
Laravel's **Crypter** class provides a simple interface for handling secure, two-way encryption. By default, the Crypter class provides strong AES-256 encryption and decryption out of the box via the Mcrypt PHP extension.
> **Note:** Don't forget to install the Mcrypt PHP extension on your server.
<aname="encrypt"></a>
## Encrypting A String
#### Encrypting a given string:
$encrypted = Crypter::encrypt($value);
<aname="decrypt"></a>
## Decrypting A String
#### Decrypting a string:
$decrypted = Crypter::decrypt($encrypted);
> **Note:** It's incredibly important to point out that the decrypt method will only decrypt strings that were encrypted using **your** application key.
Events can provide a great away to build de-coupled applications, and allow plug-ins to tap into the core of your application without modifying its code.
<aname="firing-events"></a>
## Firing Events
To fire an event, just tell the **Event** class the name of the event you want to fire:
#### Firing an event:
$responses = Event::fire('loaded');
Notice that we assigned the result of the **fire** method to a variable. This method will return an array containing the responses of all the event's listeners.
Sometimes you may want to fire an event, but just get the first response. Here's how:
#### Firing an event and retrieving the first response:
$response = Event::first('loaded');
> **Note:** The **first** method will still fire all of the handlers listening to the event, but will only return the first response.
The **Event::until** method will execute the event handlers until the first non-null response is returned.
#### Firing an event until the first non-null response:
$response = Event::until('loaded');
<aname="listening-to-events"></a>
## Listening To Events
So, what good are events if nobody is listening? Register an event handler that will be called when an event fires:
#### Registering an event handler:
Event::listen('loaded', function()
{
// I'm executed on the "loaded" event!
});
The Closure we provided to the method will be executed each time the "loaded" event is fired.
<aname="laravel-events"></a>
## Laravel Events
There are several events that are fired by the Laravel core. Here they are:
> **Note:** You can easily validate file uploads using the [Validator class](/docs/validation).
<aname="ext"></a>
## File Extensions
#### Getting the extension from a filename:
File::extension('picture.png');
<aname="is"></a>
## Checking File Types
#### Determining if a file is given type:
if (File::is('jpg', 'path/to/file.jpg'))
{
//
}
The **is** method does not simply check the file extension. The Fileinfo PHP extension will be used to read the content of the file and determine the actual MIME type.
> **Note:** You may pass any of the extensions defined in the **application/config/mimes.php** file to the **is** method.
> **Note:** The Fileinfo PHP extension is required for this functionality. More information can be found on the [PHP Fileinfo page](http://php.net/manual/en/book.fileinfo.php).
<aname="mime"></a>
## Getting MIME Types
#### Getting the MIME type associated with an extension:
echo File::mime('gif');
> **Note:** This method simply returns the MIME type defined for the extension in the **application/config/mimes.php** file.
<aname="cpdir"></a>
## Copying Directories
#### Recursively copy a directory to a given location:
-[Who Will Enjoy Laravel?](#who-will-enjoy-laravel)
-[What Makes Laravel Different?](#laravel-is-different)
-[Application Structure](#application-structure)
-[Laravel's Community](#laravel-community)
-[License Information](#laravel-license)
<aname="the-basics"></a>
## The Basics
Welcome to the Laravel documentation. These documents were designed to function both as a getting-started guide and as a feature reference. Even though you may jump into any section and start learning, we recommend reading the documentation in order as it allows us to progressively establish concepts that will be used in later documents.
<aname="who-will-enjoy-laravel"></a>
## Who Will Enjoy Laravel?
Laravel is a powerful framework that emphasizes flexibility and expressiveness. Users new to Laravel will enjoy the same ease of development that is found in the most popular and lightweight PHP frameworks. More experienced users will appreciate the opportunity to modularize their code in ways that are not possible with other frameworks. Laravel's flexibility will allow your organization to update and mold the application over time as is needed and its expressiveness will allow you and your team to develop code that is both concise and easily read.
<aname="laravel-is-different"></a>
## What Makes Laravel Different?
There are many ways in which Laravel differentiates itself from other frameworks. Here are a few examples that we think make good bullet points:
-**Bundles** are Laravel's modular packaging system. [The Laravel Bundle Repository](http://bundles.laravel.com/) is already populated with quite a few features that can be easily added to your application. You can either download a bundle repository to your bundles directory or use the "Artisan" command-line tool to automatically install them.
-**The Eloquent ORM** is the most advanced PHP ActiveRecord implementation available. With the capacity to easily apply constraints to both relationships and nested eager-loading you'll have complete control over your data with all of the conveniences of ActiveRecord. Eloquent natively supports all of the methods from Laravel's Fluent query-builder.
-**Application Logic** can be implemented within your application either using controllers (which many web-developers are already familiar with) or directly into route declarations using syntax similar to the Sinatra framework. Laravel is designed with the philosophy of giving a developer the flexibility that they need to create everything from very small sites to massive enterprise applications.
-**Reverse Routing** allows you to create links to named routes. When creating links just use the route's name and Laravel will automatically insert the correct URI. This allows you to change your routes at a later time and Laravel will update all of the relevant links site-wide.
-**Restful Controllers** are an optional way to separate your GET and POST request logic. In a login example your controller's get_login() action would serve up the form and your controller's post_login() action would accept the posted form, validate, and either redirect to the login form with an error message or redirect your user to their dashboard.
-**Class Auto Loading** keeps you from having to maintain an autoloader configuration and from loading unnecessary components when they won't be used. Want to use a library or model? Don't bother loading it, just use it. Laravel will handle the rest.
-**View Composers** are blocks of code that can be run when a view is loaded. A good example of this would be a blog side-navigation view that contains a list of random blog posts. Your composer would contain the logic to load the blog posts so that all you have to do i load the view and it's all ready for you. This keeps you from having to make sure that your controllers load the a bunch of data from your models for views that are unrelated to that method's page content.
-**The IoC container** (Inversion of Control) gives you a method for generating new objects and optionally instantiating and referencing singletons. IoC means that you'll rarely ever need to bootstrap any external libraries. It also means that you can access these objects from anywhere in your code without needing to deal with an inflexible monolithic structure.
-**Migrations** are version control for your database schemas and they are directly integrated into Laravel. You can both generate and run migrations using the "Artisan" command-line utility. Once another member makes schema changes you can update your local copy from the repository and run migrations. Now you're up to date, too!
-**Unit-Testing** is an important part of Laravel. Laravel itself sports hundreds of tests to help ensure that new changes don't unexpectedly break anything. This is one of the reasons why Laravel is widely considered to have some of the most stable releases in the industry. Laravel also makes it easy for you to write unit-tests for your own code. You can then run tests with the "Artisan" command-line utility.
-**Automatic Pagination** prevents your application logic from being cluttered up with a bunch of pagination configuration. Instead of pulling in the current page, getting a count of db records, and selected your data using a limit/offset just call 'paginate' and tell Laravel where to output the paging links in your view. Laravel automatically does the rest. Laravel's pagination system was designed to be easy to implement and easy to change. It's also important to note that just because Laravel can handle these things automatically doesn't mean that you can't call and configure these systems manually if you prefer.
These are just a few ways in which Laravel differentiates itself from other PHP frameworks. All of these features and many more are discussed thoroughly in this documentation.
<aname="application-structure"></a>
## Application Structure
Laravel's directory structure is designed to be familiar to users of other popular PHP frameworks. Web applications of any shape or size can easily be created using this structure similarly to the way that they would be created in other frameworks.
However due to Laravel's unique architecture, it is possible for developers to create their own infrastructure that is specifically designed for their application. This may be most beneficial to large projects such as content-management-systems. This kind of architectural flexibility is unique to Laravel.
Throughout the documentation we'll specify the default locations for declarations where appropriate.
<aname="laravel-community"></a>
## Laravel's Community
Laravel is lucky to be supported by rapidly growing, friendly and enthusiastic community. The [Laravel Forums](http://forums.laravel.com) are a great place to find help, make a suggestion, or just see what other people are saying.
Many of us hang out every day in the #laravel IRC channel on FreeNode. [Here's a forum post explaining how you can join us.](http://forums.laravel.com/viewtopic.php?id=671) Hanging out in the IRC channel is a really great way to learn more about web-development using Laravel. You're welcome to ask questions, answer other people's questions, or just hang out and learn from other people's questions being answered. We love Laravel and would love to talk to you about it, so don't be a stranger!
<aname="laravel-license"></a>
## License Information
Laravel is open-sourced software licensed under the [MIT License](http://www.opensource.org/licenses/mit-license.php).
-[Redirecting With Old Input](#redirecting-with-old-input)
-[Cookies](#cookies)
<aname="input"></a>
## Input
The **Input** class handles input that comes into your application via GET, POST, PUT, or DELETE requests. Here are some examples of how to access input data using the Input class:
#### Retrieve a value from the input array:
$email = Input::get('email');
> **Note:** The "get" method is used for all request types (GET, POST, PUT, and DELETE), not just GET requests.
#### Retrieve all input from the input array:
$input = Input::get();
#### Retrieve all input including the $_FILES array:
$input = Input::all();
By default, *null* will be returned if the input item does not exist. However, you may pass a different default value as a second parameter to the method:
#### Returning a default value if the requested input item doesn't exist:
#### Determining if the input contains a given item:
if (Input::has('name')) ...
> **Note:** The "has" method will return *false* if the input item is an empty string.
<aname="files"></a>
## Files
#### Retrieving all items from the $_FILES array:
$files = Input::file();
#### Retrieving an item from the $_FILES array:
$picture = Input::file('picture');
#### Retrieving a specific item from a $_FILES array:
$size = Input::file('picture.size');
<aname="old-input"></a>
## Old Input
You'll commonly need to re-populate forms after invalid form submissions. Laravel's Input class was designed with this problem in mind. Here's an example of how you can easily retrieve the input from the previous request. First, you need to flash the input data to the session:
#### Retrieving a flashed input item from the previous request:
$name = Input::old('name');
> **Note:** You must specify a session driver before using the "old" method.
*Further Reading:*
-*[Sessions](/docs/session/config)*
<aname="redirecting-with-old-input"></a>
## Redirecting With Old Input
Now that you know how to flash input to the session. Here's a shortcut that you can use when redirecting that prevents you from having to micro-manage your old input in that way:
#### Flashing input from a Redirect instance:
return Redirect::to('login')->with_input();
#### Flashing selected input from a Redirect instance:
Laravel provides a nice wrapper around the $_COOKIE array. However, there are a few things you should be aware of before using it. First, all Laravel cookies contain a "signature hash". This allows the framework to verify that the cookie has not been modified on the client. Secondly, when setting cookies, the cookies are not immediately sent to the browser, but are pooled until the end of the request and then sent together. This means that you will not be able to both set a cookie and retrieve the value that you set in the same request.
#### Retrieving a cookie value:
$name = Cookie::get('name');
#### Returning a default value if the requested cookie doesn't exist:
$name = Cookie::get('name', 'Fred');
#### Setting a cookie that lasts for 60 minutes:
Cookie::put('name', 'Fred', 60);
#### Creating a "permanent" cookie that lasts five years:
- Apache, nginx, or another compatible web server.
- Laravel takes advantage of the powerful features that have become available in PHP 5.3. Consequently, PHP 5.3 is a requirement.
- Laravel uses the [FileInfo library](http://php.net/manual/en/book.fileinfo.php) to detect files' mime-types. This is included by default with PHP 5.3. However, Windows users may need to add a line to their php.ini file before the Fileinfo module is enabled. For more information check out the [installation / configuration details on PHP.net](http://php.net/manual/en/fileinfo.installation.php).
- Laravel uses the [Mcrypt library](http://php.net/manual/en/book.mcrypt.php) for encryption and hash generation. Mcrypt typically comes pre-installed. If you can't find Mcrypt in the output of phpinfo() then check the vendor site of your LAMP installation or check out the [installation / configuration details on PHP.net](http://php.net/manual/en/book.mcrypt.php).
<aname="installation"></a>
## Installation
1.[Download Laravel](http://laravel.com/download)
2. Extract the Laravel archive and upload the contents to your web server.
3. Set the value of the **key** option in the **config/application.php** file to a random, 32 character string.
4. Navigate to your application in a web browser.
If all is well, you should see a pretty Laravel splash page. Get ready, there is lots more to learn!
### Extra Goodies
Installing the following goodies will help you take full advantage of Laravel, but they are not required:
- SQLite, MySQL, PostgreSQL, or SQL Server PDO drivers.
- Memcached or APC.
### Problems?
If you are having problems installing, try the following:
- Make sure the **public** directory is the document root of your web server.
- If you are using mod_rewrite, set the **index** option in **application/config/application.php** to an empty string.
<aname="basic-configuration"></a>
## Basic Configuration
All of the configuration provided are located in your applications config/ directory. We recommend that you read through these files just to get a basic understanding of the options available to you. Pay special attention to the **application/config/application.php** file as it contains the basic configuration options for your application.
It's **extremely** important that you change the **application key** option before working on your site. This key is used throughout the framework for encryption, hashing, etc. It lives in the **config/application.php** file and should be set to a random, 32 character string. A standards-compliant application key can be automatically generated using the Artisan command-line utility. More information can be found in the [Artisan command index](/docs/artisan/commands).
> **Note:** If you are using mod_rewrite, you should set the index option to an empty string.
<aname="environments"></a>
## 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:
SetEnv LARAVEL_ENV local
> **Note:** Using a web server other than Apache? Check your server's documentation to learn how to set environment variables.
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:
return array(
'url' => 'http://localhost/laravel/public',
);
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';
<aname="cleaner-urls"></a>
## Cleaner URLs
Most likely, you do not want your application URLs to contain "index.php". You can remove it using HTTP rewrite rules. If you are using Apache to serve your application, make sure to enable mod_rewrite and create a **.htaccess** file like this one in your **public** directory:
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 [L]
</IfModule>
Is the .htaccess file above not working for you? Try this one:
Options +FollowSymLinks
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php [L]
After setting up HTTP rewriting, you should set the **index** configuration option in **application/config/application.php** to an empty string.
> **Note:** Each web server has a different method of doing HTTP rewrites, and may require a slightly different .htaccess file.
An IoC container is simply a way of managing the creation of objects. You can use it to define the creation of complex objects, allowing you to resolve them throughout your application using a single line of code. You may also use it to "inject" dependencies into your classes and controllers.
IoC containers help make your application more flexible and testable. Since you may register alternate implementations of an interface with the container, you may isolate the code you are testing from external dependencies using [stubs and mocks](http://martinfowler.com/articles/mocksArentStubs.html).
<aname="register"></a>
## Registering Objects
#### Registering a resolver in the IoC container:
IoC::register('mailer', function()
{
$transport = Swift_MailTransport::newInstance();
return Swift_Mailer::newInstance($transport);
});
Great! Now we have registered a resolver for SwiftMailer in our container. But, what if we don't want the container to create a new mailer instance every time we need one? Maybe we just want the container to return the same instance after the intial instance is created. Just tell the container the object should be a singleton:
#### Registering a singleton in the container:
IoC::singleton('mailer', function()
{
//
});
You may also register an existing object instance as a singleton in the container.
#### Registering an existing instance in the container:
IoC::instance('mailer', $instance);
<aname="resolve"></a>
## Resolving Objects
Now that we have SwiftMailer registered in the container, we can resolve it using the **resolve** method on the **IoC** class:
$mailer = IoC::resolve('mailer');
> **Note:** You may also [register controllers in the container](/docs/controllers#dependency-injection).
Auto-loading allows you to lazily load class files when they are needed without explicitly *requiring* or *including* them. So, only the classes you actually need are loaded for any given request to your application, and you can just jump right in and start using any class without loading it's related file.
By default, the **models** and **libraries** directories are registered with the auto-loader in the **application/start.php** file. The loader uses a class to file name loading convention, where all file names are lower-cased. So for instance, a "User" class within the models directory should have a file name of "user.php". You may also nest classes within sub-directories. Just namespace the classes to match the directory structure. So, a "Entities\User" class would have a file name of "entities/user.php" within the models directory.
<aname="directories"></a>
## Registering Directories
As noted above, the models and libraries directories are registered with the auto-loader by default; however, you may register any directories you like to use the same class to file name loading conventions:
#### Registering directories with the auto-loader:
Autoloader::directories(array(
path('app').'entities',
path('app').'repositories',
));
<aname="mappings"></a>
## Registering Mappings
Sometimes you may wish to manually map a class to its related file. This is the most performant way of loading classes:
#### Registering a class to file mapping with the auto-loader:
Autoloader::map(array(
'User' => path('app').'models/user.php',
'Contact' => path('app').'models/contact.php',
));
<aname="namespaces"></a>
## Registering Namespaces
Many third-party libraries use the PSR-0 standard for their structure. PSR-0 states that class names should match their file names, and directory structure is indicated by namespaces. If you are using a PSR-0 library, just register it's root namespace and directory with the auto-loader:
#### Registering a namespace with the auto-loader:
Autoloader::namespaces(array(
'Doctrine' => path('libraries').'Doctrine',
));
Before namespaces were available in PHP, many projects used underscores to indicate directory structure. If you are using one of these legacy libraries, you can still easily register it with the auto-loader. For example, if you are using SwiftMailer, you may have noticed all classes begin with "Swift_". So, we'll register "Swift" with the auto-loader as the root of an underscored project.
#### Registering an "underscored" library with the auto-loader:
Localization is the process of translating your application into different languages. The **Lang** class provides a simple mechanism to help you organize and retrieve the text of your multilingual application.
All of the language files for your application live under the **application/language** directory. Within the **application/language** directory, you should create a directory for each language your application speaks. So, for example, if your application speaks English and Spanish, you might create **en** and **sp** directories under the **language** directory.
Each language directory may contain many different language files. Each language file is simply an array of string values in that language. In fact, language files are structured identically to configuration files. For example, within the **application/language/en** directory, you could create a **marketing.php** file that looks like this:
#### Creating a language file:
return array(
'welcome' => 'Welcome to our website!',
);
Next, you should create a corresponding **marketing.php** file within the **application/language/sp** directory. The file would look something like this:
return array(
'welcome' => 'Bienvenido a nuestro sitio web!',
);
Nice! Now you know how to get started setting up your language files and directories. Let's keep localizing!
<aname="basics"></a>
## Retrieving A Language Line
#### Retrieving a language line:
echo Lang::line('marketing.welcome')->get();
#### Retrieving a language line using the "__" helper:
echo __('marketing.welcome');
Notice how a dot was used to separate "marketing" and "welcome"? The text before the dot corresponds to the language file, while the text after the dot corresponds to a specific string within that file.
Need to retrieve the line in a language other than your default? Not a problem. Just mention the language to the **get** method:
#### Getting a language line in a given language:
echo Lang::line('marketing.welcome')->get('sp');
<aname="replace"></a>
## Place Holders & Replacements
Now, let's work on our welcome message. "Welcome to our website!" is a pretty generic message. It would be helpful to be able to specify the name of the person we are welcoming. But, creating a language line for each user of our application would be time-consuming and ridiculous. Thankfully, you don't have to. You can specify "place-holders" within your language lines. Place-holders are preceeded by a colon:
#### Creating a language line with place-holders:
'welcome' => 'Welcome to our website, :name!'
#### Retrieving a language line with replacements:
All of the configuration options regarding errors and logging live in the **application/config/errors.php** file. Let's jump right in.
### Ignored Errors
The **ignore** option contains an array of error levels that should be ignored by Laravel. By "ignored", we mean that we won't stop execution of the script on these errors. However, they will be logged when logging is enabled.
### Error Detail
The **detail** option indicates if the framework should display the error message and stack trace when an error occurs. For development, you will want this to be **true**. However, in a production environment, set this to **false**. When disabled, the view located in **application/views/error/500.php** will be displayed, which contains a generic error message.
<aname="logging"></a>
## Logging
To enable logging, set the **log** option in the error configuration to "true". When enabled, the Closure defined by the **logger** configuration item will be executed when an error occurs. This gives you total flexibility in how the error should be logged. You can even e-mail the errors to your development team!
By default, logs are stored in the **storage/logs** direcetory, and a new log file is created for each day. This keeps your log files from getting crowded with too many messages.
<aname="the-logger-class"></a>
## The Logger Class
Sometimes you may wish to use Laravel's **Log** class for debugging, or just to log informational messages. Here's how to use it:
#### Writing a message to the logs:
Log::write('info', 'This is just an informational message!');
#### Using magic methods to specify the log message type:
Log::info('This is just an informational message!');
Models are the heart of your application. Your application logic (controllers / routes) and views (html) are just the mediums with which users interact with your models. The most typical type of logic contained within a model is [Business Logic](http://en.wikipedia.org/wiki/Business_logic).
*Some examples of functionality that would exist within a model are:*
- Database Interactions
- File I/O
- Interactions with Web Services
For instance, perhaps you are writing a blog. You will likely want to have a "Post" model. Users may want to comment on posts so you'd also have a "Comment" model. If users are going to be commenting then we'll also need a "User" model. Get the idea?
<aname="libraries"></a>
## Libraries
Libraries are classes that perform tasks that aren't specific to your application. For instance, consider a PDF generation library that converts HTML. That task, although complicated, is not specific to your application, so it is considered a "library".
Creating a library is as easy as creating a class and storing it in the libraries folder. In the following example, we will create a simple library with a method that echos the text that is passed to it. We create the **printer.php** file in the libraries folder with the following code.
<?php
class Printer {
public static function write($text) {
echo $text;
}
}
You can now call Printer::write('this text is being echod from the write method!') from anywhere within your application.
<aname="auto-loading"></a>
## Auto Loading
Libraries and Models are very easy to use thanks to the Laravel auto-loader. To learn more about the auto-loader check out the documentation on [Auto-Loading](/docs/loading).
<aname="best-practices"></a>
## Best Practices
We've all head the mantra: "controllers should be thin!" But, how do we apply that in real life? It's possible that part of the problem is the word "model". What does it even mean? Is it even a useful term? Many associate "model" with "database", which leads to having very bloated controllers, with light models that access the database. Let's explore some alternatives.
What if we just totally scrapped the "models" directory? Let's name it something more useful. In fact, let's just give it the same as our application. Perhaps are our satellite tracking site is named "Trackler", so let's create a "trackler" directory within the application folder.
Great! Next, let's break our classes into "entities", "services", and "repositories". So, we'll create each of those three directories within our "trackler" folder. Let's explore each one:
### Entities
Think of entities as the data containers of your application. They primarily just contain properties. So, in our application, we may have a "Location" entity which has "latitude" and "longitude" properties. It could look something like this:
<?php namespace Trackler\Entities;
class Location {
public $latitude;
public $longitude;
public function __construct($latitude, $longitude)
{
$this->latitude = $latitude;
$this->longitude = $longitude;
}
}
Looking good. Now that we have an entity, let's explore our other two folders.
### Services
Services contain the *processes* of your application. So, let's keep using our Trackler example. Our application might have a form on which a user may enter their GPS location. However, we need to validate that the coordinates are correctly formatted. We need to *validate* the *location entity*. So, within our "services" directory, we could create a "validators" folder with the following class:
<?php namespace Trackler\Services\Validators;
use Trackler\Entities\Location;
class Location_Validator {
public static function validate(Location $location)
{
// Validate the location instance...
}
}
Great! Now we have a great way to test our validation in isolation from our controllers and routes! So, we've validated the location and we're ready to store it. What do we do now?
### Repositories
Repositories are the data access layer of your application. They are responsible for storing and retrieving the *entities* of your application. So, let's continue using our *location* entity in this example. We need a location repository that can store them. We could store them using any mechanism we want, whether that is a relational database, Redis, or the next storage hotness. Let's look at an example:
<?php namespace Trackler\Repositories;
use Trackler\Entities\Location;
class Location_Repository {
public function save(Location $location, $user_id)
{
// Store the location for the given user ID...
}
}
Now we have a clean separation of concerns between our application's entities, services, and repositories. This means we can inject stub repositories into our services or controllers, and test those pieces of our application in isolation from the database. Also, we can entirely switch data store technologies without affecting our services, entities, or controllers. We've achieved a good *separation of concerns*.
#### Returning a default value if the segment doesn't exist:
echo URI::segment(10, 'Foo');
#### Getting the full request URI, including query string:
echo URI::full();
Sometimes you may need to determine if the current URI is a given string, or begins with a given string. Here's an example of how you can use the is() method to accomplish this:
#### Determine if the URI is "home":
if (URI::is('home'))
{
// The current URI is "home"!
}
#### Determine if the current URI begins with "docs/":
if URI::is('docs/*'))
{
// The current URI begins with "docs/"!
}
<aname="other-request-helpers"></a>
## Other Request Helpers
#### Getting the current request method:
echo Request::method();
#### Accessing the $_SERVER global array:
echo Request::server('http_referer');
#### Retrieving the requester's IP address:
echo Request::ip();
#### Determining if the current request is using HTTPS:
if (Request::secure())
{
// This request is over HTTPS!
}
#### Determing if the current request is an AJAX request:
if (Request::ajax())
{
// This request is using AJAX!
}
#### Determining if the current requst is via the Artisan CLI:
Laravel uses the latest features of PHP 5.3 to make routing simple and expressive. It's important that building everything from APIs to complex web applications is as easy as possible. Routes are typically defined in **application/routes.php**.
Unlike many other frameworks with Laravel it's possible to embed application logic in two ways. While controllers are the most common way to implement application logic it's also possible to embed your logic directly into routes. This is **especially** nice for small sites that contain only a few pages as you don't have to create a bunch of controllers just to expose half a dozen methods or put a handful of unrelated methods into the same controller and then have to manually designate routes that point to them.
In the following example the first parameter is the route that you're "registering" with the router. The second parameter is the function containing the logic for that route. Routes are defined without a front-slash. The only exception to this is the default route which is represented with **only** a front-slash.
> **Note:** Routes are evaluated in the order that they are registered, so register any "catch-all" routes at the bottom of your **routes.php** file.
#### Registering a route that responds to "GET /":
Route::get('/', function()
{
return "Hello World!";
});
#### Registering a route that is valid for any HTTP verb (GET, POST, PUT, and DELETE):
Route::any('/', function()
{
return "Hello World!";
});
#### Registering routes for other request methods:
Route::post('user', function()
{
//
});
Route::put('user/(:num)', function($id)
{
//
});
Route::delete('user/(:num)', function($id)
{
//
});
**Registering a single URI for multiple HTTP verbs:**
If a request enters your application but does not match any existing route, the 404 event will be raised. You can find the default event handler in your **application/routes.php** file.
#### The default 404 event handler:
Event::listen('404', function()
{
return Response::error('404');
});
You are free to change this to fit the needs of your application!
*Futher Reading:*
-*[Events](/docs/events)*
<aname="filters"></a>
## Filters
Route filters may be run before or after a route is executed. If a "before" filter returns a value, that value is considered the response to the request and the route is not executed, which is conveniont when implementing authentication filters, etc. Filters are typically defined in **application/routes.php**.
Sometimes you may want to attach a filter to all requests that begin with a given URI. For example, you may want to attach the "auth" filter to all requests with URIs that begin with "admin". Here's how to do it:
#### Defining a URI pattern based filter:
Route::filter('pattern: admin/*', 'auth');
<aname="global-filters"></a>
## Global Filters
Laravel has two "global" filters that run **before** and **after** every request to your application. You can find them both in the **application/routes.php** file. These filters make great places to start common bundles or add global assets.
> **Note:** The **after** filter receives the **Response** object for the current request.
<aname="route-groups"></a>
## Route Groups
Route groups allow you to attach a set of attributes to a group of routes, allowing you to keep your code neat and tidy.
Constantly generating URLs or redirects using a route's URI can cause problems when routes are later changed. Assigning the route a name gives you a convenient way to refer to the route throughout your application. When a route change occurs the generated links will point to the new route with no further configuration needed.
#### Registering a named route:
Route::get('/', array('as' => 'home', function()
{
return "Hello World";
}));
#### Generating a URL to a named route:
$url = URL::to_route('home');
#### Redirecting to the named route:
return Redirect::to_route('home');
Once you have named a route, you may easily check if the route handling the current request has a given name.
#### Determine if the route handling the request has a given name:
if (Request::route()->is('home'))
{
// The "home" route is handling the request!
}
<aname="https-routes"></a>
## HTTPS Routes
When defining routes, you may use the "https" attribute to indicate that the HTTPS protocol should be used when generating a URL or Redirect to that route.
Bundles are Laravel's modular package system. Bundles can easily be configured to handle requests to your application. We'll be going over [bundles in more detail](/docs/bundles) in another document. For now, read through this section and just be aware that not only can routes be used to expose functionality in bundles, but they can also be registered from within bundles.
Let's open the **application/bundles.php** file and add something:
#### Registering a bundle to handle routes:
return array(
'admin' => array('handles' => 'admin'),
);
Notice the new **handles** option in our bundle configuration array? This tells Laravel to load the Admin bundle on any requests where the URI begins with "admin".
Now you're ready to register some routes for your bundle, so create a **routes.php** file within the root directory of your bundle and add the following:
#### Registering a root route for a bundle:
Route::get('(:bundle)', function()
{
return 'Welcome to the Admin bundle!';
});
Let's explore this example. Notice the **(:bundle)** place-holder? That will be replaced with the value of the **handles** clause that you used to register your bundle. This keeps your code [D.R.Y.](http://en.wikipedia.org/wiki/Don't_repeat_yourself) and allows those who use your bundle to change it's root URI without breaking your routes! Nice, right?
Of course, you can use the **(:bundle)** place-holder for all of your routes, not just your root route.
#### Registering bundle routes:
Route::get('(:bundle)/panel', function()
{
return "I handle requests to admin/panel!";
});
<aname="controller-routing"></a>
## Controller Routing
Controllers provide another way to manage your application logic. If you're unfamiliar with controllers you may want to [read about controllers](/docs/controllers) and return to this section.
It is important to be aware that all routes in Laravel must be explicitly defined, including routes to controllers. This means that controller methods that have not been exposed through route registration **cannot** be accessed. It's possible to automatically expose all methods within a controller using controller route registration. Controller route registrations are typically defined in **application/routes.php**.
Most likely, you just want to register all of the controllers in your application's "controllers" directory. You can do it in one simple statement. Here's how:
#### Register all controllers for the application:
Route::controller(Controller::detect());
The **Controller::detect** method simply returns an array of all of the controllers defined for the application.
If you wish to automatically detect the controllers in a bundle, just pass the bundle name to the method. If no bundle is specified, the application folder's controller directory will be searched.
#### Register all controllers for the "admin" bundle:
Route::controller(Controller::detect('admin'));
#### Registering the "home" controller with the Router:
Route::controller('home');
#### Registering several controllers with the router:
Once a controller is registered, you may access its methods using a simple URI convention:
http://localhost/controller/method/arguments
This convention is similar to that employed by CodeIgniter and other popular frameworks, where the first segment is the controller name, the second is the method, and the remaining segments are passed to the method as arguments. If no method segment is present, the "index" method will be used.
This routing convention may not be desirable for every situation, so you may also explicitly route URIs to controller actions using a simple, intuitive syntax.
#### Registering a route that points to a controller action:
Route::get('welcome', 'home@index');
#### Registering a filtered route that points to a controller action:
You may test your routes using Laravel's "Artisan" CLI. Simple specify the request method and URI you want to use. The route response will be var_dump'd back to the CLI.
The web is a stateless environment. This means that each request to your application is considered unrelated to any previous request. However, **sessions** allow you to store arbitrary data for each visitor to your application. The session data for each visitor is stored on your web server, while a cookie containing a **session ID** is stored on the visitor's machine. This cookie allows your application to "remember" the session for that user and retrieve their session data on subsequent requests to your application.
> **Note:** Before using sessions, make sure an application key has been specified in the **application/config/application.php** file.
Six session drivers are available out of the box:
- Cookie
- File System
- Database
- Memcached
- Redis
- Memory (Arrays)
<aname="cookie"></a>
## Cookie Sessions
Cookie based sessions provide a light-weight and fast mechanism for storing session information. They are also secure. Each cookie is encrypted using strong AES-256 encryption. However, cookies have a four kilobyte storage limit, so you may wish to use another driver if you are storing a lot of data in the session.
To get started using cookie sessions, just set the driver option in the **application/config/session.php** file:
'driver' => 'cookie'
<aname="file"></a>
## File System Sessions
Most likely, your application will work great using file system sessions. However, if your application receives heavy traffic or runs on a server farm, use database or Memcached sessions.
To get started using file system sessions, just set the driver option in the **application/config/session.php** file:
'driver' => 'file'
That's it. You're ready to go!
> **Note:** File system sessions are stored in the **storage/sessions** directory, so make sure it's writeable.
<aname="database"></a>
## Database Sessions
To start using database sessions, you will first need to [configure your database connection](/docs/database/config).
Next, you will need to create a session table. Below are some SQL statements to help you get started. However, you may also use Laravel's "Artisan" command-line to generate the table for you!
### Artisan
php artisan session:table
### SQLite
CREATE TABLE "sessions" (
"id" VARCHAR PRIMARY KEY NOT NULL UNIQUE,
"last_activity" INTEGER NOT NULL,
"data" TEXT NOT NULL
);
### MySQL
CREATE TABLE `sessions` (
`id` VARCHAR(40) NOT NULL,
`last_activity` INT(10) NOT NULL,
`data` TEXT NOT NULL,
PRIMARY KEY (`id`)
);
If you would like to use a different table name, simply change the **table** option in the **application/config/session.php** file:
'table' => 'sessions'
All you need to do now is set the driver in the **application/config/session.php** file:
'driver' => 'database'
<aname="memcached"></a>
## Memcached Sessions
Before using Memcached sessions, you must [configure your Memcached servers](/docs/database/config#memcached).
Just set the driver in the **application/config/session.php** file:
'driver' => 'memcached'
<aname="redis"></a>
## Redis Sessions
Before using Redis sessions, you must [configure your Redis servers](/docs/database/redis#config).
Just set the driver in the **application/config/session.php** file:
'driver' => 'redis'
<aname="memory"></a>
## In-Memory Sessions
The "memory" session driver just uses a simple array to store your session data for the current request. This driver is perfect for unit testing your application since nothing is written to disk. It shouldn't ever be used as a "real" session driver.
To store items in the session call the put method on the Session class:
Session::put('name', 'Taylor');
The first parameter is the **key** to the session item. You will use this key to retrieve the item from the session. The second parameter is the **value** of the item.
The **flash** method stores an item in the session that will expire after the next request. It's useful for storing temporary data like status or error messages:
Session::flash('status', 'Welcome Back!');
<aname="get"></a>
## Retrieving Items
You can use the **get** method on the Session class to retrieve any item in the session, including flash data. Just pass the key of the item you wish to retrieve:
$name = Session::get('name');
By default, NULL will be returned if the session item does not exist. However, you may pass a default value as a second parameter to the get method:
Now, "Fred" will be returned if the "name" item does not exist in the session.
Laravel even provides a simple way to determine if a session item exists using the **has** method:
if (Session::has('name'))
{
$name = Session::get('name');
}
<aname="forget"></a>
## Removing Items
To remove an item from the session use the **forget** method on the Session class:
Session::forget('name');
You can even remove all of the items from the session using the **flush** method:
Session::flush();
<aname="regeneration"></a>
## Regeneration
Sometimes you may want to "regenerate" the session ID. This simply means that a new, random session ID will be assigned to the session. Here's how to do it:
The **Str** class also provides three convenient methods for manipulating string capitalization: **upper**, **lower**, and **title**. These are more intelligent versions of the PHP [strtoupper](http://php.net/manual/en/function.strtoupper.php), [strtolower](http://php.net/manual/en/function.strtolower.php), and [ucwords](http://php.net/manual/en/function.ucwords.php) methods. More intelligent because they can handle UTF-8 input if the [multi-byte string](http://php.net/manual/en/book.mbstring.php) PHP extension is installed on your web server. To use them, just pass a string to the method:
echo Str::lower('I am a string.');
echo Str::upper('I am a string.');
echo Str::title('I am a string.');
<aname="limits"></a>
## Word & Character Limiting
#### Limiting the number of characters in a string:
echo Str::limit($string, 10);
#### Limiting the number of words in a string:
echo Str::words($string, 10);
<aname="random"></a>
## Generating Random Strings
#### Generating a random string of alpha-numeric characters:
echo Str::random(32);
#### Generating a random string of alphabetic characters:
echo Str::random(32, 'alpha');
<aname="singular-and-plural"></a>
## Singular & Plural
The String class is capable of transforming your strings from singular to plural, and vice versa.
#### Getting the plural form of a word:
echo Str::plural('user');
#### Getting the singular form of a word:
echo Str::singular('users');
#### Getting the plural form if given value is greater than one:
echo Str::plural('comment', count($comments));
<aname="slugs"></a>
## Slugs
#### Generating a URL friendly slug:
return Str::slug('My First Blog Post!');
#### Generating a URL friendly slug using a given separator:
-[Calling Controllers From Tests](#calling-controllers-from-tests)
<aname="the-basics"></a>
## The Basics
Unit Testing allows you to test your code and verify that it is working correctly. In fact, many advocate that you should even write your tests before you write your code! Laravel provides beautiful integration with the popular [PHPUnit](http://www.phpunit.de/manual/current/en/) testing library, making it easy to get started writing your tests. In fact, the Laravel framework itself has hundreds of unit tests!
<aname="creating-test-classes"></a>
## Creating Test Classes
All of your application's tests live in the **application/tests** directory. In this directory, you will find a basic **example.test.php** file. Pop it open and look at the class it contains:
<?php
class TestExample extends PHPUnit_Framework_TestCase {
/**
* Test that a given condition is met.
*
* @return void
*/
public function testSomethingIsTrue()
{
$this->assertTrue(true);
}
}
Take special note of the **.test.php** file suffix. This tells Laravel that it should include this class as a test case when running your test. Any files in the test directory that are not named with this suffix will not be considered a test case.
If you are writing tests for a bundle, just place them in a **tests** directory within the bundle. Laravel will take care of the rest!
For more information regarding creating test cases, check out the [PHPUnit documentation](http://www.phpunit.de/manual/current/en/).
<aname="running-tests"></a>
## Running Tests
To run your tests, you can use Laravel's Artisan command-line utility:
#### Running the application's tests via the Artisan CLI:
php artisan test
#### Running the unit tests for a bundle:
php artisan test bundle-name
<aname="#calling-controllers-from-tests"></a>
## Calling Controllers From Tests
Here's an example of how you can call your controllers from your tests:
-[URLs To Controller Actions](#urls-to-controller-actions)
-[URLs To Assets](#urls-to-assets)
-[URL Helpers](#url-helpers)
<aname="the-basics"></a>
## The Basics
#### Retrieving the application's base URL:
$url = URL::base();
#### Generating a URL relative to the base URL:
$url = URL::to('user/profile');
#### Generating a HTTPS URL:
$url = URL::to_secure('user/login');
#### Retrieving the current URL:
$url = URL::current();
#### Retrieving the current URL including query string:
$url = URL::full();
<aname="urls-to-routes"></a>
## URLs To Routes
#### Generating a URL to a named route:
$url = URL::to_route('profile');
Sometimes you may need to generate a URL to a named route, but also need to specify the values that should be used instead of the route's URI wildcards. It's easy to replace the wildcards with proper values:
#### Generating a URL to a named route with wildcard values:
Almost every interactive web application needs to validate data. For instance, a registration form probably requires the password to be confirmed. Maybe the e-mail address must be unique. Validating data can be a cumbersome process. Thankfully, it isn't in Laravel. The Validator class provides as awesome array of validation helpers to make validating your data a breeze. Let's walk through an example:
#### Get an array of data you want to validate:
$input = Input::all();
#### Define the validation rules for your data:
$rules = array(
'name' => 'required|max:50',
'email' => 'required|email|unique:users',
);
#### Create a Validator instance and validate the data:
$validation = Validator::make($input, $rules);
if ($validation->fails())
{
return $validation->errors;
}
With the *errors* property, you can access a simple message collector class that makes working with your error messages a piece of cake. Of course, default error messages have been setup for all validation rules. The default messages live at **language/en/validation.php**.
Now you are familiar with the basic usage of the Validator class. You're ready to dig in and learn about the rules you can use to validate your data!
#### Validate that an attribute is present and is not an empty string:
'name' => 'required'
<aname="rule-alpha"></a>
### Alpha, Alpha Numeric, & Alpha Dash
#### Validate that an attribute consists solely of letters:
'name' => 'alpha'
#### Validate that an attribute consists of letters and numbers:
'username' => 'alpha_num'
#### Validate that an attribute only contains letters, numbers, dashes, or underscores:
'username' => 'alpha_dash'
<aname="rule-size"></a>
### Size
#### Validate that an attribute is a given length, or, if an attribute is numeric, is a given value:
'name' => 'size:10'
#### Validate that an attribute size is within a given range:
'payment' => 'between:10,50'
> **Note:** All minimum and maximum checks are inclusive.
#### Validate that an attribute is at least a given size:
'payment' => 'min:10'
#### Validate that an attribute is no greater than a given size:
'payment' => 'max:50'
<aname="rule-numeric"></a>
### Numeric
#### Validate that an attribute is numeric:
'payment' => 'numeric'
#### Validate that an attribute is an integer:
'payment' => 'integer'
<aname="rule-in"></a>
### Inclusion & Exclusion
#### Validate that an attribute is contained in a list of values:
'size' => 'in:small,medium,large'
#### Validate that an attribute is not contained in a list of values:
'language' => 'not_in:cobol,assembler'
<aname="rule-confirmation"></a>
### Confirmation
The *confirmed* rule validates that, for a given attribute, a matching *attribute_confirmation* attribute exists.
#### Validate that an attribute is confirmed:
'password' => 'confirmed'
Given this example, the Validator will make sure that the *password* attribute matches the *password_confirmation* attribute in the array being validated.
<aname="rule-acceptance"></a>
### Acceptance
The *accepted* rule validates that an attribute is equal to *yes* or *1*. This rule is helpful for validating checkbox form fields such as "terms of service".
#### Validate that an attribute is accepted:
'terms' => 'accepted'
<aname="same-and-different"></a>
## Same & Different
#### Validate that an attribute matches another attribute:
'token1' => 'same:token2'
#### Validate that two attributes have different values:
'password' => 'different:old_password',
<aname="regex-match"></a>
### Regular Expression Match
The *match* rule validates that an attribute matches a given regular expression.
#### Validate that an attribute matches a regular expression:
'username' => 'match:/[a-z]+/';
<aname="rule-unique"></a>
### Uniqueness & Existence
#### Validate that an attribute is unique on a given database table:
'email' => 'unique:users'
In the example above, the *email* attribute will be checked for uniqueness on the *users* table. Need to verify uniqueness on a column name other than the attribute name? No problem:
#### Specify a custom column name for the unique rule:
'email' => 'unique:users,email_address'
Many times, when updating a record, you want to use the unique rule, but exclude the row being updated. For example, when updating a user's profile, you may allow them to change their e-mail address. But, when the *unique* rule runs, you want it to skip the given user since they may not have changed their address, thus causing the *unique* rule to fail. It's easy:
#### Forcing the unique rule to ignore a given ID:
'email' => 'unique:users,email_address,10'
#### Validate that an attribute exists on a given database table:
'state' => 'exists:states'
#### Specify a custom column name for the exists rule:
'state' => 'exists:states,abbreviation'
<aname="dates"></a>
### Dates
#### Validate that a date attribute is before a given date:
'birthdate' => 'before:1986-28-05';
#### Validate that a date attribute is after a given date:
'birthdate' => 'after:1986-28-05';
> **Note:** The **before** and **after** validation rules use the **strtotime** PHP function to convert your date to something the rule can understand.
<aname="rule-email"></a>
### E-Mail Addresses
#### Validate that an attribute is an e-mail address:
'address' => 'email'
> **Note:** This rule uses the PHP built-in *filter_var* method.
<aname="rule-url"></a>
### URLs
#### Validate that an attribute is a URL:
'link' => 'url'
#### Validate that an attribute is an active URL:
'link' => 'active_url'
> **Note:** The *active_url* rule uses *checkdnsr* to verify the URL is active.
<aname="rule-uploads"></a>
### Uploads
The *mimes* rule validates that an uploaded file has a given MIME type. This rule uses the PHP Fileinfo extension to read the contents of the file and determine the actual MIME type. Any extension defined in the *config/mimes.php* file may be passed to this rule as a parameter:
#### Validate that a file is one of the given types:
'picture' => 'mimes:jpg,gif'
> **Note:** When validating files, be sure to use Input::file() or Input::all() to gather the input.
#### Validate that a file is an image:
'picture' => 'image'
#### Validate that a file is no more than a given size in kilobytes:
'picture' => 'image|max:100'
<aname="retrieving-error-messages"></a>
## Retrieving Error Messages
Laravel makes working with your error messages a cinch using a simple error collector class. After calling the *passes* or *fails* method on a Validator instance, you may access the errors via the *errors* property. The error collector has several simple functions for retrieving your messages:
#### Determine if an attribute has an error message:
if ($validation->errors->has('email'))
{
// The e-mail attribute has errors...
}
#### Retrieve the first error message for an attribute:
echo $validation->errors->first('email');
Sometimes you may need to format the error message by wrapping it in HTML. No problem. Along with the :message place-holder, pass the format as the second parameter to the method.
Once you have performed your validation, you need an easy way to get the errors back to the view. Laravel makes it amazingly simple. Let's walk through a typical scenario. We'll define two routes:
Great! So, we have two simple registration routes. One to handle displaying the form, and one to handle the posting of the form. In the POST route, we run some validation over the input. If the validation fails, we redirect back to the registration form and flash the validation errors to the session so they will be available for us to display.
**But, notice we are not explicitly binding the errors to the view in our GET route**. However, an errors variable will still be available in the view. Laravel intelligently determines if errors exist in the session, and if they do, binds them to the view for you. If no errors exist in the session, an empty message container will still be bound to the view. In your views, this allows you to always assume you have a message container available via the errors variable. We love making your life easier.
<aname="custom-error-messages"></a>
## Custom Error Messages
Want to use an error message other than the default? Maybe you even want to use a custom error message for a given attribute and rule. Either way, the Validator class makes it easy.
#### Create an array of custom messages for the Validator:
$messages = array(
'required' => 'The :attribute field is required.',
Great! Now our custom message will be used anytime a required validation check fails. But, what is this **:attribute** stuff in our message? To make your life easier, the Validator class will replace the **:attribute** place-holder with the actual name of the attribute! It will even remove underscores from the attribute name.
You may also use the **:other**, **:size**, **:min**, **:max**, and **:values** place-holders when constructing your error messages:
#### Other validation message place-holders:
$messages = array(
'same' => 'The :attribute and :other must match.',
'size' => 'The :attribute must be exactly :size.',
'between' => 'The :attribute must be between :min - :max.',
'in' => 'The :attribute must be one of the following types: :values',
);
So, what if you need to specify a custom required message, but only for the email attribute? No problem. Just specify the message using an **attribute_rule** naming convention:
#### Specifying a custom error message for a given attribute:
$messages = array(
'email_required' => 'We need to know your e-mail address!',
);
In the example above, the custom required message will be used for the email attribute, while the default message will be used for all other attributes.
However, if you are using many custom error messages, specifying inline may become cumbersome and messy. For that reason, you can specify your custom messages in the **custom** array within the validation language file:
#### Adding custom error messages to the validation langauge file:
'custom' => array(
'email_required' => 'We need to know your e-mail address!',
)
<aname="custom-validation-rules"></a>
## Custom Validation Rules
Laravel provides a number of powerful validation rules. However, it's very likely that you'll need to eventually create some of your own. There are two simple methods for creating validation rules. Both are solid so use whichever you think best fits your project.
In this example we're registering a new validation rule with the validator. The rule receives three arguments. The first is the name of the attribute being validated, the second is the value of the attribute being validated, and the third is an array of parameters that were specified for the rule.
Here is how your custom validation rule looks when called:
$rules = array(
'username' => 'required|awesome',
);
Of course, you will need to define an error message for your new rule. You can do this either in an ad-hoc messages array:
$messages = array(
'awesome' => 'The attribute value must be awesome!',
In this case, the parameters argument of your validation rule would receive an array containing one element: "yes".
Another method for creating and storing custom validation rules is to extend the Validator class itself. By extending the class you create a new version of the validator that has all of the pre-existing functionality combined with your own custom additions. You can even choose to replace some of the default methods if you'd like. Let's look at an example:
First, create a class that extends **Laravel\Validator** and place it in your **application/libraries** directory:
#### Defining a custom validator class:
<?php
class Validator extends Laravel\Validator {}
Next, remove the Validator alias from **config/application.php**. This is necessary so that you don't end up with 2 classes named "Validator" which will certainly conflict with one another.
Next, let's take our "awesome" rule and define it in our new class:
#### Adding a custom validation rule:
<?php
class Validator extends Laravel\Validator {
public function validate_awesome($attribute, $value, $parameters)
{
return $value == 'awesome';
}
}
Notice that the method is named using the **validate_rule** naming convention. The rule is named "awesome" so the method must be named "validate_awesome". This is one way in which registering your custom rules and extending the Validator class are different. Validator classes simply need to return true or false. That's it!
Keep in mind that you'll still need to create a custom message for any validation rules that you create. The method for doing so is the same no matter how you define your rule!
The **Asset** class provides a simple way to manage the CSS and JavaScript used by your application. To register an asset just call the **add** method on the **Asset** class:
#### Registering an asset:
Asset::add('jquery', 'js/jquery.js');
The **add** method accepts three parameters. The first is the name of the asset, the second is the path to the asset relative to the **public** directory, and the third is a list of asset dependencies (more on that later). Notice that we did not tell the method if we were registering JavaScript or CSS. The **add** method will use the file extension to determine the type of file we are registering.
<aname="dumping-assets"></a>
## Dumping Assets
When you are ready to place the links to the registered assets on your view, you may use the **styles** or **scripts** methods:
#### Dumping assets into a view:
<head>
<?php echo Asset::styles(); ?>
<?php echo Asset::scripts(); ?>
</head>
<aname="asset-dependencies"></a>
## Asset Dependencies
Sometimes you may need to specify that an asset has dependencies. This means that the asset requires other assets to be declared in your view before it can be declared. Managing asset dependencies couldn't be easier in Laravel. Remember the "names" you gave to your assets? You can pass them as the third parameter to the **add** method to declare dependencies:
In this example, we are registering the **jquery-ui** asset, as well as specifying that it is dependent on the **jquery** asset. Now, when you place the asset links on your views, the jQuery asset will always be declared before the jQuery UI asset. Need to declare more than one dependency? No problem:
#### Registering an asset that has multiple dependencies:
To increase response time, it is common to place JavaScript at the bottom of HTML documents. But, what if you also need to place some assets in the head of your document? No problem. The asset class provides a simple way to manage asset **containers**. Simply call the **container** method on the Asset class and mention the container name. Once you have a container instance, you are free to add any assets you wish to the container using the same syntax you are used to:
#### Retrieving an instance of an asset container:
Before learning how to conveniently add and dump bundle assets, you may wish to read the documentation on [creating and publishing bundle assets](/docs/bundles#bundle-assets).
When registering assets, the paths are typically relative to the **public** directory. However, this is inconvenient when dealing with bundle assets, since they live in the **public/bundles** directory. But, remember, Laravel is here to make your life easier. So, it is simple to specify the bundle which the Asset container is managing.
#### Specifying the bundle the asset container is managing:
Asset::container('foo')->bundle('admin');
Now, when you add an asset, you can use paths relative to the bundle's public directory. Laravel will automatically generate the correct full paths.
Laravel provides an easy method of protecting your application from cross-site request forgeries. First, a random token is placed in your user's session. Don't sweat it, this is done automatically. Next, use the token method to generate a hidden form input field containing the random token on your form:
#### Generating a hidden field containing the session's CSRF token:
> **Note:** After creating a label, any form element you create with a name matching the label name will automatically receive an ID matching the label name as well.
<aname="text"></a>
## Text, Text Area, Password & Hidden Fields
#### Generate a text input element:
echo Form::text('username');
#### Specifying a default value for a text input element:
echo Form::text('email', 'example@gmail.com');
> **Note:** The *hidden* and *textarea* methods have the same signature as the *text* method. You just learned three methods for the price of one!
#### Generating a password input element:
echo Form::password('password');
<aname="checkboxes-and-radio-buttons"></a>
## Checkboxes and Radio Buttons
#### Generating a checkbox input element:
echo Form::checkbox('name', 'value');
#### Generating a checkbox that is checked by default:
echo Form::checkbox('name', 'value', true);
> **Note:** The *radio* method has the same signature as the *checkbox* method. Two for one!
<aname="drop-down-lists"></a>
## Drop-Down Lists
#### Generating a drop-down list from an array of items:
> **Note:** Need to create a button element? Try the *button* method. It has the same signature as *submit*.
<aname="custom-macros"></a>
## Custom Macros
It's easy to define your own custom Form class helpers called "macros". Here's how it works. First, simply register the macro with a given name and a Closure:
-[Redirecting With Flash Data](#redirecting-with-flash-data)
-[Downloads](#downloads)
-[Errors](#errors)
<aname="the-basics"></a>
## The Basics
Views contain the HTML that is sent to the person using your application. By separating your view from the business logic of your application, your code will be cleaner and easier to maintain.
All views are stored within the **application/views** directory and use the PHP file extension. The **View** class provides a simple way to retrieve your views and return them to the client. Let's look at an example!
#### Creating the view:
<html>
I'm stored in views/home/index.php!
</html>
#### Returning the view from a route:
Route::get('/', function()
{
return View::make('home.index');
});
#### Returning the view from a controller:
public function action_index()
{
return View::make('home.index');
});
Sometimes you will need a little more control over the response sent to the browser. For example, you may need to set a custom header on the response, or change the HTTP status code. Here's how:
#### Returning a custom response containing a view:
return Response::view('home', 200, $headers);
<aname="binding-data-to-views"></a>
## Binding Data To Views
Typically, a route or controller will request data from a model that the view needs to display. So, we need a way to pass the data to the view. There are several ways to accomplish this, so just pick the way that you like best!
#### Binding data to a view:
Route::get('/', function()
{
return View::make('home')->with('name', 'James');
});
#### Accessing the bound data within a view:
<html>
Hello, <?php echo $name; ?>.
</html>
#### Chaining the binding of data to a view:
View::make('home')
->with('name', 'James')
->with('votes', 25);
#### Passing an array of data to bind data:
View::make('home', array('name' => 'James'));
#### Using magic methods to bind data:
$view->name = 'James';
$view->email = 'example@example.com';
#### Using the ArrayAccess interface methods to bind data:
$view['name'] = 'James';
$view['email'] = 'example@example.com';
<aname="nesting-views"></a>
## Nesting Views
Often you will want to nest views within views. Nested views are sometimes called "partials", and help you keep views small and modular.
#### Binding a nested view using the "nest" method:
Sometimes you may wish to directly include a view from within another view. You can use the **render** helper function:
#### Using the "render" helper to display a view:
<div class="content">
<?php echo render('user.profile'); ?>
</div>
It is also very common to have a partial view that is responsible for display an instance of data in a list. For example, you may create a partial view responsible for displaying the details about a single order. Then, for example, you may loop through an array of orders, rendering the partial view for each order. This is made simpler using the **render_each** helper:
#### Rendering a partial view for each item in an array:
The first argument is the name of the partial view, the second is the array of data, and the third is the variable name that should be used when each array item is passed to the partial view.
<aname="named-views"></a>
## Named Views
Named views can help to make your code more expressive and organized. Using them is simple:
Each time a view is created, its "composer" event will be fired. You can listen for this event and use it to bind assets and common data to the view each time it is created. A common use-case for this functionality is a side-navigation partial that shows a list of random blog posts. You can nest your partial view by loading it in your layout view. Then, define a composer for that partial. The composer can then query the posts table and gather all of the necessary data to render your view. No more random logic strewn about! Composers are typically defined in **application/routes.php**. Here's an example:
#### Register a view composer for the "home" view:
View::composer('home', function($view)
{
$view->nest('footer', 'partials.footer');
});
Now each time the "home" view is created, an instance of the View will be passed to the registered Closure, allowing you to prepare the view however you wish.
> **Note:** A view can have more than one composer. Go wild!
<aname="redirects"></a>
## Redirects
It's important to note that both routes and controllers require responses to be returned with the 'return' directive. Instead of calling "Redirect::to()"" where you'd like to redirect the user. You'd instead use "return Redirect::to()". This distinction is important as it's different than most other PHP frameworks and it could be easy to accidentally overlook the importance of this practice.
#### Redirecting to another URI:
return Redirect::to('user/profile');
#### Redirecting with a specific status:
return Redirect::to('user/profile', 301);
#### Redirecting to a secure URI:
return Redirect::to_secure('user/profile');
#### Redirecting to the root of your application:
return Redirect::home();
#### Redirecting back to the previous action:
return Redirect::back();
#### Redirecting to a named route:
return Redirect::to_route('profile');
#### Redirecting to a controller action:
return Redirect::to_action('home@index');
Sometimes you may need to redirect to a named route, but also need to specify the values that should be used instead of the route's URI wildcards. It's easy to replace the wildcards with proper values:
#### Redirecting to a named route with wildcard values:
After a user creates an account or signs into your application, it is common to display a welcome or status message. But, how can you set the status message so it is available for the next request? Use the with() method to send flash data along with the redirect response.
To generating proper error responses simply specify the response code that you wish to return. The corresponding view stored in **views/error** will automatically be returned.
-[Scripts And Style Sheets](#scripts-and-style-sheets)
-[Links](#links)
-[Links To Named Routes](#links-to-named-routes)
-[Links To Controller Actions](#links-to-controller-actions)
-[Mail-To Links](#mail-to-links)
-[Images](#images)
-[Lists](#lists)
-[Custom Macros](#custom-macros)
<aname="entities"></a>
## Entities
When displaying user input in your Views, it is important to convert all characters which have signifance in HTML to their "entity" representation.
For example, the < symbol should be converted to its entity representation. Converting HTML characters to their entity representation helps protect your application from cross-site scripting:
#### Converting a string to its entity representation:
It's easy to define your own custom HTML class helpers called "macros". Here's how it works. First, simply register the macro with a given name and a Closure:
All pagination link elements can be style using CSS classes. Here is an example of the HTML elements generated by the links method:
<div class="pagination">
<a href="foo" class="previous_page">Previous</a>
<a href="foo">1</a>
<a href="foo">2</a>
<span class="dots">...</span>
<a href="foo">11</a>
<a href="foo">12</a>
<span class="current">13</span>
<a href="foo">14</a>
<a href="foo">15</a>
<span class="dots">...</span>
<a href="foo">25</a>
<a href="foo">26</a>
<a href="foo" class="next_page">Next</a>
</div>
When you are on the first page of results, the "Previous" link will be disabled. Likewise, the "Next" link will be disabled when you are on the last page of results. The generated HTML will look like this:
Your application probably uses a common layout across most of its pages. Manually creating this layout within every controller action can be a pain. Specifying a controller layout will make your develompent much more enjoyable. Here's how to get started:
#### Specify a "layout" property on your controller:
class Base_Controller extends Controller {
public $layout = 'layouts.common';
}
#### Access the layout from the controllers' action:
public function action_profile()
{
$this->layout->nest('content', 'user.profile');
}
> **Note:** When using layouts, actions do not need to return anything.
<aname="sections"></a>
## Sections
View sections provide a simple way to inject content into layouts from nested views. For example, perhaps you want to inject a nested view's needed JavaScript into the header of your layout. Let's dig in:
#### Creating a section within a view:
<?php Section::start('scripts'); ?>
<script src="jquery.js"></script>
<?php Section::stop(); ?>
#### Rendering the contents of a section:
<head>
<?php echo Section::yield('scripts'); ?>
</head>
#### Using Blade short-cuts to work with sections:
@section('scripts')
<script src="jquery.js"></script>
@endsection
<head>
@yield('scripts')
</head>
<aname="blade-template-engine"></a>
## Blade Template Engine
Blade makes writing your views pure bliss. To create a blade view, simply name your view file with a ".blade.php" extension. Blade allows you to use beautiful, unobtrusive syntax for writing PHP control structures and echoing data. Here's an example:
#### Echoing a variable using Blade:
Hello, {{$name}}.
#### Rendering a view:
<h1>Profile</hi>
@include('user.profile')
> **Note:** When using the **@include** Blade expression, the view will automatically inherit all of the current view data.
#### Creating loops using Blade:
<h1>Comments</h1>
@foreach ($comments as $comment)
The comment body is {{$comment->body}}.
@endforeach
#### Other Blade control structures:
@if (count($comments) > 0)
I have comments!
@else
I have no comments!
@endif
@for ($i =0; $i < count($comments) - 1; $i++)
The comment body is {{$comments[$i]}}
@endfor
@while ($something)
I am still looping!
@endwhile
#### The "for-else" control structure:
@forelse ($posts as $post)
{{ $post->body }}
@empty
There are not posts in the array!
@endforelse
<aname="blade-layouts"></a>
## Blade Layouts
Not only does Blade provide clean, elegant syntax for common PHP control structures, it also gives you a beautiful method of using layouts for your views. For example, perhaps your application uses a "master" view to provide a common look and feel for your application. It may look something like this:
<html>
<ul class="navigation">
@section('navigation')
<li>Nav Item 1</li>
<li>Nav Item 2</li>
@yield_section
</ul>
<div class="content">
@yield('content')
</div>
</html>
Notice the "content" section being yielded. We need to fill this section with some text, so let's make another view that uses this layout:
@layout('master')
@section('content')
Welcome to the profile page!
@endsection
Great! Now, we can simply return the "profile" view from our route:
return View::make('profile');
The profile view will automatically use the "master" template thanks to Blade's **@layout** expression.
Sometimes you may want to only append to a section of a layout rather than overwrite it. For example, consider the navigation list in our "master" layout. Let's assume we just want to append a new list item. Here's how to do it:
@layout('master')
@section('navigation')
@parent
<li>Nav Item 3</li>
@endsection
@section('content')
Welcome to the profile page!
@endsection
Notice the **@parent** Blade construct? It will be replaced with the contents of the layout's navigation section, providing you with a beautiful and powerful method of performing layout extension and inheritance.
