PHP
Article

Use Laravel Contracts to Build a Laravel 5 Twig Package

By Younes Rafie

Laravel 5 is finally out, and with all the awesome features it brings. One of the new architectural changes is the new Contracts Package. In this article we are going to understand the reasoning behind this change and try to build a practical use case using the new Contracts.

Laravel

What Is a Contract

A contract is an interface that defines a behaviour. Let’s take this definition from Wikipedia.

In object-oriented languages, the term interface is often used to define an abstract type that contains no data or code, but defines behaviors as method signatures.

With that being said, we use interfaces to extract the object behaviour from a class to an interface and only depend upon the definition. In Laravel’s IoC container you can bind an interface to an implementation.

$this->app->bind('App\Contracts\EventPusher', 'App\Services\PusherEventPusher');

Now every time you resolve the EventPusher interface from the container, you will receive a Pusher implementation. If you decide to switch to another service like Fanout, you only need to change the binding.

$this->app->bind('App\Contracts\EventPusher', 'App\Services\FanoutEventPusher');

Most of Laravel core services now are extracted to a contract, and if you want for example to override the Illuminate/Mail service, you can implement the Illuminate\Contracts\Mail contract and define the necessary methods and add it a s a provider.

Laravel View Contract

Laravel uses its own template engine called Blade. However, I want to use Symfony Twig as my template engine. Blade already offers the possibility to register your own extensions; check the Twig Bridge for more info. Laravel 5 has a better way to achieve the same goal using Contracts, so let’s create our own implementation.

Defining The Package

To start building our package, we need to define it inside the composer.json file. We require Twig and autoload our src folder as our root namespace.

// composer.json
{
  "name": "whyounes/laravel5-twig",
  "description": "Twig for Laravel 5",
  "authors": [
    {
      "name": "RAFIE Younes",
      "email": "younes.rafie@gmail.com"
    }
  ],
  "require": {
    "twig/twig": "1.18.*"
  },
  "autoload": {
    "psr-0": {
      "RAFIE\\": "src/"
    }
  }
}

View Service Provider

The preferable way to register your package bindings is through a Service Provider.

// src/RAFIE/Twig/TwigViewServiceProvider.php

public function registerLoader()
{
  $this->app->singleton('twig.loader', function ($app) {
    $view_paths = $app['config']['view.paths'];
    $loader = new \Twig_Loader_Filesystem($view_paths);

    return $loader;
  });
}

The registerLoader method will bind our Twig Loader to the container. The $app['config']['view.paths'] contains our view paths. By default, it has only the resources/views folder.

// src/RAFIE/Twig/TwigViewServiceProvider.php

public function registerTwig()
{
  $this->app->singleton('twig', function ($app) {
    $options = [
        'debug' => $app['config']['app.debug'],
        'cache' => $app['config']['view.compiled'],
    ];

    $twig = new \Twig_Environment($app['twig.loader'], $options);

    // register Twig Extensions
    $twig->addExtension(new \Twig_Extension_Debug());

    // register Twig globals
    $twig->addGlobal('app', $app);

    return $twig;
  });
}

The Twig_Environment class is the Twig core class. It accepts a Twig_LoaderInterface and a list of options:

  • $app['config']['app.debug'] retrieves our debug flag from the config file.
  • $app['config']['view.compiled'] is our compiled views path registered inside the config/view.php file.

The $twig->addGlobal method registers a variable to be available for all views.

// src/RAFIE/Twig/TwigViewServiceProvider.php

namespace RAFIE\Twig;

class TwigViewServiceProvider extends ServiceProvider
{
	public function register()
	{
	   $this->registerLoader();
	   $this->registerTwig();
	
	   $this->app->bind('view', function ($app) {
	     return new TwigFactory($app);
	   });
	 }
}

The register method will bind the twig and twig.loader to the container. The view key was previously holding the Blade view factory, now it will resolve our new TwigFactory class which will be responsible for rendering our view.
Laravel won’t load your service provider by default, so you need to register it inside your config/app.php providers array. We will also comment out the Laravel view service provider.

// config/app.php

