@yield('content') diff --git a/laravel/view.php b/laravel/view.php index 4219c56d..50d7a4d5 100644 --- a/laravel/view.php +++ b/laravel/view.php @@ -356,7 +356,7 @@ protected function load() } else { - return static::$cache[$this->path] = include $this->path; + return static::$cache[$this->path] = file_get_contents($this->path); } } diff --git a/storage/documentation/artisan/commands.md b/storage/documentation/artisan/commands.md new file mode 100644 index 00000000..997e86ce --- /dev/null +++ b/storage/documentation/artisan/commands.md @@ -0,0 +1,102 @@ +# Artisan Commands + +## Contents + +- [Application Configuration](#application-configuration) +- [Sessions](#sessions) +- [Migrations](#migrations) +- [Bundles](#bundles) +- [Tasks](#tasks) +- [Unit Tests](#unit-tests) +- [Routing](#routing) +- [Application Keys](#keys) +- [CLI Options](#cli-options) + + +## Application Configuration [(More Information)](/docs/install#basic-configuration) + +Description | Command +------------- | ------------- +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` + + +## Database Sessions [(More Information)](/docs/session/config#database) + +Description | Command +------------- | ------------- +Create a session table | `php artisan session:table` + + +## Migrations [(More Information)](/docs/database/migrations) + +Description | Command +------------- | ------------- +Create the Laravel migration table | `php artisan migrate:install` +Creating a migration | `php artisan migrate:make create_users_table` +Creating a migration for a bundle | `php artisan migrate:make bundle::tablename` +Running outstanding migrations | `php artisan migrate` +Running outstanding migrations in the application | `php artisan migrate application` +Running all outstanding migrations in a bundle | `php artisan migrate bundle` +Rolling back the last migration operation | `php artisan migrate:rollback` +Roll back all migrations that have ever run | `php artisan migrate:reset` + + +## Bundles [(More Information)](/docs/bundles) + +Description | Command +------------- | ------------- +Install a bundle | `php artisan bundle:install eloquent` +Upgrade a bundle | `php artisan bundle:upgrade eloquent` +Upgrade all bundles | `php artisan bundle:upgrade` +Publish a bundle assets | `php artisan bundle:publish bundle_name` +Publish all bundles assets | `php artisan bundle:publish` + +
+> **Note:** After installing you need to [register the bundle](../bundles/#registering-bundles) + + +## Tasks [(More Information)](/docs/artisan/tasks) + +Description | Command +------------- | ------------- +Calling a task | `php artisan notify` +Calling a task and passing arguments | `php artisan notify taylor` +Calling a specific method on a task | `php artisan notify:urgent` +Running a task on a bundle | `php artisan admin::generate` +Running a specific method on a bundle | `php artisan admin::generate:list` + + +## Unit Tests [(More Information)](/docs/testing) + +Description | Command +------------- | ------------- +Running the application tests | `php artisan test` +Running the bundle tests | `php artisan test bundle-name` + + +## Routing [(More Information)](/docs/routing) + +Description | Command +------------- | ------------- +Calling a route | `php artisan route:call get api/user/1` + +
+> **Note:** You can replace get with post, put, delete, etc. + + +## Application Keys + +Description | Command +------------- | ------------- +Generate an application key | `php artisan key:generate` + +
+> **Note:** You can specify an alternate key length by adding an extra argument to the command. + + +## CLI Options + +Description | Command +------------- | ------------- +Setting the Laravel environment | `php artisan foo --env=local` +Setting the default database connection | `php artisan foo --database=sqlitename` diff --git a/storage/documentation/artisan/tasks.md b/storage/documentation/artisan/tasks.md new file mode 100644 index 00000000..08e6606c --- /dev/null +++ b/storage/documentation/artisan/tasks.md @@ -0,0 +1,100 @@ +# Tasks + +## Contents + +- [The Basics](#the-basics) +- [Creating & Running Tasks](#creating-tasks) +- [Bundle Tasks](#bundle-tasks) +- [CLI Options](#cli-options) + + +## The Basics + +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. + + +## 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 + + +## 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: + + php artisan admin::generate:list + + +## CLI Options + +#### Setting the Laravel environment: + + php artisan foo --env=local + +#### Setting the default database connection: + + php artisan foo --database=sqlite \ No newline at end of file diff --git a/storage/documentation/auth/config.md b/storage/documentation/auth/config.md new file mode 100644 index 00000000..dbeed52d --- /dev/null +++ b/storage/documentation/auth/config.md @@ -0,0 +1,56 @@ +# Auth Configuration + +## Contents + +- [The Basics](#the-basics) +- [The User Function](#user) +- [The Attempt Function](#attempt) +- [The Logout Function](#logout) + + +## The Basics + +Most interactive applications have the ability for users to login and logout. Laravel provides a simple class to help you validate user credentials and retrieve information about the current user of your application. + +To get started, let's look over the **application/config/auth.php** file. The authentication configuration contains three functions: **user**, **attempt**, and **logout**. Let's go over each one individually. + + +## 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**. + + +## 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: + + 'attempt' => function($username, $password) + { + $user = DB::table('users')->where_username($username)->first(); + + if ( ! is_null($user) and Hash::check($password, $user->password)) + { + return $user; + } + } + +Like the previous example, the fluent query builder is used to retrieve the user out of the database by the given username. If the user is found, the given password is hashed and compared against the hashed password stored on the table, and if the passwords match, the user model is returned. If the credentials are invalid or the user does not exist, **null** should be returned. + +> **Note:** Any object may be returned by this function as long as it has an **id** property. + + +## The "Logout" Function + +The **logout** function is called whenever a user is logged out of your application. This function gives you a convenient location to interact with any third-party authentication providers you may be using. \ No newline at end of file diff --git a/storage/documentation/auth/usage.md b/storage/documentation/auth/usage.md new file mode 100644 index 00000000..677432cb --- /dev/null +++ b/storage/documentation/auth/usage.md @@ -0,0 +1,89 @@ +# Authentication Usage + +## Contents + +- [Salting & Hashing](#hash) +- [Logging In](#login) +- [Protecting Routes](#filter) +- [Retrieving The Logged In User](#user) +- [Logging Out](#logout) + +> **Note:** Before using the Auth class, you must [specify a session driver](/docs/session/config). + + +## 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!'; + } + + +## 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); + + +## 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: + + Route::get('admin', array('before' => 'auth', function() {}); + +> **Note:** You are free to edit the **auth** filter however you like. A default implementation is located in **application/routes.php**. + + +## 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. + + +## 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. \ No newline at end of file diff --git a/storage/documentation/bundles.md b/storage/documentation/bundles.md new file mode 100644 index 00000000..2f72dbb5 --- /dev/null +++ b/storage/documentation/bundles.md @@ -0,0 +1,214 @@ +# Bundles + +## Contents + +- [The Basics](#the-basics) +- [Creating Bundles](#creating-bundles) +- [Registering Bundles](#registering-bundles) +- [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) + + +## 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. + + +## 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: + + 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! + + +## 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: + +#### Registering a bundle with a custom location: + + return array( + + 'admin' => array('location' => 'userscape/admin'), + + ); + +Now Laravel will look for our bundle in **bundles/userscape/admin**. + + +## 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. + + +## 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: + +#### Listen for a bundle's start event: + + Event::listen('laravel.started: admin', function() + { + // The "admin" bundle has started... + }); + +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'); + + +## 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. + + +## 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(); + + +## 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). + + +## 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) + + +## 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. + +#### Listening for a bundle's start event: + + Event::listen('laravel.started: admin', function() + { + Config::set('admin::file.option', true); + }); \ No newline at end of file diff --git a/storage/documentation/cache/config.md b/storage/documentation/cache/config.md new file mode 100644 index 00000000..39f80c4c --- /dev/null +++ b/storage/documentation/cache/config.md @@ -0,0 +1,79 @@ +# Cache Configuration + +## Contents + +- [The Basics](#the-basics) +- [Database](#database) +- [Memcached](#memcached) +- [Redis](#redis) +- [Cache Keys](#keys) +- [In-Memory Cache](#memory) + + +## The Basics + +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. + + +## 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! + + +## 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: + + 'servers' => array( + array('host' => '127.0.0.1', 'port' => 11211, 'weight' => 100), + ) + + +## Redis + +[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' + + +### 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' + + +### 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. \ No newline at end of file diff --git a/storage/documentation/cache/usage.md b/storage/documentation/cache/usage.md new file mode 100644 index 00000000..adc2f2e8 --- /dev/null +++ b/storage/documentation/cache/usage.md @@ -0,0 +1,59 @@ +# Cache Usage + +## Contents + +- [Storing Items](#put) +- [Retrieving Items](#get) +- [Removing Items](#forget) + + +## Storing Items + +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. + + +## 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: + + $users = Cache::get('count', function() {return DB::table('users')->count();}); + +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: + + $users = Cache::remember('count', function() {return DB::table('users')->count();}, 5); + +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'); + } + + +## Removing Items + +Need to get rid of a cached item? No problem. Just mention the name of the item to the **forget** method: + + Cache::forget('name'); \ No newline at end of file diff --git a/storage/documentation/config.md b/storage/documentation/config.md new file mode 100644 index 00000000..ae741386 --- /dev/null +++ b/storage/documentation/config.md @@ -0,0 +1,34 @@ +# Runtime Configuration + +## Contents + +- [The Basics](#the-basics) +- [Retrieving Options](#retrieving-options) +- [Setting Options](#setting-options) + + +## The Basics + +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. + + +## Retrieving Options + +#### Retrieve a configuration option: + + $value = Config::get('application.url'); + +#### Return a default value if the option doesn't exist: + + $value = Config::get('application.timezone', 'UTC'); + +#### Retrieve an entire configuration array: + + $options = Config::get('database'); + + +## Setting Options + +#### Set a configuration option: + + Config::set('cache.driver', 'apc'); \ No newline at end of file diff --git a/storage/documentation/contents.md b/storage/documentation/contents.md new file mode 100644 index 00000000..25d78c8a --- /dev/null +++ b/storage/documentation/contents.md @@ -0,0 +1,108 @@ +### General +- [Laravel Overview](/docs/home) +- [Installation & Setup](/docs/install) + - [Requirements](/docs/install#requirements) + - [Installation](/docs/install#installation) + - [Basic Configuration](/docs/install#basic-configuration) + - [Environments](/docs/install#environments) + - [Cleaner URLs](/docs/install#cleaner-urls) +- [Controllers](/docs/controllers) + - [The Basics](/docs/controllers#the-basics) + - [Controller Routing](/docs/controllers#controller-routing) + - [Bundle Controllers](/docs/controllers#bundle-controllers) + - [Action Filters](/docs/controllers#action-filters) + - [Nested Controllers](/docs/controllers#nested-controllers) + - [RESTful Controllers](/docs/controllers#restful-controllers) + - [Dependency Injection](/docs/controllers#dependency-injection) + - [Controller Factory](/docs/controllers#controller-factory) +- [Models & Libraries](/docs/models) +- [Views & Responses](/docs/views) + - [The Basics](/docs/views#basics) + - [Binding Data To Views](/docs/views#binding-data-to-views) + - [Nesting Views](/docs/views#nesting-views) + - [Named Views](/docs/views#named-views) + - [View Composers](/docs/views#view-composers) + - [Redirects](/docs/views#redirects) + - [Redirecting With Data](/docs/views#redirecting-with-flash-data) + - [Downloads](/docs/views#downloads) + - [Errors](/docs/views#errors) + - [Managing Assets](/docs/views/assets) + - [Templating](/docs/views/templating) + - [Pagination](/docs/views/pagination) + - [Building HTML](/docs/views/html) + - [Building Forms](/docs/views/forms) +- [Routing](/docs/routing) + - [The Basics](/docs/routing#the-basics) + - [Wildcards](/docs/routing#wildcards) + - [The 404 Event](/docs/routing#the-404-event) + - [Filters](/docs/routing#filters) + - [Global Filters](/docs/routing#global-filters) + - [Route Groups](/docs/routing#groups) + - [Named Routes](/docs/routing#named-routes) + - [HTTPS Routes](/docs/routing#https-routes) + - [Bundle Routing](/docs/routing#bundle-routing) + - [CLI Route Testing](/docs/routing#cli-route-testing) +- [Input & Cookies](/docs/input) + - [Input](/docs/input#input) + - [Files](/docs/input#files) + - [Old Input](/docs/input#old-input) + - [Redirecting With Old Input](/docs/input#redirecting-with-old-input) + - [Cookies](/docs/input#cookies) +- [Bundles](/docs/bundles) + - [The Basics](/docs/bundles#the-basics) + - [Creating Bundles](/docs/bundles#creating-bundles) + - [Registering Bundles](/docs/bundles#registering-bundles) + - [Bundles & Class Loading](/docs/bundles#bundles-and-class-loading) + - [Starting Bundles](/docs/bundles#starting-bundles) + - [Routing To Bundles](/docs/bundles#routing-to-bundles) + - [Using Bundles](/docs/bundles#using-bundles) + - [Bundle Assets](/docs/bundles#bundle-assets) + - [Installing Bundles](/docs/bundles#installing-bundles) + - [Upgrading Bundles](/docs/bundles#upgrading-bundles) +- [Class Auto Loading](/docs/loading) +- [Errors & Logging](/docs/logging) +- [Runtime Configuration](/docs/config) +- [Examining Requests](/docs/requests) +- [Generating URLs](/docs/urls) +- [Events](/docs/events) +- [Validation](/docs/validation) +- [Working With Files](/docs/files) +- [Working With Strings](/docs/strings) +- [Localization](/docs/localization) +- [Encryption](/docs/encryption) +- [IoC Container](/docs/ioc) +- [Unit Testing](/docs/testing) + +### Database + +- [Configuration](/docs/database/config) +- [Raw Queries](/docs/database/raw) +- [Fluent Query Builder](/docs/database/fluent) +- [Eloquent ORM](/docs/database/eloquent) +- [Schema Builder](/docs/database/schema) +- [Migrations](/docs/database/migrations) +- [Redis](/docs/database/redis) + +### Caching + +- [Configuration](/docs/cache/config) +- [Usage](/docs/cache/usage) + +### Sessions + +- [Configuration](/docs/session/config) +- [Usage](/docs/session/usage) + +### Authentication + +- [Configuration](/docs/auth/config) +- [Usage](/docs/auth/usage) + +### Artisan CLI + +- [Tasks](/docs/artisan/tasks) + - [The Basics](/docs/artisan/tasks#the-basics) + - [Creating & Running Tasks](/docs/artisan/tasks#creating-tasks) + - [Bundle Tasks](/docs/artisan/tasks#bundle-tasks) + - [CLI Options](/docs/artisan/tasks#cli-options) +- [Commands](/docs/artisan/commands) \ No newline at end of file diff --git a/storage/documentation/controllers.md b/storage/documentation/controllers.md new file mode 100644 index 00000000..5468653b --- /dev/null +++ b/storage/documentation/controllers.md @@ -0,0 +1,206 @@ +# Controllers + +## Contents + +- [The Basics](#the-basics) +- [Controller Routing](#controller-routing) +- [Bundle Controllers](#bundle-controllers) +- [Action Filters](#action-filters) +- [Nested Controllers](#nested-controllers) +- [Controller Layouts](#controller-layouts) +- [RESTful Controllers](#restful-controllers) +- [Dependency Injection](#dependency-injection) +- [Controller Factory](#controller-factory) + + +## The Basics + +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. + + +## 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. + + +## 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). + + +## 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. + +#### Attaching a filter to only some actions: + + $this->filter('before', 'auth')->only(array('index', 'list')); + +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: + + $this->filter('before', 'auth')->except(array('add', 'posts')); + +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)* + + +## 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 + + +## Controller Layouts + +Full documentation on using layouts with Controllers [can be found on the Templating page](http://laravel.com/docs/views/templating). + + +## 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. + + +## 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). + + +## 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:** + + Event::listen(Controller::factory, function($controller) + { + return new $controller; + }); + +The event will receive the class name of the controller that needs to be resolved. All you need to do is return an instance of the controller. diff --git a/storage/documentation/database/config.md b/storage/documentation/database/config.md new file mode 100644 index 00000000..a4eddb62 --- /dev/null +++ b/storage/documentation/database/config.md @@ -0,0 +1,46 @@ +# Database Configuration + +## Contents + +- [Quick Start Using SQLite](#quick) +- [Configuring Other Databases](#server) +- [Setting The Default Connection Name](#default) + +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. + + +## 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/). + + +## 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. + + +## 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. \ No newline at end of file diff --git a/storage/documentation/database/eloquent.md b/storage/documentation/database/eloquent.md new file mode 100644 index 00000000..8624b8a7 --- /dev/null +++ b/storage/documentation/database/eloquent.md @@ -0,0 +1,460 @@ +# Eloquent ORM + +## Contents + +- [The Basics](#the-basics) +- [Conventions](#conventions) +- [Retrieving Models](#get) +- [Aggregates](#aggregates) +- [Inserting & Updating Models](#save) +- [Relationships](#relationships) +- [Inserting Related Models](#inserting-related-models) +- [Working With Intermediate Tables](#intermediate-tables) +- [Eager Loading](#eager) +- [Constraining Eager Loads](#constraining-eager-loads) +- [Setter & Getter Methods](#getter-and-setter-methods) +- [Mass-Assignment](#mass-assignment) + + +## The Basics + +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. + + +## 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'; + + } + + +## 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: + + $user = User::where('email', '=', $email)->first(); + + $user = User::where_email($email)->first(); + + $users = User::where_in('id', array(1, 2, 3))->or_where('email', '=', $email)->get(); + + $users = User::order_by('votes', 'desc')->take(10)->get(); + +> **Note:** If no results are found, the **first** method will return NULL. The **all** and **get** methods return an empty array. + + +## 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(); + + +## 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. + + $user = User::create(array('email' => 'example@gmail.com')); + +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. + + +## 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. + + +### 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; + + +### 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: + + return $this->has_many('Comment', 'my_foreign_key'); + +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: + + echo Post::find(1)->comments()->order_by('votes', 'desc')->take(10)->get(); + + +### Many-To-Many + +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: + + class User extends Eloquent { + + public function roles() + { + return $this->has_many_and_belongs_to('Role', 'user_roles'); + } + + } + + +## Inserting Related Models + +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); + + +## 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. + + +## 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: + + $books = Book::with(array('author', 'publisher'))->get(); + +> **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: + + $books = Book::with(array('author', 'author.contacts'))->get(); + + +## Constraining Eager Loads + +Sometimes you may wish to eager load a relationship, but also specify a condition for the eager load. It's simple. Here's what it looks like: + + $users = User::with(array('posts' => function($query) + { + $query->where('title', 'like', '%first%'); + + }))->get(); + +In this example, we're eager loading the posts for the users, but only if the post's "title" column contains the word "first". + + +## Getter & Setter Methods + +Setters allow you to handle attribute assignment with custom methods. Define a setter by appending "set_" to the intended attribute's name. + + public function set_password($password) + { + $this->set_attribute('hashed_password', Hash::make($password)); + } + +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. + + public function get_published_date() + { + return date('M j, Y', $this->get_attribute('published_at')); + } + +Call the getter method as a variable (without parenthesis) using the name of the method without the "get_" prefix. + + echo $this->published_date; + + +## 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: + + User::accessible(array('email', 'password', 'name')); + +> **Note:** Utmost caution should be taken when mass-assigning using user-input. Technical oversights could cause serious security vulnerabilities. \ No newline at end of file diff --git a/storage/documentation/database/fluent.md b/storage/documentation/database/fluent.md new file mode 100644 index 00000000..6ab34476 --- /dev/null +++ b/storage/documentation/database/fluent.md @@ -0,0 +1,270 @@ +# Fluent Query Builder + +## Contents + +- [The Basics](#the-basics) +- [Retrieving Records](#get) +- [Building Where Clauses](#where) +- [Nested Where Clauses](#nested-where) +- [Dynamic Where Clauses](#dynamic) +- [Table Joins](#joins) +- [Ordering Results](#ordering) +- [Skip & Take](#limit) +- [Aggregates](#aggregates) +- [Expressions](#expressions) +- [Inserting Records](#insert) +- [Updating Records](#update) +- [Deleting Records](#delete) + +## The Basics + +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. + + +## 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: + + $email = DB::table('users')->where('id', '=', 1)->only('email'); + +#### 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(); + + +## 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: + + DB::table('users')->where_in('id', array(1, 2, 3))->get(); + + DB::table('users')->where_not_in('id', array(1, 2, 3))->get(); + + DB::table('users') + ->where('email', '=', 'example@gmail.com') + ->or_where_in('id', array(1, 2, 3)) + ->get(); + + DB::table('users') + ->where('email', '=', 'example@gmail.com') + ->or_where_not_in('id', array(1, 2, 3)) + ->get(); + +### where\_null, where\_not\_null, or\_where\_null, and or\_where\_not\_null + +The suite of **where_null** methods makes checking for NULL values a piece of cake: + + return DB::table('users')->where_null('updated_at')->get(); + + return DB::table('users')->where_not_null('updated_at')->get(); + + return DB::table('users') + ->where('email', '=', 'example@gmail.com') + ->or_where_null('updated_at') + ->get(); + + return DB::table('users') + ->where('email', '=', 'example@gmail.com') + ->or_where_not_null('updated_at') + ->get(); + + +## Nested Where Clauses + +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" > ?) + + +## Dynamic Where Clauses + +Dynamic where methods are great way to increase the readability of your code. Here are some examples: + + $user = DB::table('users')->where_email('example@gmail.com')->first(); + + $user = DB::table('users')->where_email_and_password('example@gmail.com', 'secret'); + + $user = DB::table('users')->where_id_or_name(1, 'Fred'); + + + +## Table Joins + +Need to join to another table? Try the **join** and **left\_join** methods: + + DB::table('users') + ->join('phone', 'users.id', '=', 'phone.user_id') + ->get(array('users.email', 'phone.number')); + +The **table** you wish to join is passed as the first parameter. The remaining three parameters are used to construct the **ON** clause of the join. + +Once you know how to use the join method, you know how to **left_join**. The method signatures are the same: + + DB::table('users') + ->left_join('phone', 'users.id', '=', 'phone.user_id') + ->get(array('users.email', 'phone.number')); + +You may also specify multiple conditions for an **ON** clause by passing a Closure as the second parameter of the join: + + DB::table('users') + ->join('phone', function($join) + { + $join->on('users.id', '=', 'phone.user_id'); + $join->or_on('users.id', '=', 'phone.contact_id'); + }) + ->get(array('users.email', 'phone.numer')); + + +## Ordering Results + +You can easily order the results of your query using the **order_by** method. Simply mention the column and direction (desc or asc) of the sort: + + return DB::table('users')->order_by('email', 'desc')->get(); + +Of course, you may sort on as many columns as you wish: + + return DB::table('users') + ->order_by('email', 'desc') + ->order_by('name', 'asc') + ->get(); + + +## Skip & Take + +If you would like to **LIMIT** the number of results returned by your query, you can use the **take** method: + + return DB::table('users')->take(10)->get(); + +To set the **OFFSET** of your query, use the **skip** method: + + return DB::table('users')->skip(10)->get(); + + +## Aggregates + +Need to get a **MIN**, **MAX**, **AVG**, **SUM**, or **COUNT** value? Just pass the column to the query: + + $min = DB::table('users')->min('age'); + + $max = DB::table('users')->max('weight'); + + $avg = DB::table('users')->avg('salary'); + + $sum = DB::table('users')->sum('votes'); + + $count = DB::table('users')->count(); + +Of course, you may wish to limit the query using a WHERE clause first: + + $count = DB::table('users')->where('id', '>', 10)->count(); + + +## Expressions + +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: + + DB::table('users')->update(array('updated_at' => DB::raw('NOW()'))); + +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: + + DB::table('users')->update(array('votes' => DB::raw('votes + 1'))); + +Of course, convenient methods are provided for **increment** and **decrement**: + + DB::table('users')->increment('votes'); + + DB::table('users')->decrement('votes'); + + +## Inserting Records + +The insert method expects an array of values to insert. The insert method will return true or false, indicating whether the query was successful: + + DB::table('users')->insert(array('email' => 'example@gmail.com')); + +Inserting a record that has an auto-incrementing ID? You can use the **insert\_get\_id** method to insert a record and retrieve the ID: + + $id = DB::table('users')->insert_get_id(array('email' => 'example@gmail.com')); + +> **Note:** The **insert\_get\_id** method expects the name of the auto-incrementing column to be "id". + + +## Updating Records + +To update records simply pass an array of values to the **update** method: + + $affected = DB::table('users')->update(array('email' => 'new_email@gmail.com')); + +Of course, when you only want to update a few records, you should add a WHERE clause before calling the update method: + + $affected = DB::table('users') + ->where('id', '=', 1) + ->update(array('email' => 'new_email@gmail.com')); + + +## Deleting Records + +When you want to delete records from your database, simply call the **delete** method: + + $affected = DB::table('users')->where('id', '=', 1)->delete(); + +Want to quickly delete a record by its ID? No problem. Just pass the ID into the delete method: + + $affected = DB::table('users')->delete(1); \ No newline at end of file diff --git a/storage/documentation/database/migrations.md b/storage/documentation/database/migrations.md new file mode 100644 index 00000000..8c095631 --- /dev/null +++ b/storage/documentation/database/migrations.md @@ -0,0 +1,72 @@ +# Migrations + +## Contents + +- [The Basics](#the-basics) +- [Prepping Your Database](#prepping-your-database) +- [Creating Migrations](#creating-migrations) +- [Running Migrations](#running-migrations) +- [Rolling Back](#rolling-back) + + +## 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! + + +## 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 + + +## 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. + +You may also create migrations for a bundle. + +**Creating a migration for a bundle:** + + php artisan migrate:make bundle::create_users_table + +*Further Reading:* + +- [Schema Builder](/docs/database/schema) + + +## Running Migrations + +**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 + + +## 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. + +**Rolling back the last migration operation:** + + php artisan migrate:rollback + +**Roll back all migrations that have ever run:** + + php artisan migrate:reset \ No newline at end of file diff --git a/storage/documentation/database/raw.md b/storage/documentation/database/raw.md new file mode 100644 index 00000000..424ba27d --- /dev/null +++ b/storage/documentation/database/raw.md @@ -0,0 +1,56 @@ +# Raw Queries + +## Contents + +- [The Basics](#the-basics) +- [Other Query Methods](#other-query-methods) +- [PDO Connections](#pdo-connections) + + +## The Basics + +The **query** method is used to execute arbitrary, raw SQL against your database connection. + +#### Selecting records from the database: + + $users = DB::query('select * from users'); + +#### Selecting records from the database using bindings: + + $users = DB::query('select * from users where name = ?', array('test')); + +#### Inserting a record into the database + + $success = DB::query('insert into users values (?, ?)', $bindings); + +#### Updating table records and getting the number of affected rows: + + $affected = DB::query('update users set name = ?', $bindings); + +#### Deleting from a table and getting the number of affected rows: + + $affected = DB::query('delete from users where id = ?', array(1)); + + +## Other Query Methods + +Laravel provides a few other methods to make querying your database simple. Here's an overview: + +#### Running a SELECT query and returning the first result: + + $user = DB::first('select * from users where id = 1'); + +#### Running a SELECT query and getting the value of a single column: + + $email = DB::only('select email from users where id = 1'); + + +## PDO Connections + +Sometimes you may wish to access the raw PDO connection behind the Laravel Connection object. + +#### Get the raw PDO connection for a database: + + $pdo = DB::connection('sqlite')->pdo; + +> **Note:** If no connection name is specified, the **default** connection will be returned. \ No newline at end of file diff --git a/storage/documentation/database/redis.md b/storage/documentation/database/redis.md new file mode 100644 index 00000000..8abdd5cc --- /dev/null +++ b/storage/documentation/database/redis.md @@ -0,0 +1,58 @@ +# Redis + +## Contents + +- [The Basics](#the-basics) +- [Configuration](#config) +- [Usage](#usage) + + +## The Basics + +[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). + + +## 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: + + 'redis' => array( + + 'default' => array('host' => '127.0.0.1', 'port' => 6379), + + ), + +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. + + +## 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. \ No newline at end of file diff --git a/storage/documentation/database/schema.md b/storage/documentation/database/schema.md new file mode 100644 index 00000000..ed55d84e --- /dev/null +++ b/storage/documentation/database/schema.md @@ -0,0 +1,141 @@ +# Schema Builder + +## Contents + +- [The Basics](#the-basics) +- [Creating & Dropping Tables](#creating-dropping-tables) +- [Adding Columns](#adding-columns) +- [Dropping Columns](#dropping-columns) +- [Adding Indexes](#adding-indexes) +- [Dropping Indexes](#dropping-indexes) +- [Foreign Keys](#foreign-keys) + + +## The Basics + +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) + + +## 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'); + }); + + +## 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('email');` | VARCHAR equivalent column +`$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(); + }); + + +## 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')); + + +## 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: + +Command | Description +------------- | ------------- +`$table->primary('id');` | Adding a primary key +`$table->primary(array('fname', 'lname'));` | Adding composite keys +`$table->unique('email');` | Adding a unique index +`$table->fulltext('description');` | Adding a full-text index +`$table->index('state');` | Adding a basic index + + +## 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 + + +## 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: + + $table->foreign('user_id')->references('id')->on('users'); + +You may also specify options for the "on delete" and "on update" actions of the foreign key: + + $table->foreign('user_id')->references('id')->on('users')->on_delete('restrict'); + + $table->foreign('user_id')->references('id')->on('users')->on_update('cascade'); + +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: + + $table->drop_foreign('posts_user_id_foreign'); \ No newline at end of file diff --git a/storage/documentation/encryption.md b/storage/documentation/encryption.md new file mode 100644 index 00000000..9d7e6cee --- /dev/null +++ b/storage/documentation/encryption.md @@ -0,0 +1,30 @@ +# Encryption + +## Contents + +- [The Basics](#the-basics) +- [Encrypting A String](#encrypt) +- [Decrypting A String](#decrypt) + + +## The Basics + +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. + + +## Encrypting A String + +#### Encrypting a given string: + + $encrypted = Crypter::encrypt($value); + + +## 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. \ No newline at end of file diff --git a/storage/documentation/events.md b/storage/documentation/events.md new file mode 100644 index 00000000..dc74745f --- /dev/null +++ b/storage/documentation/events.md @@ -0,0 +1,73 @@ +# Events + +## Contents + +- [The Basics](#the-basics) +- [Firing Events](#firing-events) +- [Listening To Events](#listening-to-events) +- [Laravel Events](#laravel-events) + + +## The Basics + +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. + + +## 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'); + + +## 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. + + +## Laravel Events + +There are several events that are fired by the Laravel core. Here they are: + +#### Event fired when a bundle is started: + + Event::listen('laravel.started: bundle', function() {}); + +#### Event fired when a database query is executed: + + Event::listen('laravel.query', function($sql, $bindings, $time) {}); + +#### Event fired right before response is sent to browser: + + Event::listen('laravel.done', function($response) {}); + +#### Event fired when a messaged is logged using the Log class: + + Event::listen('laravel.log', function($type, $message) {}); \ No newline at end of file diff --git a/storage/documentation/files.md b/storage/documentation/files.md new file mode 100644 index 00000000..a27d10e5 --- /dev/null +++ b/storage/documentation/files.md @@ -0,0 +1,84 @@ +# Working With Files + +## Contents + +- [Reading Files](#get) +- [Writing Files](#put) +- [File Uploads](#upload) +- [File Extensions](#ext) +- [Checking File Types](#is) +- [Getting MIME Types](#mime) +- [Copying Directories](#cpdir) +- [Removing Directories](#rmdir) + + +## Reading Files + +#### Getting the contents of a file: + + $contents = File::get('path/to/file'); + + +## Writing Files + +#### Writing to a file: + + File::put('path/to/file', 'file contents'); + +#### Appending to a file: + + File::append('path/to/file', 'appended file content'); + + +## File Uploads + +#### Moving a $_FILE to a permanent location: + + Input::upload('picture', 'path/to/pictures'); + +> **Note:** You can easily validate file uploads using the [Validator class](/docs/validation). + + +## File Extensions + +#### Getting the extension from a filename: + + File::extension('picture.png'); + + +## 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). + + +## 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. + + +## Copying Directories + +#### Recursively copy a directory to a given location: + + File::cpdir($directory, $destination); + + +## Removing Directories + +#### Recursively delete a directory: + + File::rmdir($directory); \ No newline at end of file diff --git a/storage/documentation/home.md b/storage/documentation/home.md new file mode 100644 index 00000000..5545a492 --- /dev/null +++ b/storage/documentation/home.md @@ -0,0 +1,59 @@ +# Laravel Documentation + +- [The Basics](#the-basics) +- [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) + + +## 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. + + +## 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. + + + +## 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. + + +## 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. + + +## 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! + + +## License Information + +Laravel is open-sourced software licensed under the [MIT License](http://www.opensource.org/licenses/mit-license.php). \ No newline at end of file diff --git a/storage/documentation/input.md b/storage/documentation/input.md new file mode 100644 index 00000000..fb35e0ee --- /dev/null +++ b/storage/documentation/input.md @@ -0,0 +1,124 @@ +# Input & Cookies + +## Contents + +- [Input](#input) +- [Files](#files) +- [Old Input](#old-input) +- [Redirecting With Old Input](#redirecting-with-old-input) +- [Cookies](#cookies) + + +## 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: + + $name = Input::get('name', 'Fred'); + +#### Using a Closure to return a default value: + + $name = Input::get('name', function() {return 'Fred';}); + +#### 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. + + +## 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'); + + +## 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: + +#### Flashing input to the session: + + Input::flash(); + +#### Flashing selected input to the session: + + Input::flash('only', array('username', 'email')); + + Input::flash('except', array('password', 'credit_card')); + +#### 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)* + + +## 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: + + return Redirect::to('login')->with_input('only', array('username')); + + return Redirect::to('login')->with_input('except', array('password')); + + +## Cookies + +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: + + Cookie::forever('name', 'Fred'); + +#### Deleting a cookie: + + Cookie::forget('name'); \ No newline at end of file diff --git a/storage/documentation/install.md b/storage/documentation/install.md new file mode 100644 index 00000000..3f462e88 --- /dev/null +++ b/storage/documentation/install.md @@ -0,0 +1,101 @@ +# Installation & Setup + +## Contents + +- [Requirements](#requirements) +- [Installation](#installation) +- [Basic Configuration](#basic-configuration) +- [Environments](#environments) +- [Cleaner URLs](#cleaner-urls) + + +## Requirements + +- 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). + + +## 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. + + +## 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. + + +## 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'; + + +## 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: + + + RewriteEngine on + + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + + RewriteRule ^(.*)$ index.php/$1 [L] + + +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. \ No newline at end of file diff --git a/storage/documentation/ioc.md b/storage/documentation/ioc.md new file mode 100644 index 00000000..bd393178 --- /dev/null +++ b/storage/documentation/ioc.md @@ -0,0 +1,49 @@ +# IoC Container + +- [Definition](/docs/ioc#definition) +- [Registering Objects](/docs/ioc#register) +- [Resolving Objects](/docs/ioc#resolve) + + +## Definition + +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). + + +## 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); + + +## 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). \ No newline at end of file diff --git a/storage/documentation/loading.md b/storage/documentation/loading.md new file mode 100644 index 00000000..72919d46 --- /dev/null +++ b/storage/documentation/loading.md @@ -0,0 +1,58 @@ +# Class Auto Loading + +## Contents + +- [The Basics](#the-basics) +- [Registering Directories](#directories) +- [Registering Mappings](#mappings) +- [Registering Namespaces](#namespaces) + + +## The Basics + +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. + + +## 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', + )); + + +## 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', + )); + + +## 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: + + Autoloader::underscored(array( + 'Swift' => path('libraries').'SwiftMailer', + )); \ No newline at end of file diff --git a/storage/documentation/localization.md b/storage/documentation/localization.md new file mode 100644 index 00000000..e1941633 --- /dev/null +++ b/storage/documentation/localization.md @@ -0,0 +1,70 @@ +# Localization + +## Contents + +- [The Basics](#the-basics) +- [Retrieving A Language Line](#get) +- [Place Holders & Replacements](#replace) + + +## The Basics + +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! + + +## 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'); + + +## 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: + + echo Lang::line('marketing.welcome', array('name' => 'Taylor'))->get(); + +#### Retrieving a language line with replacements using "__": + + echo __('marketing.welcome', array('name' => 'Taylor')); \ No newline at end of file diff --git a/storage/documentation/logging.md b/storage/documentation/logging.md new file mode 100644 index 00000000..c1533387 --- /dev/null +++ b/storage/documentation/logging.md @@ -0,0 +1,40 @@ +# Errors & Logging + +## Contents + +- [Basic Configuration](#basic-configuration) +- [Logging](#logging) +- [The Logger Class](#the-logger-class) + + +## Basic Configuration + +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. + + +## 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. + + +## 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!'); \ No newline at end of file diff --git a/storage/documentation/models.md b/storage/documentation/models.md new file mode 100644 index 00000000..a1f4620c --- /dev/null +++ b/storage/documentation/models.md @@ -0,0 +1,116 @@ +# Models & Libraries + +## Contents + +- [Models](#models) +- [Libraries](#libraries) +- [Auto-Loading](#auto-loading) +- [Best Practices](#best-practices) + + +## Models + +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? + + +## 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. + + +## 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). + + +## 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: + + 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: + + +## Working With The URI + +#### Getting the current URI for the request: + + echo URI::current(); + +#### Getting a specific segment from the URI: + + echo URI::segment(1); + +#### 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/"! + } + + +## 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: + + if (Request::cli()) + { + // This request came from the CLI! + } \ No newline at end of file diff --git a/storage/documentation/routing.md b/storage/documentation/routing.md new file mode 100644 index 00000000..fc607cb9 --- /dev/null +++ b/storage/documentation/routing.md @@ -0,0 +1,317 @@ +# Routing + +## Contents + +- [The Basics](#the-basics) +- [Wildcards](#wildcards) +- [The 404 Events](#the-404-event) +- [Filters](#filters) +- [Pattern Filters](#pattern-filters) +- [Global Filters](#global-filters) +- [Route Groups](#route-groups) +- [Named Routes](#named-routes) +- [HTTPS Routes](#https-routes) +- [Bundle Routes](#bundle-routes) +- [Controller Routing](#controller-routing) +- [CLI Route Testing](#cli-route-testing) + + +## The Basics + +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:** + + Router::register(array('GET', 'POST'), $uri, $callback); + + +## Wildcards + +#### Forcing a URI segment to be any digit: + + Route::get('user/(:num)', function($id) + { + // + }); + +#### Allowing a URI segment to be any alpha-numeric string: + + Route::get('post/(:any)', function($title) + { + // + }); + +#### Allowing a URI segment to be optional: + + Route::get('page/(:any?)', function($page = 'index') + { + // + }); + + +## The 404 Event + +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)* + + +## 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**. + +#### Registering a filter: + + Route::filter('filter', function() + { + return Redirect::to('home'); + }); + +#### Attaching a filter to a route: + + Route::get('blocked', array('before' => 'filter', function() + { + return View::make('blocked'); + })); + +#### Attaching an "after" filter to a route: + + Route::get('download', array('after' => 'log', function() + { + // + })); + +#### Attaching multiple filters to a route: + + Route::get('create', array('before' => 'auth|csrf', function() + { + // + })); + +#### Passing parameters to filters: + + Route::get('panel', array('before' => 'role:admin', function() + { + // + })); + + +## Pattern Filters + +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'); + + +## 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. + + +## 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. + + Route::group(array('before' => 'auth'), function() + { + Route::get('panel', function() + { + // + }); + + Route::get('dashboard', function() + { + // + }); + }); + + +## Named Routes + +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! + } + + +## 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. + +#### Defining an HTTPS route: + + Route::get('login', array('https' => true, function() + { + return View::make('login'); + })); + +#### Using the "secure" short-cut method: + + Route::secure('GET', 'login', function() + { + return View::make('login'); + }); + + +## Bundle Routes + +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!"; + }); + + +## 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: + + Route::controller(array('dashboard.panel', 'admin')); + +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: + + Route::get('welcome', array('after' => 'log', 'uses' => 'home@index')); + + +## CLI Route Testing + +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. + +#### Calling a route via the Artisan CLI: + + php artisan route:call get api/user/1 \ No newline at end of file diff --git a/storage/documentation/session/config.md b/storage/documentation/session/config.md new file mode 100644 index 00000000..094148c8 --- /dev/null +++ b/storage/documentation/session/config.md @@ -0,0 +1,109 @@ + +# Session Configuration + +## Contents + +- [The Basics](#the-basics) +- [Cookie Sessions](#cookie) +- [File System Sessions](#file) +- [Database Sessions](#database) +- [Memcached Sessions](#memcached) +- [Redis Sessions](#redis) +- [In-Memory Sessions](#memory) + + +## The Basics + +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) + + +## 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' + + +## 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. + + +## 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' + + +## 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' + + +## 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' + + +## 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. \ No newline at end of file diff --git a/storage/documentation/session/usage.md b/storage/documentation/session/usage.md new file mode 100644 index 00000000..5f9aad56 --- /dev/null +++ b/storage/documentation/session/usage.md @@ -0,0 +1,61 @@ +# Session Usage + +## Contents + +- [Storing Items](#put) +- [Retrieving Items](#get) +- [Removing Items](#forget) +- [Regeneration](#regeneration) + + +## Storing Items + +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!'); + + +## 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: + + $name = Session::get('name', 'Fred'); + + $name = Session::get('name', function() {return 'Fred';}); + +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'); + } + + +## 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(); + + +## 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: + + Session::regenerate(); \ No newline at end of file diff --git a/storage/documentation/strings.md b/storage/documentation/strings.md new file mode 100644 index 00000000..002d9148 --- /dev/null +++ b/storage/documentation/strings.md @@ -0,0 +1,71 @@ +# Working With Strings + +## Contents + +- [Capitalization, Etc.](#capitalization) +- [Word & Character Limiting](#limits) +- [Generating Random Strings](#random) +- [Singular & Plural](#singular-and-plural) +- [Slugs](#slugs) + + +## Capitalization, Etc. + +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.'); + + +## 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); + + +## 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'); + + +## 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)); + + +## Slugs + +#### Generating a URL friendly slug: + + return Str::slug('My First Blog Post!'); + +#### Generating a URL friendly slug using a given separator: + + return Str::slug('My First Blog Post!', '_'); + diff --git a/storage/documentation/testing.md b/storage/documentation/testing.md new file mode 100644 index 00000000..a7d958c0 --- /dev/null +++ b/storage/documentation/testing.md @@ -0,0 +1,68 @@ +# Unit Testing + +## Contents + +- [The Basics](#the-basics) +- [Creating Test Classes](#creating-test-classes) +- [Running Tests](#running-tests) +- [Calling Controllers From Tests](#calling-controllers-from-tests) + + +## 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! + + +## 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: + + 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/). + + +## 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 + + +## Calling Controllers From Tests + +Here's an example of how you can call your controllers from your tests: + +#### Calling a controller from a test: + + $response = Controller::call('home@index', $parameters); + +#### Resolving an instance of a controller from a test: + + $controller = Controller::resolve('application', 'home@index'); + +> **Note:** The controller's action filters will still run when using Controller::call to execute controller actions. \ No newline at end of file diff --git a/storage/documentation/urls.md b/storage/documentation/urls.md new file mode 100644 index 00000000..4263712f --- /dev/null +++ b/storage/documentation/urls.md @@ -0,0 +1,98 @@ +# Generating URLs + +## Contents + +- [The Basics](#the-basics) +- [URLs To Routes](#urls-to-routes) +- [URLs To Controller Actions](#urls-to-controller-actions) +- [URLs To Assets](#urls-to-assets) +- [URL Helpers](#url-helpers) + + +## 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(); + + +## 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: + + $url = URL::to_route('profile', array($username)); + +*Further Reading:* + +- [Named Routes](/docs/routing#named-routes) + + +## URLs To Controller Actions + +#### Generating a URL to a controller action: + + $url = URL::to_action('user@profile'); + +#### Generating a URL to an action with wildcard values: + + $url = URL::to_action('user@profile', array($username)); + + +## URLs To Assets + +URLs generated for assets will not contain the "application.index" configuration option. + +#### Generating a URL to an asset: + + $url = URL::to_asset('js/jquery.js'); + + +## URL Helpers + +There are several global functions for generating URLs designed to make your life easier and your code cleaner: + +#### Generating a URL relative to the base URL: + + $url = url('user/profile'); + +#### Generating a URL to an asset: + + $url = asset('js/jquery.js'); + +#### Generating a URL to a named route: + + $url = route('profile'); + +#### Generating a URL to a named route with wildcard values: + + $url = route('profile', array($username)); + +#### Generating a URL to a controller action: + + $url = action('user@profile'); + +#### Generating a URL to an action with wildcard values: + + $url = action('user@profile', array($username)); \ No newline at end of file diff --git a/storage/documentation/validation.md b/storage/documentation/validation.md new file mode 100644 index 00000000..49401439 --- /dev/null +++ b/storage/documentation/validation.md @@ -0,0 +1,431 @@ +# Validation + +## Contents + +- [The Basics](#the-basics) +- [Validation Rules](#validation-rules) +- [Retrieving Error Message](#retrieving-error-messages) +- [Validation Walkthrough](#validation-walkthrough) +- [Custom Error Messages](#custom-error-messages) +- [Custom Validation Rules](#custom-validation-rules) + + +## The Basics + +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! + + +## Validation Rules + +- [Required](#rule-required) +- [Alpha, Alpha Numeric, & Alpha Dash](#rule-alpha) +- [Size](#rule-size) +- [Numeric](#rule-numeric) +- [Inclusion & Exclusion](#rule-in) +- [Confirmation](#rule-confirmation) +- [Acceptance](#rule-acceptance) +- [Same & Different](#same-and-different) +- [Regular Expression Match](#regex-match) +- [Uniqueness & Existence](#rule-unique) +- [Dates](#dates) +- [E-Mail Addresses](#rule-email) +- [URLs](#rule-url) +- [Uploads](#rule-uploads) + + +### Required + +#### Validate that an attribute is present and is not an empty string: + + 'name' => 'required' + + +### 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' + + +### 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' + + +### Numeric + +#### Validate that an attribute is numeric: + + 'payment' => 'numeric' + +#### Validate that an attribute is an integer: + + 'payment' => 'integer' + + +### 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' + + +### 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. + + +### 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' + + +## Same & Different + +#### Validate that an attribute matches another attribute: + + 'token1' => 'same:token2' + +#### Validate that two attributes have different values: + + 'password' => 'different:old_password', + + +### 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]+/'; + + +### 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' + + +### 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. + + +### 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. + + +### 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. + + +### 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' + + +## 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. + +#### Format an error message: + + echo $validation->errors->first('email', '

:message

'); + +#### Get all of the error messages for a given attribute: + + $messages = $validation->errors->get('email'); + +#### Format all of the error messages for an attribute: + + $messages = $validation->errors->get('email', '

:message

'); + +#### Get all of the error messages for all attributes: + + $messages = $validation->errors->all(); + +#### Format all of the error messages for all attributes: + + $messages = $validation->errors->all('

:message

'); + + +## Validation Walkthrough + +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: + + Route::get('register', function() + { + return View::make('user.register'); + }); + + Route::post('register', function() + { + $rules = array(...); + + $validation = Validator::make(Input::all(), $rules); + + if ($validation->fails()) + { + return Redirect::to('register')->with_errors($validation); + } + }); + +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. + + +## 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.', + ); + + $validation = Validator::make(Input::get(), $rules, $messages); + +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!', + ) + + +## 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. + +#### Registering a custom validation rule: + + Validator::register('awesome', function($attribute, $value, $parameters) + { + return $value == 'awesome'; + }); + +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!', + ); + + $validator = Validator::make(Input::get(), $rules, $messages); + +Or by adding an entry for your rule in the **language/en/validation.php** file: + + 'awesome' => 'The attribute value must be awesome!', + +As mentioned above, you may even specify and receive a list of parameters in your custom rule: + + // When building your rules array... + + $rules = array( + 'username' => 'required|awesome:yes', + ); + + // In your custom rule... + + Validator::register('awesome', function($attribute, $value, $parameters) + { + return $value == $parameters[0]; + } + +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: + + +## Registering Assets + +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. + + +## 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: + + + + + + + +## 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: + +#### Registering a bundle that has dependencies: + + Asset::add('jquery-ui', 'js/jquery-ui.js', 'jquery'); + +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: + + Asset::add('jquery-ui', 'js/jquery-ui.js', array('first', 'second')); + + +## Asset Containers + +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: + + Asset::container('footer')->add('example', 'js/example.js'); + +#### Dumping that assets from a given container: + + echo Asset::container('footer')->scripts(); + + +## Bundle Assets + +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. \ No newline at end of file diff --git a/storage/documentation/views/forms.md b/storage/documentation/views/forms.md new file mode 100644 index 00000000..7efaed24 --- /dev/null +++ b/storage/documentation/views/forms.md @@ -0,0 +1,153 @@ +# Building Forms + +## Contents + +- [Opening A Form](#opening-a-form) +- [CSRF Protection](#csrf-protection) +- [Labels](#labels) +- [Text, Text Area, Password & Hidden Fields](#text) +- [Checkboxes and Radio Buttons](#checkboxes-and-radio-buttons) +- [Drop-Down Lists](#drop-down-lists) +- [Buttons](#buttons) +- [Custom Macros](#custom-macros) + +> **Note:** All input data displayed in form elements is filtered through the HTML::entities method. + + +## Opening A Form + +#### Opening a form to POST to the current URL: + + echo Form::open(); + +#### Opening a form using a given URI and request method: + + echo Form::open('user/profile', 'PUT'); + +#### Opening a Form that POSTS to a HTTPS URL: + + echo Form::open_secure('user/profile'); + +#### Specifying extra HTML attributes on a form open tag: + + echo Form::open('user/profile', 'POST', array('class' => 'awesome')); + +#### Opening a form that accepts file uploads: + + echo Form::open_for_files('users/profile'); + +#### Opening a form that accepts file uploads and uses HTTPS: + + echo Form::open_secure_for_files('users/profile'); + +#### Closing a form: + + echo Form::close(); + + +## CSRF Protection + +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: + + echo Form::token(); + +#### Attaching the CSRF filter to a route: + + Route::post('profile', array('before' => 'csrf', function() + { + // + })); + +#### Retrieving the CSRF token string: + + $token = Session::token(); + +> **Note:** You must specify a session driver before using the Laravel CSRF protection facilities. + +*Further Reading:* + +- [Route Filters](/docs/routing#filters) +- [Cross-Site Request Forgery](http://en.wikipedia.org/wiki/Cross-site_request_forgery) + + +## Labels + +#### Generating a label element: + + echo Form::label('email', 'E-Mail Address'); + +#### Specifying extra HTML attributes for a label: + + echo Form::label('email', 'E-Mail Address', array('class' => 'awesome')); + +> **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. + + +## 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'); + + +## 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! + + +## Drop-Down Lists + +#### Generating a drop-down list from an array of items: + + echo Form::select('size', array('L' => 'Large', 'S' => 'Small')); + +#### Generating a drop-down list with an item selected by default: + + echo Form::select('size', array('L' => 'Large', 'S' => 'Small'), 'S'); + + +## Buttons + +#### Generating a submit button element: + + echo Form::submit('Click Me!'); + +> **Note:** Need to create a button element? Try the *button* method. It has the same signature as *submit*. + + +## 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: + +#### Registering a Form macro: + + Form::macro('my_field', function() + { + return ''; + }); + +Now you can call your macro using its name: + +#### Calling a custom Form macro: + + echo Form::my_field(); \ No newline at end of file diff --git a/storage/documentation/views/home.md b/storage/documentation/views/home.md new file mode 100644 index 00000000..b2b6b3f3 --- /dev/null +++ b/storage/documentation/views/home.md @@ -0,0 +1,241 @@ +# Views & Responses + +## Contents + +- [The Basics](#the-basics) +- [Binding Data To Views](#binding-data-to-views) +- [Nesting Views](#nesting-views) +- [Named Views](#named-views) +- [View Composers](#view-composers) +- [Redirects](#redirects) +- [Redirecting With Flash Data](#redirecting-with-flash-data) +- [Downloads](#downloads) +- [Errors](#errors) + + +## 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: + + + I'm stored in views/home/index.php! + + +#### 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: + + Route::get('/', function() + { + $headers = array('foo' => 'bar'); + + return Response::make('Hello World!', 200, $headers); + }); + +#### Returning a custom response containing a view: + + return Response::view('home', 200, $headers); + + +## 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: + + + Hello, . + + +#### 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'; + + +## 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: + + View::make('home')->nest('footer', 'partials.footer'); + +#### Passing data to a nested view: + + $view = View::make('home'); + + $view->nest('content', 'orders', array('orders' => $orders)); + +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: + +
+ +
+ +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. + + +## Named Views + +Named views can help to make your code more expressive and organized. Using them is simple: + +#### Registering a named view: + + View::name('layouts.default', 'layout'); + +#### Getting an instance of the named view: + + return View::of('layout'); + +#### Binding data to a named view: + + return View::of('layout', array('orders' => $orders)); + + +## View Composers + +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! + + +## 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: + + return Redirect::to_route('profile', array($username)); + +#### Redirecting to an action with wildcard values: + + return Redirect::to_action('user@profile', array($username)); + + +## Redirecting With Flash Data + +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. + + return Redirect::to('profile')->with('status', 'Welcome Back!'); + +You can access your message from the view with the Session get method: + + $status = Session::get('status'); + +*Further Reading:* + +- *[Sessions](/docs/session/config)* + + +## Downloads + +#### Sending a file download response: + + return Response::download('file/path.jpg'); + +#### Sending a file download and assigning a file name: + + return Response::download('file/path.jpg', 'photo.jpg'); + + +## Errors + +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. + +#### Generating a 404 error response: + + return Response::error('404'); + +#### Generating a 500 error response: + + return Response::error('500'); \ No newline at end of file diff --git a/storage/documentation/views/html.md b/storage/documentation/views/html.md new file mode 100644 index 00000000..d1fcae9b --- /dev/null +++ b/storage/documentation/views/html.md @@ -0,0 +1,139 @@ +# Building HTML + +## Content + +- [Entities](#entities) +- [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) + + +## 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: + + echo HTML::entities(''); + +#### Using the "e" global helper: + + echo e(''); + + +## Scripts And Style Sheets + +#### Generating a reference to a JavaScript file: + + echo HTML::script('js/scrollTo.js'); + +#### Generating a reference to a CSS file: + + echo HTML::style('css/common.css'); + +#### Generating a reference to a CSS file using a given media type: + + echo HTML::style('css/common.css', 'print'); + +*Further Reading:* + +- *[Managing Assets](/docs/views/assets)* + + +## Links + +#### Generating a link from a URI: + + echo HTML::link('user/profile', 'User Profile'); + +#### Generating a link that should use HTTPS: + + echo HTML::secure_link('user/profile', 'User Profile'); + +#### Generating a link and specifying extra HTML attributes: + + echo HTML::link('user/profile', 'User Profile', array('id' => 'profile_link')); + + +## Links To Named Routes + +#### Generating a link to a named route: + + echo HTML::link_to_route('profile'); + +#### Generating a link to a named route with wildcard values: + + $url = HTML::link_to_route('profile', array($username)); + +*Further Reading:* + +- *[Named Routes](/docs/routing#named-routes)* + + +## Links To Controller Actions + +#### Generating a link to a controller action: + + echo HTML::link_to_action('home@index'); + +### Generating a link to a controller action with wildcard values: + + echo HTML::link_to_action('user@profile', array($username)); + + +## Mail-To Links + +The "mailto" method on the HTML class obfuscates the given e-mail address so it is not sniffed by bots. + +#### Creating a mail-to link: + + echo HTML::mailto('example@gmail.com', 'E-Mail Me!'); + +#### Creating a mail-to link using the e-mail address as the link text: + + echo HTML::mailto('example@gmail.com'); + + +## Images + +#### Generating an HTML image tag: + + echo HTML::image('img/smile.jpg', $alt_text); + +#### Generating an HTML image tag with extra HTML attributes: + + echo HTML::image('img/smile.jpg', $alt_text, array('id' => 'smile')); + + +## Lists + +#### Creating lists from an array of items: + + echo HTML::ol(array('Get Peanut Butter', 'Get Chocolate', 'Feast')); + + echo HTML::ul(array('Ubuntu', 'Snow Leopard', 'Windows')); + + +## Custom Macros + +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: + +#### Registering a HTML macro: + + HTML::macro('my_element', function() + { + return '
'; + }); + +Now you can call your macro using its name: + +#### Calling a custom HTML macro: + + echo HTML::my_element(); diff --git a/storage/documentation/views/pagination.md b/storage/documentation/views/pagination.md new file mode 100644 index 00000000..602b09ba --- /dev/null +++ b/storage/documentation/views/pagination.md @@ -0,0 +1,104 @@ +# Pagination + +## Contents + +- [The Basics](#the-basics) +- [Using The Query Builder](#using-the-query-builder) +- [Appending To Pagination Links](#appending-to-pagination-links) +- [Creating Paginators Manually](#creating-paginators-manually) +- [Pagination Styling](#pagination-styling) + + +## The Basics + +Laravel's paginator was designed to reduce the clutter of implementing pagination. + + +## Using The Query Builder + +Let's walk through a complete example of paginating using the [Fluent Query Builder](/docs/database/fluent): + +#### Pull the paginated results from the query: + + $orders = DB::table('orders')->paginate($per_page); + +#### Display the results in a view: + + results as $order): ?> + id; ?> + + +#### Generate the pagination links: + + links(); ?> + +The links method will create an intelligent, sliding list of page links that looks something like this: + + Previous 1 2 ... 24 25 26 27 28 29 30 ... 78 79 Next + +The Paginator will automatically determine which page you're on and update the results and links accordingly. + +It's also possible to generate "next" and "previous" links: + +#### Generating simple "previous" and "next" links: + + previous().' '.$orders->next(); ?> + +*Further Reading:* + +- *[Fluent Query Builder](/docs/database/fluent)* + + +## Appending To Pagination Links + +You may need to add more items to the pagination links' query strings, such as the column your are sorting by. + +#### Appending to the query string of pagination links: + + appends(array('sort' => 'votes'))->links(); + +This will generate URLs that look something like this: + + http://example.com/something?page=2&sort=votes + + +## Creating Paginators Manually + +Sometimes you may need to create a Paginator instance manually, without using the query builder. Here's how: + +#### Creating a Paginator instance manually: + + $orders = Paginator::make($orders, $total, $per_page); + + +## Pagination Styling + +All pagination link elements can be style using CSS classes. Here is an example of the HTML elements generated by the links method: + + + +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: + + Previous \ No newline at end of file diff --git a/storage/documentation/views/templating.md b/storage/documentation/views/templating.md new file mode 100644 index 00000000..95582c2b --- /dev/null +++ b/storage/documentation/views/templating.md @@ -0,0 +1,153 @@ +# Templating + +## Contents + +- [The Basics](#the-basics) +- [Sections](#sections) +- [Blade Template Engine](#blade-template-engine) +- [Blade Layouts](#blade-layouts) + + +## The Basics + +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. + + +## 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: + + + + + +#### Rendering the contents of a section: + + + + + +#### Using Blade short-cuts to work with sections: + + @section('scripts') + + @endsection + + + @yield('scripts') + + + +## 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: + +

Profile + + @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: + +

Comments

+ + @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 + + +## 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: + + +
    + @section('navigation') +
  • Nav Item 1
    • +
  • Nav Item 2
    • + @yield_section +
+ +
+ @yield('content') +
+ + +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 +
  • Nav Item 3
    • + @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. \ No newline at end of file