:message
'); - -The **get** method returns an array containing all of the error messages for a given attribute: - - return $validator->errors->get('email'); - - return $validator->errors->get('email', ':message
'); - -The **all** method returns an array containing all error messages for all attributes: - - return $validator->errors->all(); - - return $validator->errors->all(':message
'); - - -### Specifying 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. - -Simply create an array of custom messages to pass to the Validator instance: - - $messages = array( - 'required' => 'The :attribute field is required.', - ); - - $validator = 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 **:size**, **:min**, **:max**, and **:values** place-holders when constructing your error messages: - - $messages = array( - '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: - - $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. - - -### Creating Custom Validation Rules - -Need to create your own validation rules? You will love how easy it is! First, create a class that extends **System\Validator** and place it in your **application/libraries** directory: - - '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 **application/lang/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 validator: - - // When building your rules array... - - $rules = array( - 'username' => 'required|awesome:yes', - ); - - // In your custom validator... - - class Validator extends System\Validator { - - public function validate_awesome($attribute, $parameters) - { - return $attribute == $parameters[0]; - } - - } - -In this case, the **parameters** argument of your validation rule would receive an array containing one element: "yes". \ No newline at end of file diff --git a/start/views.md b/start/views.md deleted file mode 100644 index 1a62e8d..0000000 --- a/start/views.md +++ /dev/null @@ -1,585 +0,0 @@ -## Views & Responses - -- [Creating Views](/docs/start/views#create) -- [Binding Data To Views](/docs/start/views#bind) -- [Nesting Views Within Views](/docs/start/views#nest) -- [Named Views](/docs/start/views#named-views) -- [View Composers](/docs/start/views#composers) -- [Managing Assets](/docs/start/views#assets) -- [Redirects](/docs/start/views#redirect) -- [Downloads](/docs/start/views#downloads) -- [Building URLs](/docs/start/views#urls) -- [Building HTML](/docs/start/views#html) -- [Pagination](/docs/start/views#pagination) -- [Errors](/docs/start/views#errors) - - -## Creating Views - -Typically, a route function returns a **View**. Views consist of plain ole' HTML and are stored in your **application/views** directory. - -A very simple view file could look like this: - - - Welcome to my website! - - -Assuming this view lives in **application/views/simple.php**, we could return it from a route like so: - - 'GET /home' => function() - { - return View::make('simple'); - } - -When building a large application, you may want to organize your views into sub-directories. That's a great idea! Assuming a view lives in **application/views/user/login.php**, we could return it like so: - - 'GET /home' => function() - { - return View::make('user/login'); - } - -It's that simple. Of course, you are not required to return a View. Strings are also welcome: - - 'GET /home' => function() - { - return json_encode('This is my response!'); - } - - -## Binding Data To Views - -You can pass data to a view by "binding" the data to a variable. This is done using the **bind** method on the View: - - 'GET /home' => function() - { - return View::make('simple')->bind('email', 'example@gmail.com'); - } - -In the example above, the first parameter is the **name** of the view variable. The second parameter is the **value** that will be assigned to the variable. - -Now, in our view, we can access the e-mail address like so: - - - - - -Of course, we can bind as many variables as we wish: - - 'GET /home' => function() - { - return View::make('simple') - ->bind('name', 'Taylor') - ->bind('email', 'example@gmail.com'); - } - -You may also bind view data by simply setting properties on a view instance: - - 'GET /home' => function() - { - $view = View::make('user/login'); - - $view->name = 'Taylor'; - $view->email = 'example@gmail.com'; - - return $view; - } - - -## Nesting Views Within Views - -Want to nest views inside of views? There are two ways to do it, and they are both easy. First, you can bind the view to a variable: - - 'GET /home' => function() - { - $view = View::make('user/login'); - - $view->content = View::make('partials/content'); - $view->footer = View::make('partials/footer'); - - return $view; - } - -Nested calls to **View::make** can get a little ugly. For that reason, Laravel provides a simple **partial** method: - - View::make('layout/default')->partial('content', 'partials/home'); - -The **partial** method is very similar to the **bind** method; however, you simply pass a view name in the second parameter to the method. The view will created and bound to the variable for you. - -Need to bind data to a partial? No problem. Pass the data in the third parameter to the method: - - View::make('layout/default') - ->partial('content', 'partials/home', array('name' => 'Taylor')); - -In some situations, you may need to get the string content of a view from within another view. It's easy using the **get** method: - - - get(); ?> - get(); ?> - - - -## Named Views - -Named views make your code more expressive and beautiful. Using them is simple. All of your named views are defined in the **application/composers.php** file. By default, a name has been defined for the **home/index** view: - - 'home.index' => array('name' => 'home', function($view) - { - // - }) - -Notice the **name** value in the array? This defines the "home" named view as being associated with the **application/views/home/index.php** file. Now, you can use the **View::of** dynamic method to create named view instances using simple, expressive syntax: - - return View::of_home(); - -Of course, you may pass bindings into the **of** method: - - return View::of_home(array('email' => 'example@gmail.com')); - -Since the **of** method returns an instance of the **View** class, you may use any of the View class methods: - - return View::of_home()->bind('email', $email); - -Using named views makes templating a breeze: - - return View::of_layout()->bind('content', $content); - - -## View Composers - -View composers will free you from repetitive, brittle code, and help keep your application beautiful and maintainable. All view composers are defined in the **application/composers.php** file. Each time a view is created, its composer will be called. The composer can bind data to the view, register its assets, or even gather common data needed for the view. When the composer is finished working with the view, it should return the view instance. Here's an example composer: - - return array( - - 'layouts.default' => function($view) - { - Asset::add('jquery', 'js/jquery.js'); - Asset::add('jquery-ui', 'js/jquery-ui.js', 'jquery'); - - $view->partial('header', 'partials/header'); - $view->partial('footer', 'partials/footer'); - - return $view; - } - - ); - -Great! We have defined a composer for the **layouts/default** view. Now, every time the view is created, this composer will be called. As you can see, the composer is registering some common assets, as well as binding partial views to the layout. Of course, we can create an instance of the view using the same syntax we're used to: - - return View::make('layouts.default'); - -There is no need to specify you want to use the composer. It will be called automatically when the view is created. The composer helps keep your code clean by allowing you to declare assets and common partials for views in a single location. Your code will be cleaner than ever. Enjoy the elegance. - - -## Managing Assets - -The **Asset** class provides a simple, elegant way to manage the CSS and JavaScript used by your application. Registering an asset is simple. Just call the **add** method on the **Asset** class: - - Asset::add('jquery', 'js/jquery.js'); - -Wonderful. 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. - -When you are ready to place the links to the registered assets on your view, you may use the **styles** or **scripts** methods: - - - - - - -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: - - Asset::add('jquery-ui', 'js/jquery-ui.js', 'jquery'); - -Great! 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: - - Asset::add('jquery-ui', 'js/jquery-ui.js', array('first', 'second')); - -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**. Simple 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: - - Asset::container('footer')->add('example', 'js/example.js'); - -Getting the links to your container assets is just as simple: - - echo Asset::container('footer')->scripts(); - - -## Redirects - -### Redirect Using URIs - -You will often need to redirect the browser to another location within your application. The **Redirect** class makes this a piece of cake. Here's how to do it: - - 'GET /redirect' => function() - { - return Redirect::to('user/profile'); - } - -Of course, you can also redirect to the root of your application: - - return Redirect::to('/'); - -Need to redirect to a URI that should be accessed over HTTPS? Check out the **to_secure** method: - - return Redirect::to_secure('user/profile'); - -You can even redirect the browser to a location outside of your application: - - return Redirect::to('http://www.google.com/'); - - -### Redirect Using Named Routes - -So far we've created redirects by specifying a URI to redirect to. But, what if the URI to the user's profile changes? It would be better to create a redirect based on the [route name](/docs/start/routes#named). Let's learn how to do it. Assuming the user profile route is named **profile**, you can redirect to the route using a dynamic, static method call like this: - - return Redirect::to_profile(); - -Need to redirect to a route that should be accessed over HTTPS? No problem: - - return Redirect::to_secure_profile(); - -That's great! But, what if the route URI looks like this: - - 'GET /user/profile/(:any)/(:any)' => array('name' => 'profile', 'do' => function() - { - // - }) - -You need to redirect to the named route, but you also need to replace the **(:any)** place-holders in the URI with actual values. It sounds complicated, but Laravel makes it a breeze. Just pass the parameters to the method in an array: - - return Redirect::to_profile(array('taylor', 'otwell')); - -The statement above will redirect the user to the following URL: - - http://example.com/index.php/user/profile/taylor/otwell - - -### Redirect 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? The **Response** and **Redirect** classes make it simple using the **with** method. This method will add a value to the Session flash data, which will be available for the next request: - - return Redirect::to('user/profile')->with('status', 'Welcome Back!'); - -> **Note:** For more information regarding Sessions and flash data, check out the [Session documentation](/docs/session/config). - - -## Downloads - -Perhaps you just want to force the web browser to download a file? Check out the **download** method on the **File** class: - - 'GET /file' => function() - { - return File::download('path/to/your/file.jpg'); - } - -In the example above, the image will be downloaded as "file.jpg", however, you can easily specify a different filename for the download in the second parameter to the method: - - 'GET /file' => function() - { - return File::download('path/to/your/file.jpg', 'photo.jpg'); - } - - -## Building URLs - -- [Generating URLs Using URIs](#uri-urls) -- [Generating URLs Using Named Routes](#named-urls) -- [URL Slugs](#url-slugs) - -While developing your application, you will probably need to generate a large number of URLs. Hard-coding your URLs can cause headaches if you switch domains or application locations. Nobody wants to dig through every view in their application to change URLs. Thankfully, the **URL** class provides some simple methods that allow you to easily generate URLs for your application. - - -### Generating URLs Using URIs - -To generate a URL for your application, use the **to** method on the URL class: - - echo URL::to(); - -The statement above will simply return the URL specified in your **application/config/application.php** file. - -However, this method can also append a specified string to the end of your application URL: - - echo URL::to('user/profile'); - -Now the statement will generate a URL something like this: - - http://example.com/index.php/user/login - -Need to generate a HTTPS URL? No problem. Check out the **to\_secure** method: - - echo URL::to_secure('user/profile'); - -Often, you will need to generate URLs to assets such as images, scripts, or styles. You don't want "index.php" inserted into these URLs. So, use the **to_asset** method: - - echo URL::to_asset('img/picture.jpg'); - - -### Generating URLs To Named Routes - -Alright, you have learned how to generate URLs from URIs, but what about from named routes? You can do it by making a dynamic, static method call to the URL class. The syntax is beautiful: - - echo URL::to_profile(); - -Have a route that needs to be accessed over HTTPS? No problem: - - echo URL::to_secure_profile(); - -Could it get any easier? Now, imagine a route that is defined like this: - - 'GET /user/profile/(:any)/(:any)' => array('name' => 'profile', 'do' => function() - { - // - }) - -To generate a URL for the route, you need to replace the **(:any)** place-holders with actual values. It's easy. Just pass the parameters to the method in an array: - - echo URL::to_profile(array('taylor', 'otwell')); - -The method above will generate the following URL: - - http://example.com/index.php/user/profile/taylor/otwell - -If you don't want to use dynamic methods, you can simply call the **to_route** method: - - echo URL::to_route('profile', array('taylor', 'otwell')); - - -### URL Slugs - -When writing an application like a blog, it is often necessary to generate URL "slugs". Slugs are URL friendly strings of text that represent something like a blog post title. Generating slugs is a piece of cake using the **slug** method: - - echo URL::slug('My blog post title!'); - -The statement above will return the following string: - - my-blog-post-title - -Want to use a different separator character? Just mention it to the method: - - echo URL::slug('My blog post title!', '_'); - - -## Building HTML - -- [Entities](#html-entities) -- [JavaScript & Style Sheets](#html-styles) -- [Links](#html-links) -- [Links To Named Routes](#html-route-links) -- [Mail-To Links](#html-mailto) -- [Images](#html-images) -- [Lists](#html-lists) - -Need some convenient methods that make writing HTML a little less painful? Introducing the **HTML** class. Enjoy. - - -### 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. Thankfully, using the **entities** method on the HTML class, it's easy to add this layer of protection to your Views: - - echo HTML::entities(''); - - -### JavaScript & Style Sheets - -What trendy web application doesn't use JavaScript? Generating a reference to a JavaScript file is as simple using the **script** method. - - echo HTML::script('js/scrollTo.js'); - -Referencing cascading style sheets is just as simple. Check out the **style method**: - - echo HTML::style('css/common.css'); - -Need to specify a media type on your style sheet? No problem. Just pass it in the second parameter to the method: - - echo HTML::style('css/common.css', 'print'); - -> **Note:** All scripts and stylesheets should live in the **public** directory of your application. - - -### Links - -Generating links couldn't be easier. Just mention the URL and title to the **link** method: - - echo HTML::link('user/profile', 'User Profile'); - -Need to generate a link to a URL that should be accessed over HTTPS? Use the **secure_link** method: - - echo HTML::secure_link('user/profile', 'User Profile'); - -Of course, you may generate links to locations outside of your application: - - echo HTML::link('http://www.google.com/', 'Search the Intrawebs!'); - -Any other attributes that should be applied to the link may be passed in the third parameter to the method: - - echo HTML::link('http://www.google.com/', 'Search the Intrawebs!', array('id' => 'google')); - - -### Links To Named Routes - -If you are using [named routes](#routes-named), you use intuitive, expressive syntax to create links to those routes via dynamic methods: - - echo HTML::link_to_login('Login'); - -Or, if you need an HTTPS link: - - echo HTML::link_to_secure_login('Login'); - -Now let's assume the **login** route is defined like this: - - 'GET /login/(:any)' => array('name' => 'login', 'do' => function() {}) - -To generate a link to the route, you need to replace the **(:any)** place-holder with an actual value. It's easy. Just pass the parameters to the method in an array: - - echo HTML::link_to_login(array('user')); - -This statement will generate a link to the following URL: - - http://example.com/login/user - - -### Mail-To Links - -It's great to allow your users to get in touch with you, but you don't want to be bombarded by spam. Laravel doesn't want you to be either. The **mailto** method allows you to create a safe mail-to link that obfuscates your e-mail address: - - echo HTML::mailto('example@gmail.com'); - -Want the link text to be something besides your e-mail address? No problem. Just mention it to the method: - - echo HTML::mailto('example@gmail.com', 'E-Mail Me!'); - -Need to obfuscate an e-mail address but don't want to generate an entire mail-to link? Simply pass the e-mail address to the **email** method: - - echo HTML::email('example@gmail.com'); - - -### Images - -Since you're building a creative application, you will need to include some images. The **image** method makes simple. Just pass the URL and Alt text to the method: - - echo HTML::image('img/smile.jpg', 'A Smiling Face'); - -Like the link method, any other attributes that should be applied to the image may be passed in the third parameter to the method: - - echo HTML::image('img/smile.jpg', 'A Smiling Face', array('id' => 'smile')); - - -### Lists - -Generating HTML lists doesn't have to be a headache. Check out the **ol** method. All it needs is an array of items: - - echo HTML::ol(array('Get Peanut Butter', 'Get Chocolate', 'Feast')); - -As usual, you may specify any other attributes that should be applied to the list: - - echo HTML::ol(array('Get Peanut Butter', 'Get Chocolate', 'Feast'), array('class' => 'awesome')); - -Need an un-ordered list? No problem. Just use the **ul** method: - - echo HTML::ul(array('Ubuntu', 'Snow Leopard', 'Windows')); - - -## Pagination - -Just looking at pagination libraries probably makes you cringe. It doesn't have to. Laravel makes pagination enjoyable. Really. - -> **Note:** Before learning about pagination, you should probably read up on [Eloquent models](/docs/database/eloquent). - -To learn about pagination, we'll use an "User" Eloquent model. First, let's define a **per_page** static property on our model. This will tell Laravel how many users to show per page when paginating lists of users: - - class User extends Eloquent { - - public static $per_page = 10; - - } - -Great! Now you're ready to get paginated results from the database. It couldn't be any easier. Just use the **paginate** method: - - $users = User::where('posts', '>', 100)->paginate(); - -The **paginate** method will return an instance of the **Paginator** class. Notice you didn't have to specify the current page or the total amount of users. Laravel makes your life easier by figuring that stuff out for you. The results of your query can be accessed via the **results** property on the Paginator instance: - - $results = $users->results; - -Need to paginate results using the [Fluent query builder](/docs/database/query)? Simply pass the number of items to show per page into the **paginate** method: - - $users = DB::table('users')->where('votes', '>' 100)->paginate(10); - -You can even specify which columns to retrieve. Just pass an array of column names as the second parameter to the method: - - $users = DB::table('users') - ->where('votes', '>' 100) - ->paginate(10, array('id', 'email')); - -Alright, now you are ready to display the results on a View: - - results as $user): ?> -name; ?>
- - -Ready to create the pagination links? Simply call the **links** method on the Paginator instance: - - echo $users->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 - -Feeling more minimal? You can create simple "Previous" and "Next" links using the **previous** and **next** methods on the Paginator instance: - - previous().' | '.$users->next(); ?> - -The URLs created by the Pagination class look something like this: - - http://example.com/something?page=2 - -Sometimes, you may wish to add more items to the query string, such as the column you are sorting by. It's a breeze. Use the **append** method on your Paginator instance: - - append(array('sort' => 'votes'))->links(); - -Great! Now the URLs will look like this: - - http://example.com/something?page=2&sort=votes - -Need to style your links? No problem. 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 - - -## Errors - -Sometimes you may need to return an error response, such as the **404** or **500** views. It can be done like this: - - return Response::make(View::make('error/404'), 404); - -But, that's a little cumbersome. Instead, use the **error** method on the **Response** class. Just mention the error you want to return: - - return Response::error('404'); - -> **Note:** The error passed the **error** method must have a corresponding view in the **application/views/error** directory. \ No newline at end of file diff --git a/strings.md b/strings.md new file mode 100644 index 0000000..002d914 --- /dev/null +++ b/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/testing.md b/testing.md new file mode 100644 index 0000000..a7d958c --- /dev/null +++ b/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/urls.md b/urls.md new file mode 100644 index 0000000..4263712 --- /dev/null +++ b/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('http://github.com/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/validation.md b/validation.md new file mode 100644 index 0000000..1c932ae --- /dev/null +++ b/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-05-28'; + +#### Validate that a date attribute is after a given date: + + 'birthdate' => 'after:1986-05-28'; + +> **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 improve 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 asset 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/views/forms.md b/views/forms.md new file mode 100644 index 0000000..f6b73e4 --- /dev/null +++ b/views/forms.md @@ -0,0 +1,167 @@ +# 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'); + +#### Generating drop-down list options from the database + +In this example we need to create a drop-down list that allows an administrator to choose a user account. To do so we use the lists() method. + + $user_options = User::where('type', '=', 'standard')->lists('real_name', 'id'); + +This will create an array called $user_options which will have the user record's 'id' field as the key and the user record's 'real_name' field as the value. This is ideal for drop-down lists. + + echo Form::select('user_id', User::where('type', '=', 'standard')->lists('real_name', 'id'), Input::old('user_id')); + +A fun trick to add a default empty list item: + + $user_options = array('') + User::where('type', '=', 'standard')->lists('real_name', 'id'); + + +## 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/views/home.md b/views/home.md new file mode 100644 index 0000000..332c8c0 --- /dev/null +++ b/views/home.md @@ -0,0 +1,245 @@ +# 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'; + +#### Share a value with all views into your application: + + View::share('key', 'value'); + + +## 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: + +