This is perfectly fine, but can lead to a large amount of validation code within your routes and controllers. Let’s have a look at how we can shift some of the validation logic into our models instead and clean up our routing. First we will need our Eloquent model.

class Ball extends Eloquent
{

}

Great! That’s all we need, now lets add a new private property to the model called rules. This will store our validation rules array in the usual format.

class Ball extends Eloquent
{
    private $rules = array(
        'color' => 'required|alpha|min:3',
        'size'  => 'required',
        // .. more rules here ..
    );
}

Great! Now our rules are attached to our model, this means that we won’t have to recreate the validation array each time we create a new model instance. Now we need a way of using these rules, I like to create a public validate() method, let’s take a look..

class Ball extends Eloquent
{
    private $rules = array(
        'color' => 'required|alpha|min:3',
        'size'  => 'required',
        // .. more rules here ..
    );

    public function validate($data)
    {
        // make a new validator object
        $v = Validator::make($data, $this->rules);
        // return the result
        return $v->passes();
    }
}

Great! Now we can validate our models using the following syntax.

// get the POST data
$new = Input::all();

// create a new model instance
$b = new Ball();

// attempt validation
if ($b->validate($new))
{
    // success code
}
else
{
    // failure
}

That’s a lot more compact, but we are missing something important. What about our validation errors? We will need those for our forms. Let’s create a new private attribute to store them.

class Ball extends Eloquent
{
    private $rules = array(
        'color' => 'required|alpha|min:3',
        'size'  => 'required',
        // .. more rules here ..
    );

    private $errors;

    public function validate($data)
    {
        // make a new validator object
        $v = Validator::make($data, $this->rules);

        // check for failure
        if ($v->fails())
        {
            // set errors and return false
            $this->errors = $v->errors;
            return false;
        }

        // validation pass
        return true;
    }
}

Now we need a method to be able to retrieve the errors object.

class Ball extends Eloquent
{
    private $rules = array(
        'color' => 'required|alpha|min:3',
        'size'  => 'required',
        // .. more rules here ..
    );

    private $errors;

    public function validate($data)
    {
        // make a new validator object
        $v = Validator::make($data, $this->rules);

        // check for failure
        if ($v->fails())
        {
            // set errors and return false
            $this->errors = $v->errors;
            return false;
        }

        // validation pass
        return true;
    }

    public function errors()
    {
        return $this->errors;
    }
}

Great! Let’s take a look at it in action.

// get the POST data
$new = Input::all();

// create a new model instance
$b = new Ball();

// attempt validation
if ($b->validate($new))
{
    // success code
}
else
{
    // failure, get errors
    $errors = $b->errors();
}

We now have a working validation model, but to use this same system across many models we would have to replicate the code across the other classes..

Dayle, surely there’s a better way?

Do not fear! There is always a better way! Let’s create a new base model with the code that we have already used. I like to call mine Elegant.

class Elegant extends Eloquent
{
    protected $rules = array();

    protected $errors;

    public function validate($data)
    {
        // make a new validator object
        $v = Validator::make($data, $this->rules);

        // check for failure
        if ($v->fails())
        {
            // set errors and return false
            $this->errors = $v->errors;
            return false;
        }

        // validation pass
        return true;
    }

    public function errors()
    {
        return $this->errors;
    }
}

Now we can have our models extend the base model Elegant instead of Eloquent, define a $rules array, and have access to all the validation features we had before..

class Ball extends Eloquent
{
    protected $rules = array(
        'color' => 'required|alpha|min:3',
        'size'  => 'required',
        // .. more rules here ..
    );
}

That’s all for now! Enjoy using your validation friendly Elegant models!

Offline Docs

It feels like a year since Taylor and I finished working on this, and I’m excited to hear what people have to say about it. We have had a lot of requests from the community for a method of taking the documentation with them. Apparently our coders are so relaxed and hip that they live jet set lifestyles, they need to be able to access the documentation on a plane, a jet ski, or the back of a giraffe. Your wish is our command, behold the offline docs.