...
'providers' => [
	'RAFIE\Twig\TwigViewServiceProvider',
	//'Illuminate\View\ViewServiceProvider',
...

View Factory

The TwigFactory class must implement the Illuminate\Contracts\View\Factory interface to get the shape and behaviour of the view system. This class will do the job of passing the view to the Twig parser. To achieve more loose coupling, we have a TwigView class which implements the Illuminate\Contracts\View\View contract. This class will behave as a bag for the view object, and will have a reference to the TwigFactory class.

// src/RAFIE/Twig/TwigFactory.php

class TwigFactory implements FactoryContract
{

  /*
   * Twig environment
   *
   * @var Twig_Environment
   * */
  private $twig;

  public function __construct(Application $app)
  {
    $this->twig = $app['twig'];
  }

  public function exists($view)
  {
    return $this->twig->getLoader()->exists($view);
  }

  public function file($path, $data = [], $mergeData = [])
  {
    // or maybe use the String loader
    if (!file_exists($path)) {
      return false;
    }

    $filePath = dirname($path);
    $fileName = basename($path);

    $this->twig->getLoader()->addPath($filePath);

    return new TwigView($this, $fileName, $data);
  }

  public function make($view, $data = [], $mergeData = [])
  {
    $data = array_merge($mergeData, $data);

    return new TwigView($this, $view, $data);
  }

  public function share($key, $value = null)
  {
    $this->twig->addGlobal($key, $value);
  }

  public function render($view, $data)
  {
    return $this->twig->render($view, $data);
  }
	
  public function composer($views, $callback, $priority = null){}

  public function creator($views, $callback){}
  
  public function addNamespace($namespace, $hints){}

}

We resolve the twig object from the container with the parameters explained previously and we start implementing method’s logic. I omitted the last three functions, because defining them will involve creating events and dispatching them, and will make our simple example more complex. The make method returns a new TwigView instance with the current factory, view, and data.

// src/RAFIE/Twig/TwigView.php

use Illuminate\Contracts\View\View as ViewContract;

class TwigView implements ViewContract
{
  /*
   * View name to render
   * @var string
   * */
  private $view;

  /*
   * Data to pass to the view
   * @var array
   * */
  private $data;

  /*
   * Twig factory
   * @var RAFIE\Twig\TwigFactory
   * */
  private $factory;


  public function __construct(TwigFactory $factory, $view, $data = [])
  {
    $this->factory = $factory;
    $this->view = $view;
    $this->data = $data;
  }
  
  public function render()
  {
    return $this->factory->render($this->view, $this->data);
  }

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

  public function with($key, $value = null)
  {
    $this->data[$key] = $value;

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

Let’s take a normal scenario where we have our index page route that returns a home view, and we also provide a variable that ensures our data is passed to the view.

// app/Http/routes.php

Route::get('/', function(){
	return View::make('home.twig', ['name' => 'younes']);
});

// we can also pass the name by chaining the call to the `with` method.
Route::get('/', function(){
	return View::make('home.twig')->with('name', 'younes');
});
// resources/views/home.twig

 <h2>Hello {{ name|upper }}</h2>

Home

When you hit your application’s index page, the execution flow will be:

  • The View facade will be resolved from the container and return a TwigFactory instance.
  • The make method is called and it returns a new TwigView instance with the factory, view and data.
  • Laravel Router accepts a Response object or a string as a request response, so the __toString method is called on our TwigView instance. The render method inside the TwigFactory calls the render method on the Twig_Environment object.

When using contracts, the application API is always consistent, so testing the other implemented methods will be done the same way as before.

// test if a view exists
View::exists('contact.twig');

// render a view from a different folder
View::file('app/contact.twig');

Conclusion

Check out the final version of the project here.

The new Contracts package provides a better way to extend Laravel core components, and provides a stable API for developers to access the framework’s behaviour. Let me know what you think about the new Contracts package in the comments, and if you have any questions don’t hesitate to post them below.

Comments
s_molinari

Thanks for the informative post. I have some things I am a bit uncertain/ confused about.

If a contract is only the concept of an interface, why give an interface a different name with the term "contract"? Or is that the name given for the easy binding method Laravel offers?

Also the lines of code between the two "contracts" in your example of EventPusher and FanoutPusher(?) would need to be different somehow, wouldn't they?

You say Blade offers its own methods for extension, then refer to the Twig Bridge. The one has nothing to do with the other, does it? Or does the Twig Bridge just hold one or more examples of a blade extension in it?

And is your use of the ViewFactory and View contracts the better way to build the actual Twig bridge? If yes, does that mean the version 0.7 of the Twig Bridge is a work around?

Last question, one of the strengths of Twig is its ability to compile the templates down to straight PHP files, which in turn can be cached in XCode caches like APC. Would this still be possible with your binding or even the Twig Bridge?

Thanks for any clarification in advance. smile

Scott

younesrafie
  • Its called Design by Contract pattern, and can be achieved using interfaces. So I'm using the term Contract when I'm referring to the pattern.
  • The EventPusher is a contract, and the FanoutEventPusher is an implementation (The actual logic for this service).
  • Blade has a mapping for extensions and compilers, so you can attach a view compiler to an extension.
    • .blade.php => Blade view compiler.
    • .twig => Twig view compiler.
      In this article, I'm not trying to extend Blade, I'm trying to replace it! You can read through TwigBridge source code if you still unsure.
  • I didn't go through the source code of the 0.7 version, but just looking to the service provider you can see that it still extending it. I think changing the view system is a good use case to use contracts, but remember, when using TwigBridge you still have access to Blade.
  • I don't know about TwigBridge, but its possible this way, because we didn't change any Twig behavior.

I hope this clarifies your confusion smile Thanks

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Get the latest in PHP, once a week, for free.