How does the Laravel 4.1 documentation work?

Question

I've gotten a start with how Laravel works from its docs as well as from tutorials and SO. But I keep running into the same problem when I try to use their API/class reference.

For example, I've been able to use the URL class like this:

URL::to('string')

Which I learnt about from a tutorial. But if I look at the documentation for Illuminate\Support\Facades\URL it doesn't list a to() method.

Conversely, if I look at the documentation for Illuminate\Filesystem\Filesystem and I try to call the get() method like this:

$file = new Filesystem;
$file->get('lorem.txt');

I get the following error

Class 'Filesystem' not found

My questions:

How do I know which Classes I can use and which Methods I can call?
Where do I find this information?
Or am I just missing something about how Laravel works?

Antonio Carlos Ribeiro Antonio Carlos Ribeiro · Accepted Answer · 2013-12-18T10:32:33

Laravel uses a Design Pattern called Facade, it is basically an alias for the instantiated object so you can use it this way:

URL::to('string');

Instead of

$url = new URL;
$url->to('string');

Take a look at your app/config/app.php and you'll see the URL alias pointing to the Facade:

'URL' => 'Illuminate\Support\Facades\URL',

If you look at the Facade you'll see the real "internal" name of it ('url'), in the IoC container:

protected static function getFacadeAccessor() { return 'url'; }

This 'url' object is instantiated by a Service Provider somewhere, this one is binded to the IoC container in the Illuminate\Routing\RoutingServiceProvider:

/**
 * Register the URL generator service.
 *
 * @return void
 */
protected function registerUrlGenerator()
{
    $this->app['url'] = $this->app->share(function($app)
    {
        // The URL generator needs the route collection that exists on the router.
        // Keep in mind this is an object, so we're passing by references here
        // and all the registered routes will be available to the generator.
        $routes = $app['router']->getRoutes();

        return new UrlGenerator($routes, $app->rebinding('request', function($app, $request)
        {
            $app['url']->setRequest($request);
        }));
    });
}

And there you can see that 'url' is, in fact, UrlGenerator ->(http://laravel.com/api/4.1/Illuminate/Routing/UrlGenerator.html).

Here's the to() method:

/**
 * Generate a absolute URL to the given path.
 *
 * @param  string  $path
 * @param  mixed  $extra
 * @param  bool  $secure
 * @return string
 */
public function to($path, $extra = array(), $secure = null)
{
    // First we will check if the URL is already a valid URL. If it is we will not
    // try to generate a new one but will simply return the URL as is, which is
    // convenient since developers do not always have to check if it's valid.
    if ($this->isValidUrl($path)) return $path;

    $scheme = $this->getScheme($secure);

    $tail = implode('/', (array) $extra);

    // Once we have the scheme we will compile the "tail" by collapsing the values
    // into a single string delimited by slashes. This just makes it convenient
    // for passing the array of parameters to this URL as a list of segments.
    $root = $this->getRootUrl($scheme);

    return $this->trimUrl($root, $path, $tail);
}

It's a little confusing at start, but you just have to remember:

1) Find the Alias.

2) Find the Facade and get the real internal name.

3) Find the ServiceProvider to find the real class.

How does the Laravel 4.1 documentation work?

3 Answers