Taylor had already setup most of the markdown processing when he approached me hoping for a simple modification to the welcome page to be able to view the docs, but we decided to take this a step further. We have since created all new welcome pages, error pages, and full documentation templates, all very clean and crisp and very easy to read on the move. Taylor let me have my wicked way with the design (should he be trusting a developer with design tasks? and we are both pleased with the results. Let’s hope you are too! Here’s a quick preview for those who are too lazy to download the develop.

The Profiler

Shortly after the release of Laravel 3.1, I created a little bundle that despite my shoddy javascript received a great deal of popularity, Anbu.

Anbu is a little toolbar that sits at the bottom of your views and reports useful information such as log entries, SQL queries performed, and other neat stuff. I added a few snazzy javascript animations and ended up with a useful but pretty front-end profiler. Taylor saw the profiler a short while later and seemed to fall in love with it (people please, look at the terrible JS!) and asked if it could be included into the core. Of course it can!

I integrated Anbu with the core, and added a little bit of extra branding to make it more Laravelsexy (it’s a word) and Taylor renamed the package to Profiler. As of Laravel 3.2 you can enable profiler in the configs, and debug til you are as happy as a red panda. Enjoy!

Blade

I was using blade to write some front end forms when I thought..

Wouldn’t it be cool to be able to add comments to blade templates, to comment on the visual aspects of the application, without them being rendered at runtime.

After much debate about whether it was a justifyable feature, and the format of the comments themselves, meet the new blade comments :

{{-- a simple multiline comment --}}

{{-- a single line comment

I hope you find them as useful as I hoped they would be!

Blade also has a new @unless which acts as a simple ‘IF NOT’.

@unless(3==3)
    <p>THREE MUST BE THREE</p>
@endunless

Enjoy!

to_array()

or not to_array.. that is the question. Eloquent objects now have a to_array() method to return the object represented as a key-value array, simple!

Authentication

The Authentication system in Laravel is pretty neat, and with the addition of the config closures it became more configurable. Taylor has taken this a step further with the inclusion of Authentication drivers, allowing you to create a simple class to handle basic authentication methods, with the possibility of tieng the Authentication procedure to a data source of your choice.

Naturally Taylor has included Eloquent and Fluent drivers with 3.2 to provide some familiar defaults.

Input::json()

Now some methods to help those who are building API’s on top of Laravel. The Input::json() method allows you to retrieve the JSON payload of the Input class as an array, very handy for backbone and other JS FW’s!

You can now use Response::json() to output a JSON response from a PHP array, or Response::eloquent() to output an Eloquent object as JSON, super handy!

Well those are a few of my favorite features! The complete list of features can be found here. Thanks to everyone who has contributed to the project.

I would also like to say hi (wave) to our amazing Laravel Community members, come and join us in #laravel on freenode if you would like a chat!

We can’t let them win, the must not destroy our beautiful applications. Let’s validate all input provided by the user, that way they won’t be able to harm us at all.

Naturally Laravel has a library, aptly named ‘Validation’ that will do all the hard work for us.

Set up validation

Let’s start by creating an imaginary form, close your eyes and imagine a nice long form with many fields… uh oh… how can I get you to open your eyes again..?

Right, I will assume you got fed up of waiting, have opened your eyes, and are back with me again, along with our imaginary form. Let’s get the input data from that form.

$input = Input::get();

Now normally you don’t want to use the get() method, as its an easy way to populate your input array with extra data you don’t need. In fact the open source collaboration site github was a victim to mass assignment. I have used get() to simplify the tutorial, in your applications please build the input array only with the fields you need.

Now our input array now contains something that looks a little like this..

array(
    'name' => 'John',
    'age'  => 15
)

Let’s validate these fields to make sure they make sense to our application, before we can start the validation process we need to create a set of rules that will be used to validate each field. With the validator class, rules are defined in an array format, let’s jump right in and take a look.

$rules = array(
    'name'  => 'required|min:3|max:32|alpha',
    'age'   => 'required|integer|min:16'
);

Great, now we have some rules. The array key is the field that is being validated upon, and the array value contains a number of validation rules separate by a pipe | symbol.

In our case we are validating that both fields contain a value, by using the ‘required’ rule. The length of the users name must be a minimum of 3 characters (min:3) and a maximum length of 32 characters (max:32). The ‘alpha’ rule will check to make sure that the name field only contains letters.

Our age field must contain an integer and the value must be at least 16, you see that the min rule has adapted to fit the content that its validating, very clever!

Don’t worry, we will cover all the validation rules later, for now let’s see the validation in action, here we go.

$v = Validator::make($input, $rules);

We have made our validator object with the make() method, passing it our input array, and our rules array. Let’s see if it validates!

if( $v->fails() )
{
    // code for validation failure 
}
else
{
    // code for validation success!
}

As you can see, we use the fails() method to check the result of the validation attempt, it will return true if the validation has failed, and false if it was successful.

If you prefer a more positive outlook on your validations, you could use the passes() method, which returns the opposite values..

if( $v->passes() )
{
    // code for validation success!
}
else
{
    // code for validation failure 
}

There, now we are positive and can dance over rainbows with sparkleponies.

Errors

If your validation fails, which it will because our user is under 16 (sorry for slaying your sparklepony), you will want to find out what went wrong. The validator provides an errors Messages object which allows us to easily find the information we need.

The errors object has similar methods to the Input class, so I will not need to go over them all, let’s retrieve an array of errors for a specific field.

$age_errors = $v->errors->get('age');

Now we have an array containing all of the errors associated with the age field..

array(
    'The age must be at least 16.'
)

Most of the time I find myself using the first() method in my views, which returns the first array item if it exists, or null if it doesn’t. For example..

{{ Form::label('username', 'Username') }}
{{ $errors->first('username') }}
{{ Form::text('username') }}

Now our validation errors will appear for this field if any are present. You can also pass a second parameter to the first() method to format the output..

{{ $errors->first('username', '<span class="error">:message</span>') }}

Neat!

You can also use has() to check to see if an error exists, and all() to retrieve all errors as an array.

Validation Rules

Here is a list of validation rules, and their purpose.

required

Ensure that a value for a field is present, and is not an empty string.

alpha

The string must only consist of letters (alphabetical characters).

alpha_num

The string must only contain letters and numbers. Useful for usernames.

alpha_dash

The string must contain only letters, numbers, dashes or underscore characters. Useful for storing URL slugs.

size:5

(string) The string must be exactly five characters long.
(numeric) The value must be five.

between:5,10

(string) The length of the string must be between five and ten characters.
(numeric) The value must be between five and ten.

min:5

(string) The length of the string must be between five characters or more
(numeric) The value must be equal to or greater than five.
(file) The file size must be 5 kilobytes or more.

max:5

(string) The length of the string must be less than or equal to five.
(numeric) The value must be less than or equal to five.
(file) The file size must be 5 kilobytes or less.

numeric

The value must be numeric.

integer

The value must be an integer or whole number.

in:red,green,blue

Ensure that the value is contained within the list of values provided.

not_in:pink,purple

Ensure that none of the values provided match the value.

confirmed

The value of the field must match a confirmation field, named in the format ‘_confirmation’.

accepted

The field value must be equal to ‘yes’ or 1. Useful for validating checkboxes.

same:age

The field value must match the field specified by the same rule.

different:age

The field value must not match the field specified by the same rule.

match:/[a-z]+/

The field value must match the provided regular expression.

unique:users

This is one of my favorites, the validator will look at the users database table, and make sure that the value is unique within the column that has the same name as the field name. Useful for making sure that duplicate usernames or email addresses don’t occur.

If you would like to specify an alternate column name, simply pass it as a second parameter..

unique:users,nickname

You can also force the rule to ignore a provided id by passing it as a third parameter.

unique:users,nickname,5

exists:colors

Acts as the opposite of unique, the value must already exist in the database table. Once more you can pass a second parameter to refer to another column.

before:1984-12-12

The date provided by the field, must have occurred before the date template provided to the before rule.

The before and after filters use strtotime() to calculate a timestamp for comparison, this means you can do some neat tricks like..

before:next Thursday

Unfortunately I was on the one that added this functionality, so if it breaks you can go ahead and shout at me… sorry!

after:1984-12-12

Similar to before, only the date must occur after the date provided to the after rule.

email

The value must be a valid email address.

url

The value must match the format of an URL.

active_url

The value must match a valid active URL. checkdnsr is used to verify that the URL is active.

mimes:png,mp3

The value must be a $_FILE which whose MIME type matches the file extensions provided.
You can add additional MIME types to the array in config/mimes.php.

image

The uploaded file must be an image.

Custom Error Messages

I find the custom error messages quite descriptive, but your clients might have their own ideas. Let’s see how we can customize our error messages to suit our needs.

You can edit the validation error messages directly by modifying the file application/language/en/validation.php…

...
"after"          => "The :attribute must be a date after :date.",
"alpha"          => "The :attribute may only contain letters.",
"alpha_dash"     => "The :attribute may only contain letters, numbers, and dashes.",
...

Laravel replaces the :attribute marker with the name of the field. Other markers also exist within the rules, and their purpose is quite self explanatory.

If you would rather change the messages for a single form, rather than edit them globally, you can pass a third array of messages to the Validator::make() method.

$messages = array(
    'same'    => 'The :attribute and  ther must match, fool!',
    'size'    => 'The :attribute must be exactly :size , like duh!'
);

$v = Validator::make($input, $rules, $messages);

Great now we have custom messages! We can even specify error messages for individual fields, by setting the message key to field_rule, for example..

$messages = array(
    'age_required'    => 'You need to have had at least one birthday!'
);

Custom Validation Rules

The validator allows you add extra rules to suit the needs of your application, let’s jump right in and take a look at how we register a new validation rule.

Validator::register('superdooper', function($attribute, $value, $parameters){
    return $value == 'superdooper';
});

Our newly created validation rule superdooper will ensure that our value matches the string ‘superdooper’. Your custom validations should return true on success, or false on failure.

The $attribute value will be the name of the field being validated, and $value will of course contain the value.

The $parameters attribute contains an array of parameters that have been passed to the rule after the colon, and separated by commas.

As you have created a new validator, there will be no error messages associated with it yet, we will need to add one so that Laravel knows what to say when it fails. We can add an error message in the same way as we have previously..

'superdooper' => 'The :attribute must be superdooper, ok trooper?!',

Once again you can pass the extra error message array as a third parameter to the Validator::make() method, or simply add it to your application/language/en/validation.php file for safe keeping.

Validation Classes

If we want to provide many new validation methods, or reuse them across a number if projects, it would be best to create a validation class. Validation classes extend Laravel’s data, and overload it with additional validation methods. The class is created in the application/libraries directory for easy loading, but you could place it elsewhere as long as it is registered with the Autoloader (later post). Let’s take a look at the class.

<?php

// application/libraries/validator.php

class Validator extends Laravel\Validator {

    public function validate_awesome($attribute, $value, $parameters)
    {
        return $value == 'awesome';
    }

}

As you can see our Validator class extends the Laravel\Validator namespaced core class and provides additional validations in the form of validate_<rulename> methods. The validation methods accept the same parameters as the Validator::register() closure, and work in the same way.

In order to use our new validation class, we will need to remove the existing alias for Validator from our application/config/config.php file. This way Laravel will use our created class instead of the one in the Laravel source folder.

You could use this method to replace the original validation methods with your own, for example you could create a validate_size method and calculate the size in an alternate format.

I would suggest adding custom error messages to the validation language file when using Validation classes, this will allow for a much easier migration to another project, and will not require any ‘source-digging’ to find all the messages used.

In the next post, we will cover some typical form validation scenarios that are common to web applications, this includes input forms, edit forms, form re-population and more.

One Way Encryption

One way encryption is the best way to store user passwords, or other sensitive data. One way means that your data can be converted into an encrypted string, but due to a complex algorithm with painful maths, reversing the process is not possible.

This makes storing passwords a doddle! Your customers don’t have to worry about you knowing their passwords, but you are still able to compare them (by hashing the password they provide) or change the password if needed.

Note that hashing is the process of creating a hash or encrypted string from another string.

Let’s take a look at how password hashing works with one way encryption.

$pass = Input::get('password');

Now we have retrieved the password from our ‘create user’ form, but it’s in plain-text! Let’s hash it quickly so we can store it securely in our database.

$pass = Hash::make($pass);

We have used another of Laravel’s highly expressive methods, this time make()ing a new Hash. Our $pass value will now contain a bcrypt encrypted version of our password, neat!

Let’s say that our user has entered their password to login, and now we need to check to see if its authentic before they can be logged into the system. We can simply compare our hash to the value stored in the database with the check() method.

$pass = Input::get('password');
if ( Hash::check($pass, $user->password) )
{
    // auth successful
}

The check() method accepts two parameters, the plain-text value provided by your user, and the hashed password that you have stored. It returns a boolean value to indicate whether the true values match or not.

What if we want to decode our data at a later date? Let’s two way encrypt it.

Two Way Encryption

Two way encryption, allows you to return your encrypted data to its original form, kind of like those spy code sheets you played with when you were a kid!

The Laravel Crypter class uses AES-256 encryption which is provided by the Mcrypt PHP extension, so make sure that this PHP extension has been installed before attempting to use the class!

The Crypter class works using two simple methods, encrypt() and decrypt(), let’s take a look at encrypting a string.

$secret = Crypter::encrypt('I actually like Hello Kitty');

Now our dirty little secret has been AES-256 encrypted, and the result has been returned. This would be of no use if we couldn’t decrypt the secret at a later date. Let’s look at how you can decrypt an encrypted piece of data.

$decrypted_secret = Crypter::decrypt($secret);

Easy as that! Simply hand the encrypted string to the decrypt() and the decrypted result is handed back.

Enjoy using the Crypter class to simulate the feeling of using your super secret decoder rings you got that one time in a cereal box!

IoC stands for Inversion of Control, I don’t want to complicate things with a full description, there are many online articles which will cover the nerdier side of this topic. Instead think of the container as ‘Inverting the Control’ or ‘Handing control back to Laravel’ to resolve our objects.

That’s what the container is all about, resolving objects. Other than its use for injecting dependencies for use in unit tests (we will cover this later) you can simply think of the IoC container as a ‘shortcut’ for resolving complex objects, or following a singleton pattern, without the usual class associated with the pattern. More on singletons later, let’s have a look at registering a objects with the container.

Registering Objects

Let’s use our imaginations, like the big purple dinosaur on the TV taught us. We will be imagining a class called ‘Discoball’ which will be used all over our application for various groovy purposes.

Unfortunately, our Discoball class requires a lot of configuration before it can be used, let’s have a look at that.

$db = new Discoball(Discoball::SHINY);
$db->configure_shinyness('max');
$db->spin_speed('8900rpm');

Woah! That’s a lot of settings. Now it would soon get boring to have to instantiate and setup our discoball every time we want to use it. Let’s let the IoC container instantiate it for us, and jump right in with a code sample.

I like to put this code into start.php, but you can put it anywhere you like, as long as your objects are registered before you try to resolve them.

// application/start.php
IoC::register('discoball', function() {

    // instantiate our object as before
    $db = new Discoball(Discoball::SHINY);
    $db->configure_shinyness('max');
    $db->spin_speed('8900rpm');

    // hand the object as the result of the closure
    return $db;
});

We use the IoC::register() method to register our object with the controller. The first parameter is a string that will be used to resolve the object later, I used the word ‘discoball’ as it made the most sense to me. The second parameter is a closure that we can use to instantiate our object.

Inside the closure you will see the familiar discoball configuration code, and we will return the configured discoball object from the closure.

Great! Our object is registered, and that’s all there is to the Io… just kidding. Let’s have a look at how we can use our registered object.

Resolving Objects

Now we have our disco ball registered, let’s see how we can get it back. Let’s make a call to resolve.

$db = IoC::resolve('discoball');

And that’s it! Instead of creating and configuring a new instance of our discoball each time, we make a call to the resolve() method, passing the string that identifies the object and the IoC container will execute the closure we created in the first section, and return our instantiated and configured discoball object.

Handy, and saves many lines of code!

You can register and resolve as many objects as you want, go ahead and try it. For now lets move on to singletons.

Singletons

Resolving our discoball is useful, but what if our discoball was expensive on resources to instantiate, or should only be instantiated once? The register method will not be useful in this case, since the closure is executed with every call to resolve() and a new instance of the object is returned each time. This is where the singleton design pattern comes in.

The singleton design pattern involves writing your classes in a certain way, so that they can be called using a static method, and will always return the same instance of itself. This way the class is instantiated only once.

For more information on the Singleton design pattern, I would suggest a quick Google search, or check out the PHP API which has an article on the subject.

Singletons can be useful, but they require a certain class structure to be able to use them. The IoC container has a singleton() method which makes the process a lot more simple, and does not require any special kind of class. Let’s register our discoball as a singleton instead..

// application/start.php

IoC::singleton('discoball', function() {

    // instantiate our object as before
    $db = new Discoball(Discoball::SHINY);
    $db->configure_shinyness('max');
    $db->spin_speed('8900rpm');

    // hand the object as the result of the closure
    return $db;
});

As you can see, the process is almost identical to registering an object, except that we use the method singleton() which accepts the same parameters.

When we resolve our discoball, the closure will only be run the first time resolve() is called, the resulting object will be stored, and any future calls to the resolve() method will return the same object instance. For example..

// closure is executed, and a discoball
// instance is returned
$db = IoC::resolve('discoball');

// the same instance of the discoball
// in the above statement is returned
$another = IoC::resolve('discoball');

Great! It’s also worth noting that you can pass an already instantiated object as a second parameter to the singleton() method, and it will be returned by all future requests to resolve() for example..

$db = new Discoball(Discoball::SHINY);
IoC::singleton('discoball', $db);

// get hold of our discoball
$ball = IoC::resolve('discoball');

In a future post we will discuss using the IoC container and dependency injection in combination with unit testing.

Thanks to Andrew Smith and Julien Tant (AoSix) for buying the book. Julien had the following to say..

Hey Dayle, thanks a lot for this book, the Laravel framework is just awesome ! If any french guys read this, visit http://www.laravel.fr/ !

Thanks guys, and great work translating the tutorials to French!

Also thanks to Proger_XP for buying the book and translating my tutorials to Russian, which are available at Laravel.ru. Great work!

Request data

Let’s use the Input class to handle this instead.

$panda = Input::get('panda');

Now we have a Panda! Great.. we have too many already. One thing you need to remember about the get() method on the Input class, is that it doesn’t refer to $_GET data, get() is just a nice and expressive short method name for retrieving all kinds of data. The input class adds responds to get() with all kinds of request data, including $_POST.

If a piece of request data isn’t set, the Input class will return null. If you pass a second parameter to the get() method and the index doesn’t exist, then the method will return the second parameter instead. Very useful!

$panda = Input::get('panda', 'Muffin');

If you would like to retrieve the entire request array, simply skip the index. Easy as that.

$morepandas = Input::get();

By default the get() array won’t includes values from the $_FILES array, however if you use all() instead of get() it will contain files too.

$pandas_and_files = Input::all();

If you would like to check if a piece of post data exists, without actually returning it, simply use the elegant and highly expressive has() method, which will return a boolean result.

Files

To access an element from the $_FILES array, simple make a call to the Input::file() method, for example..

$file = Input::file('spoon');

If you simply want to retrieve a file attribute, then add a period, and an attribute key to the first parameter, for example to retrieve the file size..

$size = Input::file('spoon.size');

Once again, calling the method without a parameter will retrieve the full array of files.

$files = Input::file();

Flash Data

Flash data is a useful method of storing data for use in the next request, this can be a useful method of repopulating forms.

To flash all request data to the session, for it to be accessible in the next request, simply use the flash() method.

Input::flash();

If you only want to flash a portion of the current request data, simply pass ‘only’ as the first parameter to the method, and an array of field names that you wish flashed as the second parameter.

Input::flash('only', array('betty', 'simon'));

Now we will take Betty and Simon with us to the next request. Alternatively we could specify a list of fields that we don’t want to take with us using the except option, for example..

Input::flash('except', array('uncle_bob'));

There, now we can leave Uncle Bob behind, he’s an arrogant soul, and dislikes our national animal the red panda.

Now we can use the usual Redirect::to() method to move to a new request. From here we can use the expressive Input::old() method to retrieve a value that has been flashed from a previous request.

$betty = Input::old('betty');

As you can see, Betty has survived the transition. You can think of flash data as those fuzzy transporter pads from Star Trek, moving Kirk and his buddies from one request to the next.

Once again you can skip the parameter to return a full array of flash data.

$people = Input::old();

You can use the had() method to see if an index of flash data exists.

Input::had('uncle_bob');

Of course not, we hate Uncle Bob.

Laravel wouldn’t be the framework it is, without its wonderful shortcuts and expressive methods. Let’s have a look at a prime example of this in action.

return Redirect::to('party')->with_input();

The with_input() method will flash all of our request data for us, it also accepts the same only and except methods as our flash() method.

return Redirect::to('party')->with_input('only', array('betty', 'simon'));
return Redirect::to('party')->with_input('except', array('uncle_bob'));

If you haven’t been living under a rock for the past couple of decades you will already know what hyper-links are, and I won’t bore you with the technical explanation. Before we have a look at links let’s take a look at how Laravel handles its URLs.

Retrieving URLs

First let’s take a look at a problem. You see frameworks have very unique URL structures, some may have an index.php in them, some installations won’t. Others will have complex routes. In most cases using a relative URL like you would on another website would lead to trouble in the long run. If you chose to provide full URL’s to everything, and decided to move the application at a later date, you might find yourself abusing the find and replace function of your favorite editor.

Why not let Laravel do all the hard work? Laravel knows the full URL to your application, it knows whether or not you are using URL rewriting. It even knows about your routes. Let’s take advantage of this information by using the URL class to generate some site URLs.

Let’s start by finding the URL to the root of our website. We can use the base() method for this.

echo URL::base();

Great! Now we have the full URL to our site, with or without the index.php on the end, it all depends on your current setup. What about the current URL, the one that is being routed at the moment, can we get that? You betcha! Simply use the current() method.

echo URL::current();

By default, Laravel will strip off the query string, if one is appended to the URL. If we want to retrieve the current URL along with the query string, we can use the full() method instead.

echo URL::full();

Knowing our base URL and current URL can be handy, but it would be more useful if we could get the URL to other routes or pages, then we could create links.

To generate a URL to a route, we use the to() method, and hand it the route we are trying to retrieve, this is much easier than specifying the full path, for example..

echo URL::to('my/route');

If we wan’t to link to this page securely, via the HTTPS protocol we can use the method to_secure() instead.

echo URL::to_secure('my/route');

Do you remember being taught about named routes in the routing post? Of course you do! Here’s an example of one again..

Route::get('login', array('as' => 'login', 'do' => function() {
    // some code
}));

Here we have a route that we have named ‘login’ using the ‘as’ array key. Well I told you that it would be useful later, and now is the time for named routes to shine. Let’s make a link to our named ‘login’ route..

echo URL::to_route('login');

Woah! Very clean and expressive I think you will agree. What if we need to supply parameters to our route? Simple, just pass an array of parameters as a second parameter to the to_route() method. Let’s imagine for a second that our login route looks more like this…

Route::get('my/(:any)/login/(:any)/page')..

It’s a terrible route, please don’t use ugly URL’s like this one, but it will help to illustrate a point. You see if you pass parameters to the to_route() method, Laravel will automatically work out which order they should appear in the URL, and return the full URL with the parameters in the right place, neat!

echo URL::to_route('login', array(5, 7));

The above method would give us..

http://myapp/my/5/login/7/page

Great! Now our routes will look squeaky clean.. as long as we don’t create routes as complicated as that one.

So that’s routes cleared up, but we shouldn’t forget controllers. No one likes to be left out. Fortunately there’s a nice and clean way to create a link to a controller action. Simply use the to_action() method, for example..

echo URL::to_action('dashboard@home');

Simply pass the controller name and action, separated by an @ (at) symbol. Once again you can pass an array of extra parameters as a second parameter to the to_action() method if you need to.

If we are dealing with assets, a CSS style-sheet for example, rather than routes pages we will need a very different URL. We can’t use URL::to() because that might put an index.php in the URL, or resolve it to one of our routes.

Instead we can use the to_asset() method to generate a correct link. Simply pass the application relative path to our style-sheet, and Laravel will take care of the rest.

echo URL::to_asset('css/style.css');

This line will give us..

http://myapp/css/style.css

These methods are already very handy, but Laravel takes this a step further by providing shorter helper methods which look great when used in our views. Here is a list of these helpers, and their longer alternatives.

Generating Links

Now that we can retrieve our site links, the next logical step would be to use them to create hyper-links, now I know what you’re thinking, we can do it like this..

<a href="<?php echo URL::to('my/page'); ?>">My Page</a>

Sure that would work, but it’s a little ugly. In Laravel if something is a little ugly, there is always a better way of handling it. Links are no exception.

Why don’t we use the HTML class to generate a link? After all, that’s what the HTML class is for. It is used to generate all kinds of HTML tags.

<?php echo HTML::link('my/page', 'My Page'); ?>

That looks a lot better! Let’s see the result.

<a href="http://localhost/develop/index.php/my/page">My Page</a>

If you are an SEO ninja, and cannot stand to see a link without a title attribute, simply pass an extra array.

<?php echo HTML::link('my/page', 'My Page', array('title' => 'My page!')); ?>

Which gives..

<a href="http://localhost/develop/index.php/my/page" title="My page!">My Page</a>

One of the great features of Laravel is how consistent its method naming is, many of the HTML::link methods follow a similar naming pattern as the URL::to methods, which makes them easy to remember. Let’s take a look at how we can link to a secure page (via HTTPS).

HTML::link_to_secure('my/page', 'My Page');

We can also use link_to_route, to create a link to a named route just like we did with the URL library.

HTML::link_to_route('login', 'Login!');

Once again we can use the link_to_action() method to link to a controller-action pair, for example..

HTML::link_to_action('account@login', 'Login!');

Laravel even gives us a method of easily creating ‘mailto’ links from an email address. Let’s take a look.

HTML::mailto('me@daylerees.com', 'Mail me!');

Nice and clean!

Now that you know how to create URL’s and links, your applications will start to grow in size, covering many routes until they consume our planet and take over the unive…

Your applications will be a lot more interesting!

Fortunately for me, Laravel’s form class takes care of a lot of the hard work for us, by providing useful methods for generating common form elements. Let’s use the form class to create a simple web form in one of our views.

Creating Forms

// form.php
<?php echo Form::open('my/route'); ?>

    <!-- username field -->
    <?php echo Form::label('username', 'Username'); ?>
    <?php echo Form::text('username'); ?>

    <!-- password field -->
    <?php echo Form::label('password', 'Password'); ?>
    <?php echo Form::password('password'); ?>

    <!-- login button -->
    <?php echo Form::submit('Login');

<?php echo Form::close(); ?>

Take a moment, stare at the form source, you have never seen a form so clean. Say it out loud to yourself, go on.. I will wait.

I have never seen a form so clean.

You are right, its beautiful, let’s have a look at the generated source to make sure I’m not just teaching you wrong, you know, for fun?

<form method="POST" action="http://mysite/my/route" accept-charset="UTF-8">

    <!-- username field -->
    <label for="username">Username</label>
    <input type="text" name="username" id="username">

    <!-- password field -->
    <label for="password">Password</label>
    <input type="password" name="password" id="password">

    <!-- login button -->
    <input type="submit" value="Login">

</form>

Great, it worked! I mean of course it did! Let’s go over the form line by line to see how it works, on our first line we have the Form::open() method, which creates a form open tag for us.

The first parameter to the method is the URI we wish to submit the form to. The second parameter is the METHOD used to submit the form, if you don’t provide a method as a string Laravel will assume that you want a POST form, which is the most common usage.

The third parameter is also optional, you can pass an array of attribute => value pairs to add extra attributes to the <form> tag. For example if you wished to target the form with Javascript you may want to pass array('id' => 'myform') as the third parameter to give the element an id.

To submit a form to a secure URI (https) you will need to use the open_secure() method instead of open(), it accepts the same parameters.

If you wish to be able to have files uploaded from your form, it will need to use multipart/data, use open_for_files() instead of the open() method. This method also accepts the same parameters.

Finally if you wish to submit to a secure URI, and have files uploaded you will need to use the open_secure_for_files() method, which once again accepts the same parameters, and is a combination of both open_secure() and open_for_files().

Adding Labels

The next line contains the Form::label() method which is used to create a <label> element. The first parameter is the name of the input element that it describes to be used in the for="" attribute. The second parameter is what will be used as the content of the label element. You can pass an array as an optional third parameter to apply extra HTML element attributes.

Generating Inputs

Next we have the input generators, these methods help to generate all of the HTML elements that are common to forms. In the example above we use the text() and password() method to generate <input type="text".. and <input type="password".. elements.

The first parameter to the method, is the value of the elements name attribute, the second optional parameter is the default value of the element. Once more we can pass an array of HTML attributes as an optional third parameter, are you starting to see a pattern yet?

The textarea() and hidden() fields also accept the same parameters.

Checkboxes can be created using the checkbox() method, with the first parameter being the name of the element, the second being the value, and the third option is an optional boolean switch to set whether the element is initially checked or not. The fourth optional parameter again sets attributes, in fact.. go ahead an assume all future inputs accept an attributes array as their optional final parameter. Let’s have a look at a checkbox generator..

<?php echo Form::checkbox('admin', 'yes', true, array('id' => 'admin-checker')); ?>

The radio() method creates radio buttons, and shares the same parameters as the checkbox() method.

Next we have drop downs, the most awkward of all form elements. Fortunately all we need to do is pass a name, an array of value => label options, and an optional parameter to state which option should be selected by default to the select() method. Our dropdown will then be generated for us, for example..

Form::select('roles', array(
    0 => 'User',
    1 => 'Member',
    2 => 'Editor',
    3 => 'Administrator'
), 2);

and we get..

<select name="roles">
    <option value="0">User</option>
    <option value="1">Member</option>
    <option value="2" selected="selected">Editor</option>
    <option value="3">Administrator</option>
</select>

Great! Now it’s time to submit our form.

Generating Buttons

The submit() and button() generator methods both accept the same parameters, the first being the value of the HTML element, and the second being the usual array of attributes.

Form::submit('Login');

Secret Inputs

There are also a number of extra generation methods for less common form inputs that aren’t covered by the documentation. Here is a listing of them, with their parameters.

Form::search($name, $value = null, $attributes = array());
Form::email($name, $value = null, $attributes = array());
Form::telephone($name, $value = null, $attributes = array());
Form::url($name, $value = null, $attributes = array());
Form::number($name, $value = null, $attributes = array());
Form::date($name, $value = null, $attributes = array());
Form::file($name, $attributes = array());

CSRF Token

If you intend to use the CSRF filter (which will be covered in a later post) you can add the CSRF token to your form by using the method token(), for example..

Form::token();

Form Macros

Laravel has provided many different input methods, but what if we need something a little more custom? Fortunately Laravel has provided the macro method to allow us to create our own input generators.

By passing an input name, and a closure to the macro method we can define our own input generator, let’s take a look.

Form::macro('shoe_size', function() {
    return '<input type="show_size" />';
});

Now we can use the Form class to generate our shoe size field in the same way as any other input, for example..

<?php echo Form::shoe_size(); ?>

If you need to use parameters, simply add them as parameters to the closure. Enjoy creating your own unique input generators!

DB::table('users')->where('name', '=', 'dayle')->take(5)->get();

It’s a system that simply makes sense to use, and is very clear to read. Today I am going to help you build chainable classes, so that your libraries will start to feel more ‘Laravelish’. (If that isn’t a real word we need to make it one.)

I’m going to start by showing you a chainable class, all done.

class Ball
{
    private $size = 1;
    private $color = 'blue';
    private $texture = 'squishy';

    // creator
    public static function make()
    {
        $ball = new Ball();
        return $ball;
    }

    // chain
    public function size($size)
    {
        $this->size = $size;
        return $this;
    }

    // chain
    public function color($color)
    {
        $this->color = $color;
        return $this;
    }

    // chain
    public function texture($texture)
    {
        $this->texture = $texture;
        return $this;
    }

    // trigger
    public function get()
    {
        return "This is a {$this->texture} {$this->color} ball, size {$this->size}.";
    }
}

I bet its not as complicated as you thought it would be! Before we can look at how it works, first you will need to know the three parts of a chainable class. I will use my own names for these parts, feel free to borrow them!

Creator

The creator method is normally static, and is used to create a new instance of the class. It will always return the class instance as the result of the method. In my example the creator is make().

Chains

Chains are methods which alter the class in some way. They are non-static public methods, which set class attributes with the new settings passed to them. Chains will always return the current instance of the class, which is $this.

Triggers

Trigger methods are found at the end of the chain. They are the methods that make use of all of class attributes we have changed. They either perform an action, or return a result.

Let’s have a closer look at each part of our class, first the Creator method make().

// creator
public static function make()
{
    $ball = new Ball();
    return $ball;
}

As you can see, a static call to make creates a new instance of our class, and hands it back as the result. So this line of PHP is perfectly acceptable..

$ball = Ball::make();

Similar to..

$ball = new Ball();

Now we know what our creator method does, let’s have a closer look at the chain methods..

// chain
public function size($size)
{
    $this->size = $size;
    return $this;
}

// chain
public function color($color)
{
    $this->color = $color;
    return $this;
}

// chain
public function texture($texture)
{
    $this->texture = $texture;
    return $this;
}

The chain methods are making changes to class attributes using the parameters provided to them, and returning the current object instance, which can always be found using $this.

So now we could use the following code..

$ball = Ball::make();
$ball->color('red');

This is perfectly fine, but it could look better. The make() method is returning an object instance, so we can attach our chain method on to the end, to call the method on the object instance that has been returned. Therefore the code..

$ball = Ball::make()->color('red');

Which will perform in the same way as the last code snippet. We can attach as many chains as we want, because they all return the current object instance, for example..

$ball = Ball::make()->color('red')->size(5)->texture('fuzzy');

The chains can also be added in any order we like.

To make use of our changes we will need to use a trigger method, in our class the trigger method is get().

// trigger
public function get()
{
    return "This is a {$this->texture} {$this->color} ball, size {$this->size}.";
}

The get() method makes use of all our newly set class attributes and returns a short sentence describing the ball that we have made.

echo Ball::make()->size(4)->get();

gives..

This is a squishy blue ball, size 4.

In this example I have simply supplied the size() chain, which works fine because I have set default values for all my class attributes.

So now we know how to make a chainable class, and some ‘Laravelish’ libraries, go forth and make clean, expressive bundles!

By now you should be used to creating a Route stub for your controllers, something that looks a little bit like this..

Route::controller('controllername');

If you have progressed a little you may even be passing an array to simplify the process. By creating the stubs you are letting Laravel know that the controller exists, and is routable, this enables a load of cool functionality powered by reverse routing.

However, if you have migrated from another well known framework (who’s name sounds like burning your source code) you may be familiar with URI’s such as..

myapp.com/controller/action/param/param/param

In this case the first segment of the URL points to the controller in use, the second segment points to the controller action, and any additional segments are passed as parameters to the action. This is how ‘that other framework’ handles it, and does not force you to register routes.

Well here’s a quick tip to force Laravel to route in a similar way, only reverse routing will still be available! Simply pass the Controller::detect() method to the Route::controller() method, for example..

Route::controller(Controller::detect());

You see the Controller::detect() method will look at the filesystem, and detect all Controllers for the DEFAULT_BUNDLE which is our application folder. It will then return an array containing all the controllers it found. The Route::controller() method will then take that array, and register all of the controllers within the Routing engine, simple!

You can even pass a bundle name as a parameter to the detect() method to register all controllers for that bundle, for example..

Route::controller(Controller::detect('mybundle'));

Enjoy using your psychic controllers!