Laravel 4 Tutorials - Medium

Where Is All The Content?

Christopher Pitt — Tue, 26 May 2015 05:11:43 GMT

You may have noticed a shortage of content here. From now on, the posts I write about Laravel will be over in https://medium.com/laravel-5-tutorials.

Happy learning!

Where Is All The Content? was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Forge + SSL

Christopher Pitt — Mon, 02 Jun 2014 10:56:36 GMT

Laravel Forge is awesome. It’s never been easier to ship Laravel applications, even with zero sysadmin knowledge. It’s even easy to set up SSL for your site. That is what we’re going to talk about, in this article.

Disclaimer

Forge is very dynamic. It’s new, and Taylor is adding features quicker than people can document. That makes this article subject to changes in Forge. Some of it may no longer be needed, by the time you encounter it. I will try to keep it updated though. Leave comments, or hit me up on Twitter, if you spot any changes.

Step 1: Provisioning Your Application

To get the ball rolling, you need to provision your application.

Get an account at https://forge.laravel.com
Add your server provider credentials, at https://forge.laravel.com/user/profile
Create a new server
Delete the default site
Create a new site

For https://rebuildinglaravel.com I used Digital Ocean and Github. It’s very important that you delete the default site (which is created on new servers). When you have a certificate, you’ll want to redirect non-SSL requests to the main SSL landing page. If you used the default site to host your application, the redirect will not work.

Step 2: Request An SSL Certificate

Getting SSL certificates requires generating what is called a Certificate Signing Request (CSR), and sending this to a certificate authority. The authority creates the corresponding SSL certificate, and that’s what you then install on the server.

Head over to the SSL Certificates tab, on the site edit page (something like https://forge.laravel.com/servers/[server id]/sites/[site id]) and create a Signing Request.

The values you enter should be specific to you. Authorities aren’t usually picky about this data, but use the best information you can.

Once the signing request is created, you can view it by clicking View CSR. The data between BEGIN CERTIFICATE REQUEST and END CERTIFICATE REQUEST is the signing request, but you will want to copy all the text (including the header and footer) for when you need to submit it to the authority.

Next, you will need to decide which authority to go with. I decided to apply for an open-source certificate, with https://www.globalsign.com. You can find application details at https://www.globalsign.com/ssl/ssl-open-source. They were kind enough to grant me a certificate, for https://rebuildinglaravel.com.

Once you know who you’re going with, you’ll need to follow their processes for submitting the CSR. They’ll take a few days to approve the certificate, and probably charge a small fee (unless they’re nice like Global Sign was).

Step 3: Installing the CSR

Once the certificate has been approved, you’ll get an email (or whatever method the authority uses), and the certificate will look similar to the CSR. Go back to where you created the CSR, and click Install Certificate.

When you’re ready to switch the application over to SSL, click Activate Certificate.

Step 4: Redirects

If you want to support https://example.com as well as https://www.example.com formats, you’ll need to add some redirects to the Nginx config files. If not, skip to the next step.

Currently, adding multiple domain names to a single site (in Forge) requires some manual configuration. When you provisioned the new server, you should have received an email; containing login details for the server.

Use these to log in:

$ ssh forge@123.123.123.123
 
The authenticity of host 'example.com (123.123.123.123)' can't be established.
RSA key fingerprint is a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'example.com,123.123.123.123' (RSA) to the list of known hosts.
 
forge@example.com's password:

Once you input the correct password, you should see something resembling:

Welcome to Ubuntu 14.04 LTS (GNU/Linux 3.13.0-24-generic x86_64)
 
 * Documentation: https://help.ubuntu.com/
 
 System information as of Mon Jun 2 12:19:05 SAST 2014
 
 System load: 0.0 Processes: 82
 Usage of /: 12.0% of 19.56GB Users logged in: 0
 Memory usage: 27% IP address for eth0: 123.123.123.123
 Swap usage: 0% IP address for eth1: 123.123.123.123
 
 Graph this data and manage this system at:
 https://landscape.canonical.com/
 
Last login: Mon Jun 2 09:52:25 2014 from 123.123.123.123

Obviously, all the IP addresses and domains names will be specific to your context. Please don’t ask me why your IP (123.123.123.123) isn’t working. I’ll throw a trout at you!

Thankfully Forge boxes already have an assortment of Linux utilities installed. Edit the configuration file (for your application), similarly to:

$ sudo vim /etc/nginx/sites-available/example.com

With the certificate installed (and activated), you should see something like:

server {
  listen 80;
  server_name example.com;
  return 301 https://example.com$request_uri;
}
 
server {
  listen 443 ssl;
  server_name example.com;
  root /home/forge/example.com/public;

Add the www version inline:

server {
  listen 80;
  server_name example.com www.example.com;
  return 301 https://example.com$request_uri;
}
 
server {
  listen 443 ssl;
  server_name example.com www.example.com;
  root /home/forge/example.com/public;

These changes tell the server to respond to both formats, and to redirect both formats from http to https.

Depending on the kind of certificate you got, you may also need to redirect from www URLs to URLs without. In that case, add the following:

server {
  listen 443 ssl;
  server_name example.com www.example.com;
  root /home/forge/example.com/public;
 
  if ($host = 'www.example.com') {
    rewrite ^/(.*)$ https://example.com/$1 permanent;
  }

Step 5: Back Up Keys

Certificates are generated according to a private key file. If you want to move the SSL certificate to another machine, and you don’t have the key file, you’re out of luck!

Just below the redirects we added, you should see a few lines resembling:

# FORGE SSL (DO NOT REMOVE!)
ssl on;
ssl_certificate /etc/nginx/ssl/example.com/123/server.crt;
ssl_certificate_key /etc/nginx/ssl/example.com/123/server.key;

A quick ls reveals three files in that folder:

The original CSR
The approved certificate
A private key (used to generate the CSR, and checked against the approved certificate).

Back these three files up somewhere, so you can get to them in an emergency. An easy way to do this (without much bash-foo), is:

$ cat /etc/nginx/ssl/example.com/123/*

This will output all three files, and you can copy/paste them to somewhere secure. Don’t go spreading these around.

Forge + SSL was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Migrations For The Conscientious

Christopher Pitt — Tue, 29 Apr 2014 10:23:43 GMT

I learned much from reading Taylor Otwell’s brief, yet insightful, Laravel: From Apprentice To Artisan. The parts dealing with domain-specific folders were echoes of a talk by Robert C. Martin, Architecture The Lost Years.

The idea is that your application’s folder structure shouldn’t be defined in terms of the delivery mechanism that is HTTP. It shouldn’t be defined in terms of the organisational model that is Model-View-Controller. It should be defined in terms of the application structure and behavior.

So I’ve recently been thinking a lot about this idea, and trying to structure code which fits with it. Naturally most of my Laravel application code is easily relocated and brought under the applicable namespaces. Migrations, however…

The problem with migrations is that their names are significant for their behavior, to the point where they won’t function if they aren’t named correctly. This is not uncommon in migration schemes owing to the need for chronological ordering. Migrations need to happen in the order they were created. They need to unhappen in the the opposite order.

Laravel makes this painfully clear when trying to namespace migration classes. Sure, you can change their filesystem location, and use the path argument (or the bench argument, or the package argument). These are designed to allow running migrations from anywhere. What they don’t cater for is when those migrations belong to a namespace (which is not the global namespace).

You can run composer dump-autoload and use as many path arguments as you like; if your migrations are in a namespace then Laravel will not migrate them.

It’s not all doom and gloom though. Because Laravel is built on a strong IoC foundation, it’s easy to subclass and substitute a migration handler class which deals with this natural (and annoying) weakness. Observe…

The first step is to subclass and substitute the Migrator class. You can find the base class at Illuminate\Database\Migrations\Migrator. It’s registered in Illuminate\Database\MigrationServiceProvider with the key migrator, so it’s easy to substitute in out custom code:

 
namespace Acme;
 
use Illuminate\Database\Migrations\Migrator as Base;
 
class Migrator
  extends Base
{
  /**
   * Resolve a migration instance from a file.
   *
   * @param string $file
   * @return object
   */
  public function resolve($file)
  {
    $file = implode("_", array_slice(explode("_", $file), 4));
  
    $class = "Acme\\Migration\\" . studly_case($file);
  
    return new $class;
  }
}

The resolve() method is almost exactly the same as in the base Migrator class, except that we’re now able to prefix the resolved class name with a namespace. Now we just have to swap this for the base Migrator:

 
namespace Acme;
 
use Illuminate\Support\ServiceProvider;
 
class AcmeServiceProvider
  extends ServiceProvider
{
  public function register()
  {
    $this->app->bindShared(
      "migrator",
      function () {
        return new Migrator(
          $this->app->make("migration.repository"),
          $this->app->make("db"),
          $this->app->make("files")
        );
      }
    );
  }
}

This is exactly the same bindShared() call that happened in the base service provider. I’ve just cleaned it up a little…

We will still have to use the path argument, as Laravel expects the migration classes to be in app/database/migrations. We will still need to have the timestamps in the migration file names, as Laravel needs them to work out the running order.

Instead of seeing class not found exceptions, it’s business as usual:

❯ php artisan migrate --path="app/Acme/Migration"

If you need more info on running package migrations (the traditional approach), you can find it at: http://laravel.com/docs/packages#package-migrations.

If you need more info on how to write migrations, you can find it at: http://laravel.com/docs/migrations.

Migrations For The Conscientious was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Laravel’s URL::to() vs URL::asset()

Simon Wicki — Mon, 28 Apr 2014 11:29:35 GMT

Should I bother using asset() over to()?

Short answer: No, not really.

You want to have the following code:

Now you can achieve this using blade syntax:

// using URL::to()


// using URL::asset()

URL::to()

The method is implemented like this

URL::asset()

The method is implemented like this

Difference

Both methods get the job done.

URL::to() additionally encodes the segments of the passed url with rawurlencode
URL::asset() removes index.php from the path (which shouldn’t be in first place)

So you get more utility by using URL::to(), but also takes longer to execute (approx. 25% more than URL::asset()). But it’s strongly neglectible, since calling 100 times URL::to() takes 0.003523 ms.

Alternatives

If you’re using blade, you can use the following to easily output style and script tags.

{{ HTML::script('js/bootstrap.js') }}
{{ HTML::style('css/bootstrap.min.css') }}

Or using any of Asset Management packages like orchestra/asset.

Simon Wicki is a Frontend Developer in Berlin. Passionate and fluent in Vue, Angular, React and Ionic. I love Hybrid Apps and books.

👉 Join me on Twitter to follow my latest updates.

Laravel 4 Controller Testing

Christopher Pitt — Sat, 12 Apr 2014 19:04:13 GMT

A Comprehensive Tutorial

Testing is a hot topic these days. Everyone knows that having tests is a good thing, but often they’re either “too busy” to write them, or they just don’t know how.

Even if you do write tests, it may not always be clear what the best way is to prepare for them. Perhaps you’re used to writing them against a particular framework (which I’m assuming is not Laravel 4) or you tend to write fewer when you can’t figure out how exactly to test a particular section of your application.

I have recently spent much time writing tests, and learning spades about how to write them. I have Jeffrey Way to thank, both for Laravel: Testing Decoded and Laracasts.com. These resources have taught me just about everything I know about unit/functional testing.

This article is about some of the practical things you can do to make your code easier to test, and how you would go about writing functional/unit tests against that code. If you take nothing else away, after reading this, you should be subscribed to Laracasts.com and you should read Laravel: Testing Decoded.

Since there’s already so much in the way of testing, I thought it would be better just to focus on the subject of how to write testable controllers, and then how to test that they are doing what they are supposed to be doing.

This tutorial is also different from my others because it doesn’t build a single project, but rather demonstrates general principles which can be used for them all.

While much effort has been spent in the pursuit of accuracy; there’s a good chance you could stumble across a curly quote in a code listing, or some other egregious errata. Please make a note and I will fix where needed.

I have also uploaded this code to Github. You need simply follow the configuration instructions in this tutorial, after downloading the source code, and the application should run fine.

This assumes, of course, that you know how to do that sort of thing. If not; this shouldn’t be the first place you learn about making PHP applications.

https://github.com/formativ/tutorial-laravel-4-testing

If you spot differences between this tutorial and that source code, please raise it here or as a GitHub issue. Your help is greatly appreciated.

Installing Dependencies

For this chapter, we’re going to be using PHPUnit and Mockery. Both of these libraries are used in testing, and can be installed at the same time, by running the following commands:

❯ composer require —dev "phpunit/phpunit:4.0.*"

./composer.json has been updated
Loading composer repositories with package information
...

❯ composer require —dev "mockery/mockery:0.9.*"

./composer.json has been updated
Loading composer repositories with package information
...

We’ll get into the specifics of each later, but this should at least install them and add them to the require-dev section of your composer.json file.

Unit vs. Functional vs. Acceptance

There are many kinds of tests. There are three which we are going to look at:

Unit
Functional
Acceptance

Unit Tests

Unit tests are tests which cover individual functions or methods. They are meant to run the functions or methods in complete isolation, with no dependencies or side-effects.

You can find a boring description at: http://en.wikipedia.org/wiki/Unit_testing.

Functional Tests

Functional tests are tests which concentrate on the input given to some function or method, and the output returned. They don’t care about isolation or state.

You can find a boring description at: http://en.wikipedia.org/wiki/Functional_testing.

Acceptance Tests

Acceptance tests are test which look at a much broader range of functionality. These are often called end-to-end tests because they are concerned with the correct functionality over a range of functions, methods classes etc.

You can find a boring description at: http://en.wikipedia.org/wiki/Acceptance_testing.

Am I Writing Unit Or Functional Tests?

When it comes to writing tests in Laravel 4, developers often think they are writing unit tests when they are actually writing functional tests. The difference is small but significant.

Laravel provides a set of test classes (a TestCase class, and an ExampleTest class). If you base your tests off of these, you are probably writing functional tests. The TestCase class actually initialises the Laravel 4 framework. If your code depends on that being the case (accessing the aliases, service providers etc.) then your tests aren’t isolated. They have dependencies and they need to be run in order.

When your tests only require the underlying PHPUnit or PHPSpec classes, then you may be writing unit tests.

How does this affect us? Well — if your goal is to write functional tests, and you have decent test coverage then you’re doing ok. But if you want to write true unit tests, then you need to pay attention to how your code is constructed. If you’re using the handy aliases, which Laravel provides, then writing unit tests may be tough.

That should be enough theory to get us started. Let’s take a look at some code…

Fat Controllers

It’s not uncommon to find controllers with actions resembling the following:

public function store()
{
  $validator = Validator::make(Input::all(), [
    "title"    => "required|max:50",
    "subtitle" => "required|max:100",
    "body"     => "required",
    "author"   => "required|exists:authors"
  ]);
  
  if ($validator->passes()) {
    Posts::create([
      "title"     => Input::get("title"),
      "subtitle"  => Input::get("subtitle"),
      "body"      => Input::get("body"),
      "author_id" => Input::get("author"),
      "slug"      => Str::slug(Input::get("title"))
    ]);
  
    Mail::send("emails.post", Input::all(), function($email) {
      $email
        ->to("cgpitt@gmail.com", "Chris")
        ->subject("New post");
    });
  
    return Redirect::route("posts.index");
  }
  
  return Redirect::back()
    ->withErrors($validator)
    ->withInput();
}

This was extracted from app/controllers/PostController.php. I generated the file with the controller:make command.

This is how we first learn to use MVC frameworks, but there comes a point where we are familiar with how they work, and need to start writing tests. Testing this action would be a nightmare. Fortunately, there are a few improvements we can make.

Service Providers

We’ve used service providers to organise and package our code. Now we’re going to use them to help us thin our controllers out. Create a new service provider, resembling the following:

 
namespace Formativ;
 
use Illuminate\Support\ServiceProvider;
 
class PostServiceProvider
extends ServiceProvider
{
  protected $defer = true;
  
  public function register()
  {
    $this->app->bind(
      "Formativ\\PostRepositoryInterface",
      "Formativ\\PostRepository"
    );
  
    $this->app->bind(
      "Formativ\\PostValidatorInterface",
      "Formativ\\PostValidator"
    );
  
    $this->app->bind(
      "Formativ\\PostMailerInterface",
      "Formativ\\PostMailer"
    );
  }
  
  public function provides()
  {
    return [
      "Formativ\\PostRepositoryInterface",
      "Formativ\\ValidatorInterface",
      "Formativ\\MailerInterface"
    ];
  }
}

This file should be saved as app/Formativ/PostServiceProvider.php.

You will also need to load the Formativ namespace through the composer.json file. You can do that by using either PSR specification, or even through a classmap. More info on that at: https://getcomposer.org/doc/01-basic-usage.md#autoloading.

You can find out more about making service providers at: http://laravel.com/docs/packages.

This does a couple of important things:

Interfaces are connected to concrete implementations, so that we can type-hint the interfaces in our controller, and they will be resolved automatically, with the Laravel IoC container.
We specify which interfaces are provided (in the provides() method) so that we can defer the loading of this service provider until the concrete implementations are called.

We need to define the interfaces and concrete implementations:

 
namespace Formativ;
 
interface PostRepositoryInterface
{
  public function all(array $modifiers);
  public function first(array $modifiers);
  public function insert(array $data);
  public function update(array $data, array $modifiers);
  public function delete(array $modifiers);
}

This file should be saved as app/Formativ/PostRepositoryInterface.php.

 
namespace Formativ;
 
class PostRepository implements PostRepositoryInterface
{
  public function all(array $modifiers)
  {
    // return all the posts filtered by $modifiers...
  }
  
  public function first(array $modifiers)
  {
    // return the first post filtered by $modifiers...
  }
  
  public function insert(array $data)
  {
    // insert posts with $data...
  }
  
  public function update(array $data, array $modifiers)
  {
    // update posts filtered by $modifiers, with $data...
  }
  
  public function delete(array $modifiers)
  {
    // delete posts filtered by $modifiers...
  }
}

This file should be saved as app/Formativ/PostRepository.php.

 
namespace Formativ;
 
interface PostValidatorInterface
{
  public function passes($event);
  public function messages($event);
  public function on($event);
}

This file should be saved as app/Formativ/PostValidatorInterface.php.

 
namespace Formativ;
 
class PostValidator implements PostValidatorInterface
{
  public function passes($event)
  {
    // validate the event instance...
  }
  
  public function messages($event)
  {
    // fetch the error messages for the event instance...
  }
  
  public function on($event)
  {
    // set up the event instance and return it for chaining...
  }
}

This file should be saved as app/Formativ/PostValidator.php.

 
namespace Formativ;
 
interface PostMailerInterface
{
  public function send($to, $view, $data);
}

This file should be saved as app/Formativ/PostMailerInterface.php.

 
namespace Formativ;
 
class PostMailer implements PostMailerInterface
{
  public function send($to, $view, $data)
  {
    // send an email about the post...
  }
}

This file should be saved as app/Formativ/PostMailer.php.

Dependency Injection

With all of these interfaces and concrete implementations in place, we can simply type-hint the interfaces in our controller. This is essentially dependency injection. We don’t create or use dependencies in our controller — rather they are passed in when the controller is instantiated.

The dependencies are resolved automatically, via the IoC container and reflection.

This makes the controller thinner, and helps us break the logic up into a number of smaller, easier-to-test classes:

 
use Formativ\PostRepositoryInterface;
use Formativ\PostValidatorInterface;
use Formativ\PostMailerInterface;
use Illuminate\Support\Facades\Response;
 
class PostController
extends BaseController
{
  public function __construct(
    PostRepositoryInterface $repository,
    PostValidatorInterface $validator,
    PostMailerInterface $mailer,
    Response $response
  )
  {
    $this->repository = $repository;
    $this->validator  = $validator;
    $this->mailer     = $mailer;
    $this->response   = $response;
  }
  
  public function store()
  {
    if ($this->validator->passes("store"))) {
      $this->repository->insert([
        "title"     => Input::get("title"),
        "subtitle"  => Input::get("subtitle"),
        "body"      => Input::get("body"),
        "author_id" => Input::get("author"),
        "slug"      => Str::slug(Input::get("title"))
      ]);
       
      $this->mailer->send("cgpitt@gmail.com", "emails.post");
    
      return $this->response
        ->route("posts.index")
        ->with("success", true);
    }
  
    return $this->response
      ->back()
      ->withErrors($this->validator->messages("store"))
      ->withInput();
 }

This was extracted from app/controllers/PostController.php.

Another thing you can do, to further modularise your logic, is to dispatch events at critical points in execution:

 
use Formativ\PostRepositoryInterface;
use Formativ\PostValidatorInterface;
use Formativ\PostMailerInterface;
use Illuminate\Support\Facades\Response;
use Illuminate\Events\Dispatcher;
 
class PostController
extends BaseController
{
  public function __construct(
    PostRepositoryInterface $repository,
    PostValidatorInterface $validator,
    PostMailerInterface $mailer,
    Response $response,
    Dispatcher $dispatcher
  )
  {
    $this->repository = $repository;
    $this->validator  = $validator;
    $this->mailer     = $mailer;
    $this->response   = $response;
    $this->dispatcher = $dispatcher;
   
    $this->dispatcher->listen(
      "post.store",
      [$this->repository, "insert"]
    );
     
    $this->dispatcher->listen(
      "post.store",
      [$this->mailer, "send"]
    );
  }
  
  public function store()
  {
    if ($this->validator->passes("store")) {
      $this->dispatcher->fire("post.store");
    
      return $this->response
        ->route("posts.index")
        ->with("success", true);
    }
    
    return $this->response
      ->back()
      ->withErrors($this->validator->messages("store"))
      ->withInput();
  }

This was extracted from app/controllers/PostController.php.

 
namespace Formativ;
 
use Illuminate\Http\Request;
use Str;
 
class PostRepository implements PostRepositoryInterface
{
  public function __construct(Request $request)
  {
    $this->request = $request;
  }
  
  public function insert()
  {
    $data = [
      "title"     => $this->request->get("title"),
      "subtitle"  => $this->request->get("subtitle"),
      "body"      => $this->request->get("body"),
      "author_id" => $this->request->get("author"),
      "slug"      => Str::slug($this->request->get("title"))
    ];
  
    // insert posts with $data...
  }

This was extracted from app/Formativ/PostRepository.php.

Using this approach, you can delegate method calls based on events, rather than explicit method calls and variable manipulation.

There are loads of different ways to use events, so you should definitely check out the official docs at: http://laravel.com/docs/events.

This Isn’t Testing!

If you’re wondering how this is related to testing, consider how you would have tested the original controller code. There are many different responsibilities, and places for errors to emerge.

Splitting off your logic into classes of single responsibility is a good thing. Generally following SOLID principles is a good thing. The smaller your classes are, the fewer things each of them do, the easier they are to test.

So how would we write tests for these new classes? Let’s begin with one of the concrete implementations:

 
namespace Formativ;
 
class PostMailerTest
extends TestCase
{
  public function testSend()
  {
    // ...your test here
  }
}

This file should be saved as app/tests/Formativ/PostMailerTest.php.

In order for this first test case to run, we’ll need to set up a phpunit config file:


 backupStaticAttributes="false"
 bootstrap="bootstrap/autoload.php"
 colors="true"
 convertErrorsToExceptions="true"
 convertNoticesToExceptions="true"
 convertWarningsToExceptions="true"
 processIsolation="false"
 stopOnFailure="false"
 syntaxCheck="false"
>
  
    
      ./app/tests

This file should be saved as phpunit.xml.

This will get the tests running, and serves as a template in which to start writing our tests. You can actually see this test case working, by running the following command:

❯ phpunit
 
PHPUnit 4.0.14 by Sebastian Bergmann.
 
Configuration read from /path/to/phpunit.xml
 
.
 
Time: 76 ms, Memory: 8.75Mb
 
OK (1 test, 0 assertions)

This test is functional because it only happens after a Laravel instance is spun up, and it doesn’t care about what state it leaves this application instance in.

Since we haven’t implemented the body of the send() method, it’s difficult for us to know what the return value will be. What we can test for is what methods (on the mailer’s underlying mail transport/interface) are being called…

Imagine we’re using the underlying Laravel mail class to send the emails. We used it before we started optimising the controller layer:

Mail::send("emails.post", Input::all(), function($email) {
  $email
    ->to("cgpitt@gmail.com", "Chris")
    ->subject("New post");
});

You can find out more about the Mailer class at: http://laravel.com/docs/mail.

We’d essentially like to use this logic inside the PostMailer class. We should also dependency-inject our Mail provider:

 
namespace Formativ;
 
use Illuminate\Mail\Mailer;
 
class PostMailer implements PostMailerInterface
{
  public function __construct(Mailer $mailer)
  {
    $this->mailer = $mailer;
  }
  
  public function send($to, $view, $data)
  {
    $this->mailer->send(
      $view, $data,
      function($email) use ($to) {
        $email->to($to);
      }
    );
  }
}

This file should be saved as app/Formativ/PostMailer.php.

Now we call the send() method on an injected mailer instance, instead of directly on the facade. This is still a little tricky to test (thanks to the callback), but thankfully much easier than if it was still using the facade (and in the controller):

 
namespace Formativ;
 
use Mockery;
use TestCase;
 
class PostMailerTest
extends TestCase
{
  public function tearDown()
  {
    Mockery::close();
  }
  
  public function testSend()
  {
    $mailerMock = $this->getMailerMock();
  
    $mailerMock
      ->shouldReceive("send")
      ->atLeast()->once()
      ->with(
        "bar", ["baz"],
        $this->getSendCallbackMock()
      );
  
    $postMailer = new PostMailer($mailerMock);
    $postMailer->send("foo", "bar", ["baz"]);
  }
  
  protected function getSendCallbackMock()
  {
    return Mockery::on(function($callback) {
      $emailMock = Mockery::mock("stdClass");
  
      $emailMock
        ->shouldReceive("to")
        ->atLeast()->once()
        ->with("foo");
  
      $callback($emailMock);
  
      return true;
    });
  }
  
  protected function getMailerMock()
  {
    return Mockery::mock("Illuminate\Mail\Mailer");
  }
}

This file should be saved as app/tests/Formativ/PostMailerTest.php.

Phew! Let’s break that up so it’s easier to digest…

Mockery::mock("Illuminate\Mail\Mailer");

Part of trying to test in the most isolated manner is substituting dependencies with things that don’t perform any significant function. We do this by creating a new mock instance, via the Mockery::mock() method.

We use this again with:

$emailMock = Mockery::mock("stdClass");

We can use stdClass the second time around because the provided class isn’t type-hinted. Our PostMailer class type-hints the Illuminate\Mail\Mailer class.

We then tell the test to expect that certain methods are called using certain arguments:

$emailMock
  ->shouldReceive("to")
  ->atLeast()
  ->once()
  ->with("foo");

This tells the mock to expect a call to an as-yet undefined to() method, and to expect that it will be passed “foo” as the first (and single) argument. If your production code expects a stubbed method to return a specific kind of data, you can add the andReturn() method.

We can provide expected callbacks, though it’s slightly trickier:

Mockery::on(function($callback) {
  $emailMock = Mockery::mock("stdClass");
  
  $emailMock
    ->shouldReceive("to")
    ->atLeast()
    ->once()
    ->with("foo");
  
  $callback($emailMock);
  
  return true;
});

We set up a mock, which expects calls to it’s own methods, and then the original callback is run with the provided mock. Don’t forget to add return true — that tells mockery that it’s ok to run the callback with the mock you’ve set up.

At the end of all of this; we’re just testing that methods were called in the correct way. The test doesn’t worry about making sure the Laravel Mailer class actually sends the mail correctly — that has it’s own tests.

The repository class is slightly simpler to test:

 
namespace Formativ;
 
use Mockery;
use TestCase;
 
class PostRepositoryTest
extends TestCase
{
  public function tearDown()
  {
    Mockery::close();
  }
  
  public function testSend()
  {
    $requestMock = $this->getRequestMock();
  
    $requestMock
      ->shouldReceive("get")
      ->atLeast()
      ->once()
      ->with("title");
  
    $requestMock
      ->shouldReceive("get")
      ->atLeast()
      ->once()
      ->with("subtitle");
  
    $requestMock
      ->shouldReceive("get")
      ->atLeast()
      ->once()
      ->with("body");
  
    $requestMock
      ->shouldReceive("get")
      ->atLeast()
      ->once()
      ->with("author");
  
    $postRepository = new PostRepository($requestMock);
    $postRepository->insert();
  }
  
  protected function getRequestMock()
  {
    return Mockery::mock("Illuminate\Http\Request");
  }
}

This file should be saved as app/tests/Formativ/PostRepositoryTest.php.

All we’re doing here is making sure the get method is called four times, on the request dependency. We could extend this to accommodate requests against the underlying database connector object, and the test code would be similar.

We can’t completely test the Str::slug() method because it’s not a facade but rather a static method on the Str class. Every facade allows you to mock methods (facades subclass the MockObject class), and you can even swap them out with your own mocks (using the Validator::swap($validatorMock) method).

You can test static method calls using the AspectMock library, which you can learn more about at: https://github.com/Codeception/AspectMock.

You can learn more about facades at: http://laravel.com/docs/facades.

Finally, let’s test the controller:

 
class PostControllerTest
extends TestCase
{
  public function tearDown()
  {
    Mockery::close();
  }
 
  public function testConstructor()
  {
    $repositoryMock = $this->getRepositoryMock();
  
    $mailerMock = $this->getMailerMock();
  
    $dispatcherMock = $this->getDispatcherMock();
  
    $dispatcherMock
      ->shouldReceive("listen")
      ->atLeast()
      ->once()
      ->with(
        "post.store",
        [$repositoryMock, "insert"]
      );
  
    $dispatcherMock
      ->shouldReceive("listen")
      ->atLeast()
      ->once()
      ->with(
        "post.store",
        [$mailerMock, "send"]
      );
  
    $postController = new PostController(
      $repositoryMock,
      $this->getValidatorMock(),
      $mailerMock,
      $this->getResponseMock(),
      $dispatcherMock
    );
  }
 
  public function testStore()
  {
    $validatorMock = $this->getValidatorMock();
     
    $validatorMock
      ->shouldReceive("passes")
      ->atLeast()
      ->once()
      ->with("store")
      ->andReturn(true);
       
    $responseMock = $this->getResponseMock();
     
    $responseMock
      ->shouldReceive("route")
      ->atLeast()
      ->once()
      ->with("posts.index")
      ->andReturn($responseMock);
      
    $responseMock
      ->shouldReceive("with")
      ->atLeast()
      ->once()
      ->with("success", true);
     
    $dispatcherMock = $this->getDispatcherMock();
    
    $dispatcherMock
      ->shouldReceive("fire")
      ->atLeast()
      ->once()
      ->with("post.store");
    
    $postController = new PostController(
      $this->getRepositoryMock(),
      $validatorMock,
      $this->getMailerMock(),
      $responseMock,
      $dispatcherMock
    );
   
    $postController->store();
  }
  
  public function testStoreFails()
  {
    $validatorMock = $this->getValidatorMock();
  
    $validatorMock
      ->shouldReceive("passes")
      ->atLeast()
      ->once()
      ->with("store")
      ->andReturn(false);
  
    $validatorMock
      ->shouldReceive("messages")
      ->atLeast()
      ->once()
      ->with("store")
      ->andReturn(["foo"]);
  
    $responseMock = $this->getResponseMock();
  
    $responseMock
      ->shouldReceive("back")
      ->atLeast()
      ->once()
      ->andReturn($responseMock);
  
    $responseMock
      ->shouldReceive("withErrors")
      ->atLeast()
      ->once()
      ->with(["foo"])
      ->andReturn($responseMock);
  
    $responseMock
      ->shouldReceive("withInput")
      ->atLeast()
      ->once()
      ->andReturn($responseMock);
  
    $postController = new PostController(
      $this->getRepositoryMock(),
      $validatorMock,
      $this->getMailerMock(),
      $responseMock,
      $this->getDispatcherMock()
    );
  
    $postController->store();
  }
 
  protected function getRepositoryMock()
  {
    return Mockery::mock("Formativ\PostRepositoryInterface")
      ->makePartial();
  }
  
  protected function getValidatorMock()
  {
    return Mockery::mock("Formativ\PostValidatorInterface")
      ->makePartial();
  }
  
  protected function getMailerMock()
  {
    return Mockery::mock("Formativ\PostMailerInterface")
      ->makePartial();
  }
  
  protected function getResponseMock()
  {
    return Mockery::mock("Illuminate\Support\Facades\Response")
      ->makePartial();
  }
  
  protected function getDispatcherMock()
  {
    return Mockery::mock("Illuminate\Events\Dispatcher")
      ->makePartial();
  }
}

This file should be saved as app/tests/controllers/PostControllerTest.php.

Here we’re still testing method calls, but we also test multiple paths through the store() method.

We haven’t used any assertions, even though they are very useful for unit and functional testing. Feel free to use them to check output values…

You can find out more about Mockery at: https://github.com/padraic/mockery.

You can find out more about PHPUnit at: http://phpunit.de.

The Rabbit Hole

The process of test-writing can take as much time as you want to give it. It’s best just to decide exactly what you need to test, and step away after that.

We’ve just looked at a very narrow area of testing, in our applications. You’re likely to have a richer data layer, and need a ton of tests for that. You’re probably going to want to test the rendering of views.

Don’t think this is an exhaustive reference for how to test, or even that this is the only way to functionally test your controller code. It’s simply a method I’ve found works for the applications I write.

Alternatives

The closest alternative to testing with PHPUnit is probably PHPSpec (http://www.phpspec.net). It uses a similar dialect of assertions and mocking.

If you’re looking to test, in a broader sense, consider looking into Behat (http://behat.org). It uses a descriptive, text-based language to define what behaviour a service/library should have.

Conclusion

If you enjoyed this tutorial; it would be helpful if you could click the Recommend button.

This tutorial comes from a book I’m writing. If you like it and want to support future tutorials; please consider buying it. Half of all sales go to Laravel.

Laravel 4 Controller Testing was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Laravel 4 File-Based CMS

Christopher Pitt — Sun, 02 Feb 2014 16:58:41 GMT

A Comprehensive Tutorial

OctoberCMS is a Laravel-based, pre-built CMS which was recently announced. I have yet to see the code powering what looks like a beautiful and efficient CMS system. So I thought I would try to implement some of the concepts presented in the introductory video as they illustrate valuable tips for working with Laravel.

While much effort has been spent in the pursuit of accuracy; there’s a good chance you could stumble across a curly quote in a code listing, or some other egregious errata. Please make a note and I will fix where needed.

I have also uploaded this code to Github. You need simply follow the configuration instructions in this tutorial, after downloading the source code, and the application should run fine.

This assumes, of course, that you know how to do that sort of thing. If not; this shouldn’t be the first place you learn about making PHP applications.

https://github.com/formativ/tutorial-laravel-4-file-based-cms

If you spot differences between this tutorial and that source code, please raise it here or as a GitHub issue. Your help is greatly appreciated.

Installing Dependencies

We’re developing a Laravel 4 application which has lots of server-side aspects; but there’s also an interactive interface. There be scripts!

For this; we’re using Bootstrap and jQuery. Download Bootstrap at: http://getbootstrap.com/ and unpack it into your public folder. Where you put the individual files makes little difference, but I have put the scripts in public/js, the stylesheets in public/css and the fonts in public/fonts. Where you see those paths in my source code; you should substitute them with your own.

Next up, download jQuery at: http://jquery.com/download/ and unpack it into your public folder.

On the server-side, we’re going to be using Flysystem for reading and writing files. Add it to the Composer dependencies:

"require" : {
  "laravel/framework" : "4.1.*",
  "league/flysystem"  : "0.2.*"
},

This was extracted from composer.json.

Follow that up with:

composer update

Rendering Templates

We’ve often used View::make() to render views. It’s great for when we have pre-defined view files and we want Laravel to manage how they are rendered and stored. In this tutorial, we’re going to be rendering templates from strings. We’ll need to encapsulate some of how Laravel rendered templates, but it’ll also give us a good base for extending upon the Blade template syntax.

Let’s get started by creating a service provider:

php artisan workbench formativ/cms

This will generate the usual scaffolding for a new package. We need to add it in a few places, to be able to use it in our application:

"providers" => [
  "Formativ\Cms\CmsServiceProvider",
  // …remaining service providers
],

This was extracted from app/config/app.php.

"autoload": {
  "classmap": [
    // …
  ],
  "psr-0": {
    "Formativ\\Cms": "workbench/formativ/cms/src/"
  }
}

This was extracted from composer.json.

Then we need to rebuild the composer autoloader:

composer dump-autoload

All this gets us to a place where we can start to add classes for encapsulating and extending Blade rendering. Let’s create some wrapper classes, and register them in the service provider:

 
namespace Formativ\Cms;
 
interface CompilerInterface
{
  public function compileString($template);
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/CompilerInterface.php.

 
namespace Formativ\Cms\Compiler;
 
use Formativ\Cms\CompilerInterface;
use Illuminate\View\Compilers\BladeCompiler;
 
class Blade
extends BladeCompiler
implements CompilerInterface
{
 
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/Compiler/Blade.php.

 
namespace Formativ\Cms;
 
interface EngineInterface
{
  public function render($template, $data);
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/EngineInterface.php.

 
namespace Formativ\Cms\Engine;
 
use Formativ\Cms\CompilerInterface;
use Formativ\Cms\EngineInterface;
 
class Blade
implements EngineInterface
{
  protected $compiler;
  
  public function __construct(CompilerInterface $compiler)
  {
    $this->compiler = $compiler;
  }
  
  public function render($template, $data)
  {
    $compiled = $this->compiler->compileString($template);
  
    ob_start();
    extract($data, EXTR_SKIP);
  
    try
    {
      eval("?>" . $compiled);
    }
    catch (Exception $e)
    {
      ob_end_clean();
      throw $e;
    }
  
    $result = ob_get_contents();
    ob_end_clean();
  
    return $result;
  }
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/Engine/Blade.php.

 
namespace Formativ\Cms;
 
use Illuminate\Support\ServiceProvider;
 
class CmsServiceProvider
extends ServiceProvider
{
  protected $defer = true;
  
  public function register()
  {
    $this->app->bind(
      "Formativ\Cms\CompilerInterface",
      function() {
        return new Compiler\Blade(
          $this->app->make("files"),
          $this->app->make("path.storage") . "/views"
        );
      }
    );
    
    $this->app->bind(
      "Formativ\Cms\EngineInterface",
      "Formativ\Cms\Engine\Blade"
    );
  }
  
  public function provides()
  {
    return [
      "Formativ\Cms\CompilerInterface",
      "Formativ\Cms\EngineInterface"
    ];
  }
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/CmsServiceProvider.php.

The Compiler\Blade class encapsulates the BladeCompiler class, allowing us to implement the CompilerInterface interface. This is a way of future-proofing our package so that the code which depends on methods Blade currently implements won’t fail if future versions of Blade were to remove that implementation.

We can also add additional template tags in via this class, so it’s not too much code bloat.

The Engine\Blade class contains the method which we will use to render template strings. It implements the EngineInterface interface for that same future-proofing.

We register all of these in the CmsServiceProvider. We can now inject these dependencies in our controller:

 
use Formativ\Cms\EngineInterface;
 
class IndexController
extends BaseController
{
  protected $engine;
  
  public function __construct(EngineInterface $engine)
  {
    $this->engine = $engine;
  }
  
  public function indexAction()
  {
    // ...use $this->engine->render() here
  }
}

This file should be saved as app/controllers/IndexController.php.

As we bound Formativ\Cms\EngineInterface in our service provider, we can now specify it in our controller constructor and Laravel will automatically inject it for us.

Gathering Metadata

One of the interesting things OctoberCMS does is store all of the page and layout meta data at the top of the template file. This allows changes to metadata (which would normally take place elsewhere) to be version-controlled. Having gained the ability to render template strings, we’re now in a position to be able to isolate this kind of metadata and render the rest of the file as a template.

Consider the following example:

protected function minify($html)
{
  $search = [
    "/\>[^\S ]+/s",
    "/[^\S ]+\    "/(\s)+/s"
  ];
  
  $replace = [
    ">",
    "<",
    "\\1"
  ];
  
  $html = preg_replace($search, $replace, $html);
  
  return $html;
}
  
public function indexAction()
{
  $template = $this->minify("
    
    
      
        <br>          Laravel 4 File-Based CMS<br>        
      
      
        Hello world
      
    
  ");
  
  return $this->engine->render($template, []);
}

This was extracted from app/controllers/IndexController.php.

Here we’re rendering a page template (with the help of a minify method). It’s just like what we did before. Let’s add some metadata, and pull it out of the template before rendering:

protected function extractMeta($html)
{
  $parts = explode("==", $html, 2);
  
  $meta = "";
  $html = $parts[0];
  
  if (count($parts) > 1)
  {
    $meta = $parts[0];
    $html = $parts[1];
  }
  
  return [
    "meta" => $meta,
    "html" => $html
  ];
}
 
protected function parseMeta($meta)
{
  $meta  = trim($meta);
  $lines = explode("\n", $meta);
  $data  = [];
  
  foreach ($lines as $line)
  {
    $parts = explode("=", $line);
    $data[trim($parts[0])] = trim($parts[1]);
  }
  
  return $data;
}
 
public function indexAction()
{
  $parts = $this->extractMeta("
    title   = Laravel 4 File-Based CMS
    message = Hello world
    ==
    
    
      
        <br>          {{ \$title }}<br>        
      
      
        {{ \$message }}
      
    
  ");
 
  $data     = $this->parseMeta($parts["meta"]);
  $template = $this->minify($parts["html"]);
 
  return $this->engine->render($template, $data);
}

This was extracted from app/controllers/IndexController.php.

This time round, we’re using an extractMeta() method to pull the meta data string out of the template string, and a parseMeta() method to split the lines of metadata into key/value pairs.

The result is a functional means of storing and parsing meta data, and rendering the remaining template from and to a string.

The minify method is largely unmodified from the original, which I found at: http://stackoverflow.com/questions/6225351/how-to-minify-php-page-html-output.

Creating Layouts

We need to create some sort of admin interface, with which to create and/or modify pages and layouts. Let’s skip the authentication system (as we’ve done that before and it will distract from the focus of this tutorial).

I’ve chosen for us to use Flysystem when working with the filesystem. It would be a good idea to future-proof this dependency by wrapping it in a subclass which implements an interface we control.

 
namespace Formativ\Cms;
 
interface FilesystemInterface
{
  public function has($file);
  public function listContents($folder, $detail = false);
  public function write($file, $contents);
  public function read($file);
  public function put($file, $content);
  public function delete($file);
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/FilesystemInterface.php.

 
namespace Formativ\Cms;
 
use League\Flysystem\Filesystem as Base;
 
class Filesystem
extends Base
implements FilesystemInterface
{
 
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/Filesystem.php.

public function register()
{
  $this->app->bind(
    "Formativ\Cms\CompilerInterface",
    function() {
      return new Compiler\Blade(
        $this->app->make("files"),
        $this->app->make("path.storage") . "/views"
      );
    }
  );
  
  $this->app->bind(
    "Formativ\Cms\EngineInterface",
    "Formativ\Cms\Engine\Blade"
  );
  
  $this->app->bind(
    "Formativ\Cms\FilesystemInterface",
    function() {
      return new Filesystem(
        new Local(
          $this->app->make("path.base") . "/app/views"
        )
      );
    }
  );
}

This was extracted from workbench/formativ/cms/src/Formativ/
Cms/CmsServiceProvider.php.

We’re not really adding any extra functionality to that which Flysystem provides. The sole purpose of us wrapping the Local Flysystem adapter is to make provision for swapping it with another filesystem class/library.

We should also move the metadata-related functionality into a better location.

 
namespace Formativ\Cms;
 
interface EngineInterface
{
  public function render($template, $data);
  public function extractMeta($template);
  public function parseMeta($meta);
  public function minify($template);
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/EngineInterface.php.

 
namespace Formativ\Cms\Engine;
 
use Formativ\Cms\CompilerInterface;
use Formativ\Cms\EngineInterface;
 
class Blade
implements EngineInterface
{
  protected $compiler;
  
  public function __construct(CompilerInterface $compiler)
  {
    $this->compiler = $compiler;
  }
  
  public function render($template, $data)
  {
    $extracted = $this->extractMeta($template)["template"];
    $compiled = $this->compiler->compileString($extracted);
  
    ob_start();
    extract($data, EXTR_SKIP);
  
    try
    {
      eval("?>" . $compiled);
    }
    catch (Exception $e)
    {
      ob_end_clean();
      throw $e;
    }
  
    $result = ob_get_contents();
    ob_end_clean();
  
    return $result;
  }
  
  public function minify($template)
  {
    $search = [
      "/\>[^\S ]+/s", 
      "/[^\S ]+\      "/(\s)+/s"
    ];
  
    $replace = [
      ">",
      "<",
      "\\1"
    ];
  
    $template = preg_replace($search, $replace, $template);
  
    return $template;
  }
  
  public function extractMeta($template)
  {
    $parts = explode("==", $template, 2);
  
    $meta     = "";
    $template = $parts[0];
  
    if (count($parts) > 1)
    {
      $meta     = $parts[0];
      $template = $parts[1];
    }
  
    return [
      "meta"     => $meta,
      "template" => $template
    ];
  }
  
  public function parseMeta($meta)
  {
    $meta  = trim($meta);
    $lines = explode("\n", $meta);
    $data  = [];
  
    foreach ($lines as $line)
    {
      $parts = explode("=", $line);
      $data[trim($parts[0])] = trim($parts[1]);
    }
  
    return $data;
  }
}

This file should be saved as workbench/formativ/cms/src/
Formativ/Cms/Engine/Blade.php.

The only difference can be found in the argument names (to bring them more in line with the rest of the class) and integrating the meta methods into the render() method.

Next up is layout controller class:

 
use Formativ\Cms\EngineInterface;
use Formativ\Cms\FilesystemInterface;
 
class LayoutController
extends BaseController
{
  protected $engine;
  protected $filesystem;
  
  public function __construct(
    EngineInterface $engine,
    FilesystemInterface $filesystem
  )
  {
    $this->engine     = $engine;
    $this->filesystem = $filesystem;
  
    Validator::extend(
      "add",
      function($attribute, $value, $params) {
        return !$this->filesystem->has("layouts/" . $value);
      }
    );
 
    Validator::extend(
      "edit",
      function($attribute, $value, $params) {
        $new  = !$this->filesystem->has("layouts/" . $value);
        $same = $this->filesystem->has("layouts/" . $params[0]);
  
        return $new or $same;
      }
    );
  }
 
  public function indexAction()
  {
    $layouts = $this->filesystem->listContents("layouts");
    $edit    = URL::route("admin/layout/edit") . "?layout=";
    $delete  = URL::route("admin/layout/delete") . "?layout=";
  
    return View::make("admin/layout/index", compact(
      "layouts",
      "edit",
      "delete"
    ));
  }
}

This file should be saved as app/controllers/LayoutController.php.

This is the first time we’re using Dependency Injection in our controller. Laravel is injecting our engine interface (which is the Blade wrapper) and our filesystem interface (which is the Flysystem wrapper). As usual, we assign the injected dependencies to protected properties. We also define two custom validation rules, which we’ll use when adding and editing the layout files.

We’ve also defined an indexAction() method which will be used to display a list of layout files which can then be edited or deleted. For the interface to be complete, we are going to need the following files:



  
    
    Laravel 4 File-Based CMS
          rel="stylesheet"
      href="{{ asset("css/bootstrap.min.css"); }}"
    />
          rel="stylesheet"
      href="{{ asset("css/shared.css"); }}"
    />
  
  
    @include("admin/include/navigation")
    
      
        
          @yield("content")

This file should be saved as app/views/admin/layout.blade.php.

 class="navbar navbar-inverse navbar-fixed-top"
 role="navigation"
>
  
    
      
  

      class="collapse navbar-collapse"
    id="navbar-collapse"
  >
    
      
        
          Layouts

This file should be saved as app/views/admin/include/navigation.blade.php.


  
    
      List Layouts
    
  

  
    
      Add New Layout

This file should be saved as app/views/admin/include/
layout/navigation.blade.php.

@extends("admin/layout")
@section("navigation/layout/class")
  active
@stop
@section("content")
  @include("admin/include/layout/navigation")
  @if (count($layouts))
    







        @foreach ($layouts as $layout)
          @if ($layout["type"] == "file")




          @endif
        @endforeach

                        
            File
                    
            Actions
                  
      
                                
                
                  {{ $layout["basename"] }}
                
                            
                
                  
                
                
                  
                
                          
      
    

  @else
    No layouts yet.
    
      create one now!
    
  @endif
@stop

File	Actions
{{ $layout["basename"] }}

This file should be saved as app/views/admin/layout/index.blade.php.

Route::any("admin/layout/index", [
  "as"   => "admin/layout/index",
  "uses" => "LayoutController@indexAction"
]);

This was extracted from app/routes.php.

These are quite a few files, so let’s go over them individually:

The first file is the main admin layout template. Every page in the admin area should be rendered within this layout template. As you can see, we’ve linked the jQuery and Bootstrap assets to provide some styling and interactive functionality to the admin area.
The second file is the main admin navigation template. This will also be present on every page in the admin area, though it’s better to include it in the main layout template than to clutter the main layout template with secondary markup.
The third file is a sub-navigation template, only present in the pages concerning layouts.
The fourth file is the layout index (or listing) page. It includes the sub-navigation and renders a table row for each layout file it finds. If none can be found, it will present a cheeky message for the user to add one.
Finally we add the index route to the routes.php file. At this point, the page should be visible via the browser. As there aren’t any layout files yet, you should see the cheeky message instead.

Let’s move onto the layout add page:

public function addAction()
{
  if (Input::has("save"))
  {
    $validator = Validator::make(Input::all(), [
      "name" => "required|add",
      "code" => "required"
    ]);
  
    if ($validator->fails())
    {
      return Redirect::route("admin/layout/add")
        ->withInput()
        ->withErrors($validator);
    }
  
    $meta = "
      title       = " . Input::get("title") . "
      description = " . Input::get("description") . "
      ==
    ";
  
    $name = "layouts/" . Input::get("name") . ".blade.php";
  
    $this->filesystem->write($name, $meta . Input::get("code"));
  
    return Redirect::route("admin/layout/index");
  }
  
  return View::make("admin/layout/add");
}

This was extracted from app/controllers/LayoutController.php.

@extends("admin/layout")
@section("navigation/layout/class")
  active
@stop
@section("content")
  @include("admin/include/layout/navigation")
  
    
      Name
      
        {{ $errors->first("name") }}
      
              type="text"
        class="form-control"
        id="name"
        name="name"
        placeholder="new-layout"
        value="{{ Input::old("name") }}"
      />
    

    
      Meta Title
              type="text"
        class="form-control"
        id="title"
        name="title"
        value="{{ Input::old("title") }}"
      />
    

    
      Meta Description
              type="text"  
        class="form-control"
        id="description"
        name="description"
        value="{{ Input::old("description") }}"
      />
    

    
      Code
      
        {{ $errors->first("code") }}
      
              class="form-control"
        id="code"
        name="code"
        rows="5"
        placeholder="<div>Hello world</div>"
      >{{ Input::old("code") }}
    

          type="submit"
      name="save"
      class="btn btn-default"
      value="Save"
    />
  
@stop

This file should be saved as app/views/admin/layout/add.blade.php.

Route::any("admin/layout/add", [
  "as"   => "admin/layout/add",
  "uses" => "LayoutController@addAction"
]);

This was extracted from app/routes.php.

The form processing, in the addAction() method, is wrapped in a check for the save parameter. This is the name of the submit button on the add form. We specify the validation rules (including one of those we defined in the constructor). If validation fails, we redirect back to the add page, bringing along the errors and old input. If not, we create a new file with the default meta title and default meta description as metadata. Finally we redirect to the index page.

The view is fairly standard (including the bootstrap tags we’ve used). The name and code fields have error messages and all of the fields have their values set to the old input values. We’ve also added a route to the add page.

Edit follows a similar pattern:

public function editAction()
{
  $layout      = Input::get("layout");
  $name        = str_ireplace(".blade.php", "", $layout);
  $content     = $this->filesystem->read("layouts/" . $layout);
  $extracted   = $this->engine->extractMeta($content);
  $code        = trim($extracted["template"]);
  $parsed      = $this->engine->parseMeta($extracted["meta"]);
  $title       = $parsed["title"];
  $description = $parsed["description"];
  
  if (Input::has("save"))
  {
    $validator = Validator::make(Input::all(), [
      "name" => "required|edit:" . Input::get("layout"),
      "code" => "required"
    ]);
  
    if ($validator->fails())
    {
      return Redirect::route("admin/layout/edit")
        ->withInput()
        ->withErrors($validator);
    }
  
    $meta = "
      title       = " . Input::get("title") . "
      description = " . Input::get("description") . "
      ==
    ";
  
    $name = "layouts/" . Input::get("name") . ".blade.php";
  
    $this->filesystem->put($name, $meta . Input::get("code"));
  
    return Redirect::route("admin/layout/index");
  }
  
  return View::make("admin/layout/edit", compact(
    "name",
    "title",
    "description",
    "code"
  ));
}

This was extracted from app/controllers/LayoutController.php.

@extends("admin/layout")
@section("navigation/layout/class")
  active
@stop
@section("content")
  @include("admin/include/layout/navigation")
  
    
      Name
      
        {{ $errors->first("name") }}
      
              type="text"
        class="form-control"
        id="name"
        name="name"
        placeholder="new-layout"
        value="{{ Input::old("name", $name) }}"
      />
    

    
      Meta Title
              type="text"
        class="form-control"
        id="title"
        name="title"
        value="{{ Input::old("title", $title) }}"
      />
    

    
      Meta Description
              type="text"
        class="form-control"
        id="description"
        name="description"
        value="{{ Input::old("description", $description) }}"
      />
    

    
      Code
      
        {{ $errors->first("code") }}
      
              class="form-control"
        id="code"
        name="code"
        rows="5"
        placeholder="<div>Hello world</div>"
      >{{ Input::old("code", $code) }}
    

          type="submit"
      name="save"
      class="btn btn-default"
      value="Save"
    />
  
@stop

This file should be saved as app/views/admin/layout/edit.blade.php.

Route::any("admin/layout/edit", [
  "as"   => "admin/layout/edit",
  "uses" => "LayoutController@editAction"
]);

This was extracted from app/routes.php.

The editAction() method fetches the layout file data and extracts/parses the metadata, so that we can present it in the edit form. Other than utilising the second custom validation function, we define in the constructor, there’s nothing else noteworthy in this method.

The edit form is also pretty much the same, except that we provide default values to the Input::old() method calls, giving the data extracted from the layout file. We also add a route to the edit page.

You may notice that the file name remains editable, on the edit page. When you change this value, and save the layout it won’t change the name of the current layout file, but rather generate a new layout file. This is an interesting (and in this case useful) side-effect of using the file name as the unique identifier for layout files.

Deleting layout files is even simpler:

public function deleteAction()
{
  $name = "layouts/" . Input::get("layout");
  $this->filesystem->delete($name);
  
  return Redirect::route("admin/layout/index");
}

This was extracted from app/controllers/LayoutController.php.

Route::any("admin/layout/delete", [
  "as"   => "admin/layout/delete",
  "uses" => "LayoutController@deleteAction"
]);

This was extracted from app/routes.php.

We link straight to the deleteAction() method in the index view. This method simply deletes the layout file and redirects back to the index page. We’ve added the appropriate route to make this page accessible.

We can now list the layout files, add new ones, edit existing ones and delete those layout files we no longer require. It’s basic, and could definitely be polished a bit, but it’s sufficient for our needs.

Creating Pages

Pages are handled in much the same way, so we’re not going to spend too much time on them. Let’s begin with the controller:

 
use Formativ\Cms\EngineInterface;
use Formativ\Cms\FilesystemInterface;
 
class PageController
extends BaseController
{
  protected $engine;
  protected $filesystem;
  
  public function __construct(
    EngineInterface $engine,
    FilesystemInterface $filesystem
  )
  {
    $this->engine = $engine;
    $this->filesystem = $filesystem;
  
    Validator::extend(
      "add",
      function($attribute, $value, $parameters) {
        return !$this->filesystem->has("pages/" . $value);
      }
    );
  
    Validator::extend(
      "edit",
      function($attribute, $value, $params) {
        $new = !$this->filesystem->has("pages/" . $value);
        $same = $this->filesystem->has("pages/" . $params[0]);
  
        return $new or $same;
      }
    );
  }
  
  public function indexAction()
  {
    $pages  = $this->filesystem->listContents("pages");
    $edit   = URL::route("admin/page/edit") . "?page=";
    $delete = URL::route("admin/page/delete") . "?page=";
  
    return View::make("admin/page/index", compact(
      "pages",
      "edit",
      "delete"
    ));
  }
  
  public function addAction()
  {
    $files   = $this->filesystem->listContents("layouts");
    $layouts = [];
  
    foreach ($files as $file)
    {
      $name = $file["basename"];
      $layouts[$name] = $name;
    }
  
    if (Input::has("save"))
    {
      $validator = Validator::make(Input::all(), [
        "name"   => "required|add",
        "route"  => "required",
        "layout" => "required",
        "code"   => "required"
      ]);
  
      if ($validator->fails())
      {
        return Redirect::route("admin/page/add")
          ->withInput()
          ->withErrors($validator);
      }
  
      $meta = "
        title       = " . Input::get("title") . "
        description = " . Input::get("description") . "
        layout      = " . Input::get("layout") . "
        route       = " . Input::get("route") . "
        ==
      ";
  
      $name = "pages/" . Input::get("name") . ".blade.php";
      $code = $meta . Input::get("code");
 
      $this->filesystem->write($name, $code);
  
      return Redirect::route("admin/page/index");
    }
  
    return View::make("admin/page/add", compact(
      "layouts"
    ));
  }
  
  public function editAction()
  {
    $files = $this->filesystem->listContents("layouts");
    $layouts = [];
  
    foreach ($files as $file)
    {
      $name = $file["basename"];
      $layouts[$name] = $name;
    }
   
    $page        = Input::get("page");
    $name        = str_ireplace(".blade.php", "", $page);
    $content     = $this->filesystem->read("pages/" . $page);
    $extracted   = $this->engine->extractMeta($content);
    $code        = trim($extracted["template"]);
    $parsed      = $this->engine->parseMeta($extracted["meta"]);
    $title       = $parsed["title"];
    $description = $parsed["description"];
    $route       = $parsed["route"];
    $layout      = $parsed["layout"];
  
    if (Input::has("save"))
    {
      $validator = Validator::make(Input::all(), [
        "name"   => "required|edit:" . Input::get("page"),
        "route"  => "required",
        "layout" => "required",
        "code"   => "required"
      ]);
  
      if ($validator->fails())
      {
        return Redirect::route("admin/page/edit")
          ->withInput()
          ->withErrors($validator);
      }
  
      $meta = "
        title       = " . Input::get("title") . "
        description = " . Input::get("description") . "
        layout      = " . Input::get("layout") . "
        route       = " . Input::get("route") . "
        ==
      ";
  
      $name = "pages/" . Input::get("name") . ".blade.php";
      $code = $meta . Input::get("code");
 
      $this->filesystem->put($name, $code);
  
      return Redirect::route("admin/page/index");
    }
  
    return View::make("admin/page/edit", compact(
      "name",
      "title",
      "description",
      "layout",
      "layouts",
      "route",
      "code"
    ));
  }
  
  public function deleteAction()
  {
    $name = "pages/" . Input::get("page");
    $this->filesystem->delete($name);
  
    return Redirect::route("admin/page/index");
  }
}

This file should be saved as app/controllers/PageController.php.

The constructor method accepts the same injected dependencies as our layout controller did. We also define similar custom validation rules to check the names of files we want to save.

The addAction() method differs slightly in that we load the existing layout files so that we can designate the layout for each page. We also add this (and the route parameter) to the metadata saved to the page file.

The editAction() method loads the route and layout parameters (in addition to the other fields) and passes them to the edit page template, where they will be used to populate the new fields.

  class="navbar navbar-inverse navbar-fixed-top"
  role="navigation"
>
  
    
      
    

    
      
        
          
            Layouts
          
        

        
          
            Pages

This file should be saved as app/views/admin/include/navigation.blade.php.


  
    
      List Pages
    
  

  
    
      Add New Page

This file should be saved as app/views/admin/include/
page/navigation.blade.php.

@extends("admin/layout")
@section("navigation/page/class")
  active
@stop
@section("content")
  @include("admin/include/page/navigation")
  @if (count($pages))
    







        @foreach ($pages as $page)
          @if ($page["type"] == "file")




          @endif
        @endforeach

                        
            File
                    
            Actions
                  
      
                                
                
                  {{ $page["basename"] }}
                
                            
                
                  
                
                
                  
                
                          
      
    

  @else
    No pages yet.
    
      create one now!
    
  @endif
@stop

File	Actions
{{ $page["basename"] }}

This file should be saved as app/views/admin/page/index.blade.php.

@extends("admin/layout")
@section("navigation/page/class")
  active
@stop
@section("content")
  @include("admin/include/page/navigation")
  
    
      Name
      
        {{ $errors->first("name") }}
      
              type="text"
        class="form-control"
        id="name"
        name="name"
        placeholder="new-page"
        value="{{ Input::old("name") }}"
      />
    

    
      Route
      
        {{ $errors->first("route") }}
      
              type="text"
        class="form-control"
        id="route"
        name="route"
        placeholder="/new-page"
        value="{{ Input::old("route") }}"
      />
    

    
      Layout
      
        {{ $errors->first("layout") }}
      
      {{ Form::select(
        "layout",
        $layouts,
        Input::old("layout"), 
        [
          "id" => "layout",
          "class" => "form-control"
        ]
      ) }}
    

    
      Meta Title
              type="text"
        class="form-control"
        id="title"
        name="title"
        value="{{ Input::old("title") }}"
      />
    

    
      Meta Description
              type="text"
        class="form-control"
        id="description"
        name="description"
        value="{{ Input::old("description") }}"
      />
    

    
      Code
      
        {{ $errors->first("code") }}
      
              class="form-control"
        id="code"
        name="code"
        rows="5"
        placeholder="<div>Hello world</div>"
      >{{ Input::old("code") }}
    

          type="submit"
      name="save"
      class="btn btn-default"
      value="Save"
    />
  
@stop

This file should be saved as app/views/admin/page/add.blade.php.

@extends("admin/layout")
@section("navigation/page/class")
 active
@stop
@section("content")
  @include("admin/include/page/navigation")
  
    
      Name
      
        {{ $errors->first("name") }}
      
              type="text"
        class="form-control"
        id="name"
        name="name"
        placeholder="new-page"
        value="{{ Input::old("name", $name) }}"
      />
    

    
      Route
      
        {{ $errors->first("route") }}
      
              type="text"
        class="form-control"
        id="route"
        name="route"
        placeholder="/new-page"
        value="{{ Input::old("route", $route) }}"
      />
    

    
      Layout
      
        {{ $errors->first("layout") }}
      
      {{ Form::select(
        "layout",
        $layouts,
        Input::old("layout", $layout), 
        [
          "id" => "layout",
          "class" => "form-control"
        ]
      ) }}
    

    
      Meta Title
              type="text"
        class="form-control"
        id="title"
        name="title"
        value="{{ Input::old("title", $title) }}"
      />
    

    
      Meta Description
              type="text"
        class="form-control"
        id="description"
        name="description"
        value="{{ Input::old("description", $description) }}"
      />
    

    
      Code
      
        {{ $errors->first("code") }}
      
              class="form-control"
        id="code"
        name="code"
        rows="5"
        placeholder="<div>Hello world</div>"
      >{{ Input::old("code", $code) }}
    

          type="submit"
      name="save"
      class="btn btn-default"
      value="Save"
    />
  
@stop

This file should be saved as app/views/admin/page/edit.blade.php.

The views follow a similar pattern to those which we created for managing layout files. The exception is that we add the new layout and route fields to the add and edit page templates. We’ve used the Form::select() method to render and select the appropriate layout.

Route::any("admin/page/index", [
  "as"   => "admin/page/index",
  "uses" => "PageController@indexAction"
]);
 
Route::any("admin/page/add", [
  "as"   => "admin/page/add",
  "uses" => "PageController@addAction"
]);
 
Route::any("admin/page/edit", [
  "as"   => "admin/page/edit",
  "uses" => "PageController@editAction"
]);
 
Route::any("admin/page/delete", [
  "as"   => "admin/page/delete",
  "uses" => "PageController@deleteAction"
]);

This was extracted from app/routes.php.

Finally, we add the routes which will allow us to access these pages. With all this in place, we can work on displaying the website content.

Displaying Content

Aside from our admin pages, we need to be able to catch the all requests, and route them to a single controller/action. We do this by appending the following route to the routes.php file:

Route::any("{all}", [
  "as"   => "index/index",
  "uses" => "IndexController@indexAction"
])->where("all", ".*");

This was extracted from app/routes.php.

We pass all route information to a named parameter ({all}), which will be mapped to the IndexController::indexAction() method. We also need to specify the regular expression with which the route data should be matched. With ”.*” we’re telling Laravel to match absolutely anything. This is why this route needs to come right at the end of the app/routes.php file.

 
use Formativ\Cms\EngineInterface;
use Formativ\Cms\FilesystemInterface;
 
class IndexController
extends BaseController
{
  protected $engine;
  protected $filesystem;
  
  public function __construct(
    EngineInterface $engine,
    FilesystemInterface $filesystem
  )
  {
    $this->engine = $engine;
    $this->filesystem = $filesystem;
  }
  
  protected function parseFile($file)
  {
    return $this->parseContent(
      $this->filesystem->read($file["path"]),
      $file
    );
  } 
  
  protected function parseContent($content, $file = null)
  {
    $extracted = $this->engine->extractMeta($content);
    $parsed    = $this->engine->parseMeta($extracted["meta"]);
  
    return compact("file", "content", "extracted", "parsed");
  }
  
  protected function stripExtension($name)
  {
    return str_ireplace(".blade.php", "", $name);
  }
  
  protected function cleanArray($array)
  {
    return array_filter($array, function($item) {
      return !empty($item);
    });
  }
  
  public function indexAction($route = "/")
  {
    $pages = $this->filesystem->listContents("pages");
  
    foreach ($pages as $page)
    {
      if ($page["type"] == "file")
      {
        $page = $this->parseFile($page);
  
        if ($page["parsed"]["route"] == $route)
        {
          $basename   = $page["file"]["basename"];
          $name       = "pages/extracted/" . $basename;
          $layout     = $page["parsed"]["layout"];
          $layoutName = "layouts/extracted/" . $layout;
          $extends    = $this->stripExtension($layoutName);
 
          $template = "
            @extends('" . $extends . "')
            @section('page')
              " . $page["extracted"]["template"] . "
            @stop
          ";
  
          $this->filesystem->put($name, trim($template));
  
          $layout = "layouts/" . $layout;
  
          $layout = $this->parseContent(
            $this->filesystem->read($layout)
          );
  
          $this->filesystem->put(
            $layoutName,
            $layout["extracted"]["template"]
          );
  
          $data = array_merge(
            $this->cleanArray($layout["parsed"]),
            $this->cleanArray($page["parsed"])
          );
  
          return View::make(
            $this->stripExtension($name),
            $data
          );
        }
      }
    }
  }
}

This file should be saved as app/controllers/IndexController.php.

In the IndexController class, we’ve injected the same two dependencies: $filesystem and $engine. We need these to fetch and extract the template data.

We begin by fetching all the files in the app/views/pages directory. We iterate through them filtering out all the returned items which have a type of file. From these, we fetch the metadata and check if the route defined matches that which is being requested.

If there is a match, we extract the template data and save it to a new file, resembling app/views/pages/extracted/[original name]. We then fetch the layout defined in the metadata, performing a similar transformation. We do this because we still want to run the templates through Blade (so that @extends, @include, @section etc.) all still work as expected.

We filter the page metadata and the layout metadata, to omit any items which do not have values, and we pass the merged array to the view. Blade takes over and we have a rendered view!

Extending The CMS

We’ve implemented the simplest subset of October functionality. There’s a lot more going on that I would love to implement, but we’ve run out of time to do so. If you’ve found this project interesting, perhaps you would like to take a swing at implementing partials (they’re not much work if you prevent them from having metadata). Or perhaps you’re into JavaScript and want to try your hand at emulating some of the Ajax framework magic that October’s got going on…

You can learn more about OctoberCMS’s features at: http://octobercms.com/docs/cms/themes.

Conclusion

If you enjoyed this tutorial; it would be helpful if you could click the Recommend button.

This tutorial comes from a book I’m writing. If you like it and want to support future tutorials; please consider buying it. Half of all sales go to Laravel.

Laravel 4 File-Based CMS was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Laravel 4 Embedded Systems

Christopher Pitt — Thu, 09 Jan 2014 07:51:22 GMT

A Comprehensive Tutorial

What do you think of when you hear the name Laravel? Laravel 4 powers an increasing number of websites, but that’s not the only place it can be used. In this tutorial we’re going to use it to control embedded systems.

While much effort has been spent in the pursuit of accuracy; there’s a good chance you could stumble across a curly quote in a code listing, or some other egregious errata. Please make a note and I will fix where needed.

I have also uploaded this code to Github. You need simply follow the configuration instructions in this tutorial, after downloading the source code, and the application should run fine.

This assumes, of course, that you know how to do that sort of thing. If not; this shouldn’t be the first place you learn about making PHP applications.

https://github.com/formativ/tutorial-laravel-4-embedded-systems

If you spot differences between this tutorial and that source code, please raise it here or as a GitHub issue. Your help is greatly appreciated.

Gathering Parts

This tutorial demonstrates the use of an Arduino and a web cam. There are other smaller parts, but these are the main ones. The Arduino needs firmata installed (explained later) and the webcam needs to be compatible with Linux and Motion (installed later).

We will go over using things like LEDs and resistors, but none of those are particularly important. We will also go over using servos and these are important. You can find the bracket I use at: https://www.sparkfun.com/
products/10335 and the servos I use at: https://www.sparkfun.com/
products/9065. You can get these parts, and an Arduino Uno, for less than $55.

Installing Dependencies

We’re developing a Laravel 4 application which has lots of server-side aspects; but there’s also an interactive interface. There be scripts!

For this; we’re using Bootstrap and jQuery. Download Bootstrap at: http://getbootstrap.com/ and unpack it into your public folder. Where you put the individual files makes little difference, but I have put the scripts in public/js, the stylesheets in public/css and the fonts in public/fonts. Where you see those paths in my source code; you should substitute them with your own.

Next up, download jQuery at: http://jquery.com/download/ and unpack it into your public folder.

For the server-side portion of dependencies, we need to download a library called Ratchet. I’ll explain it shortly, but in the meantime we need to add it to our composer.json file:

"require" : {
    "laravel/framework" : "4.0.*",
    "cboden/Ratchet"    : "0.3.*"
},

This was extracted from composer.json.

Follow that up with:

composer update

Ratchet isn’t built specifically for Laravel 4, so there are no service providers for us to add.

We’ll now have access to the Ratchet library for client-server communication, Bootstrap for styling the interface and jQuery for connecting these two things together.

Note About Errata

I love all things Arduino and Raspberry Pi. When I’m not programming; I’m trying to build things (in the real world) which can interact with my programming. Don’t let that fool you though: I am not an expert in electronics. There are bound to be better ways to do all of this stuff.

If you can’t get a specific program installed because apt or permissions or network settings or aliens; I cannot help you. I have neither the time nor the experience to guide you through the many potential problems. Hit me up on Twitter and, if I have not yet already done so, I will connect you to a forum where you can discuss this with other (smarter) people.

Creating An Interface

The first step to creating an interface is returning static HTML for a web request. We handle this by creating a route, a controller and a view:


Route::get("/", [
  "as"   => "index/index",
  "uses" => "IndexController@indexAction"
]);

This file should be saved as app/routes.php.


class IndexController
extends BaseController
{
  public function indexAction()
  {
    return View::make("index/index");
  }
}

This file should be saved as app/controllers/IndexController.php.



  
    
    Laravel 4 Embedded Systems
    
    
    
  
  
    
      
        
          Laravel 4 Embedded Systems

This file should be saved as app/views/index/index.blade.php.

If you’ve created all of these files (and configured your web server to serve the Laravel application) then you should see a set of controls in your browser, when you visit /. Before we move on; let’s just quickly set up a socket server for this interface to talk to the PHP server with….

Creating A Socket Server

We’ve covered this topic before; so I won’t go into too much detail. We’re going to set up a Ratchet socket server, to pass messages back and forth between the interface and the PHP server.

try {
  if (!WebSocket) {
      console.log("no websocket support");
  } else {

    var socket = new WebSocket("ws://127.0.0.1:8081/");

    socket.addEventListener("open", function (e) {
      console.log("open: ", e);
    });

    socket.addEventListener("error", function (e) {
      // console.log("error: ", e);
    });

    socket.addEventListener("message", function (e) {
      var data = JSON.parse(e.data);
      console.log("message: ", data);
    });

    // console.log("socket:", socket);

    window.socket = socket;

  }
} catch (e) {
  // console.log("exception: " + e);
}

This file should be saved as public/js/shared.js.


namespace Formativ\Embedded;

use Evenement\EventEmitter;
use Illuminate\Support\ServiceProvider;

class EmbeddedServiceProvider
extends ServiceProvider
{
  protected $defer = true;

  public function register()
  {
    $this->app->bind("embedded.emitter", function()
    {
      return new EventEmitter();
    });

    $this->app->bind("embedded.command.serve", function()
    {
      return new Command\Serve(
        $this->app->make("embedded.socket")
      );
    });

    $this->app->bind("embedded.socket", function()
    {
      return new Socket(
        $this->app->make("embedded.emitter")
      );
    });

    $this->commands(
      "embedded.command.serve"
    );
  }

  public function provides()
  {
    return [
      "embedded.emitter",
      "embedded.command.serve",
      "embedded.socket"
    ];
  }
}

This file should be saved as workbench/formativ/embedded/src/
Formativ/Embedded/EmbeddedServiceController.php.


namespace Formativ\Embedded;

use Evenement\EventEmitterInterface;
use Ratchet\MessageComponentInterface;

interface SocketInterface
extends MessageComponentInterface
{
    public function getEmitter();
    public function setEmitter(EventEmitterInterface $emitter);
}

This file should be saved as workbench/formativ/embedded/src/
Formativ/Embedded/SocketInterface.php.


namespace Formativ\Embedded;

use Evenement\EventEmitterInterface as Emitter;
use Exception;
use Ratchet\ConnectionInterface as Connection;

class Socket
implements SocketInterface
{
  protected $emitter;

  protected $connection;

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

  public function setEmitter(Emitter $emitter)
  {
    $this->emitter = $emitter;
  }

  public function __construct(Emitter $emitter)
  {
    $this->emitter = $emitter;
  }

  public function onOpen(Connection $connection)
  {
    $this->connection = $connection;
    $this->emitter->emit("open");
  }

  public function onMessage(Connection $connection, $message)
  {
    $this->emitter->emit("message", [$message]);
  }

  public function onClose(Connection $connection)
  {
    $this->connection = null;
  }

  public function onError(Connection $connection, Exception $e)
  {
    $this->emitter->emit("error", [$e]);
  }

  public function send($message)
  {
    if ($this->connection)
    {
      $this->connection->send($message);
    }
  }
}

This file should be saved as workbench/formativ/embedded/src/
Formativ/Embedded/Socket.php.

The Socket class only has room for a single connection. Feel free to change this so that it can handle any number of controlling connections.


namespace Formativ\Embedded\Command;

use Formativ\Embedded\SocketInterface;
use Illuminate\Console\Command;
use Ratchet\ConnectionInterface;
use Ratchet\Http\HttpServer;
use Ratchet\Server\IoServer;
use Ratchet\WebSocket\WsServer;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputArgument;

class Serve
extends Command
{
  protected $name = "embedded:serve";

  protected $description = "Creates a firmata socket server.";

  public function __construct(SocketInterface $socket)
  {
    parent::__construct();

    $this->socket = $socket;

    $socket->getEmitter()->on("message", function($message) {
      $this->info("Message: " . $message . ".");
    });

    $socket->getEmitter()->on("error", function($e) {
      $this->line("Exception: " . $e->getMessage() . ".");
    });
  }

  public function fire()
  {
    $port = (integer) $this->option("port");

    $server = IoServer::factory(
      new HttpServer(
        new WsServer(
          $this->socket
        )
      ),
      $port
    );

    $this->info("Listening on port " . $port . ".");
    $server->run();
  }

  protected function getOptions()
  {
    return [
      [
        "port",
        null,
        InputOption::VALUE_REQUIRED,
        "Port to listen on.",
        8081
      ]
    ];
  }
}

This file should be saved as workbench/formativ/embedded/src/
Formativ/Embedded/Command/Serve.php.

These four files create a means with which we can start a socket server, listen for messages and respond to them. The shared.js file connects to this server and allows us to send and receive these messages. It’s simpler than last time; but sufficient for our needs!

Connection To Arduino

Real-time communication is typically done through a software layer called Firmata. There are Firmata libraries for many programming languages, though PHP is not one of them. While there is one library listed on the official Firmata website, I could not get it to work.

So we’re going to create our own simple Firmata-like protocol. I managed to put one together that handles analog reads, analog writes and servo control. It does this by parsing strings received over serial connection. This is what it looks like:

#include 
 
String buffer = "";
String parts[3];
Servo servos[13];
int index = 0;
 
void setup()
{
  Serial.begin(9600);
  buffer.reserve(200);
}
 
void loop()
{
 
}
 
void handle()
{ 
  int pin = parts[1].toInt();
  int value = parts[2].toInt();
 
  if (parts[0] == "pinMode")
  {
    if (parts[2] == "output")
    {
      pinMode(pin, OUTPUT);
    }
 
    if (parts[2] == "servo")
    {
      servos[pin].attach(pin);
    }
  }
 
  if (parts[0] == "digitalWrite")
  {
    if (parts[2] == "high")
    {
      digitalWrite(pin, HIGH);
    }
    else
    {
      digitalWrite(pin, LOW);
    }
  }
 
  if (parts[0] == "analogWrite")
  {
    analogWrite(pin, value);
  }
 
  if (parts[0] == "servoWrite")
  {
    servos[pin].write(value);
  }
 
  if (parts[0] == "analogRead")
  {
    value = analogRead(pin);
  }
 
  Serial.print(parts[0] + "," + parts[1] + "," + value + ".\n");
}
 
void serialEvent()
{
  while (Serial.available())
  {
    char in = (char) Serial.read();
 
    if (in == '.' || in == ',')
    {
      parts[index] = String(buffer);
      buffer = "";
 
      index++;
 
      if (index > 2)
      {
        index = 0;
      }
    }
    else
    {
      buffer += in;
    }
 
    if (in == '.')
    {
      index = 0;
      buffer = "";
      handle();
    }
  }
}

This code needs to be uploaded to the Arduino you’re working with for any communication between our server and the Arduino to take place.

The Arduino sketch is only one side of the puzzle. We also need to modify our socket server to communicate with the Arduino:

public function __construct(SocketInterface $socket)
{
  parent::__construct();
  
  $this->socket = $socket;
  
  $socket->getEmitter()->on("message", function($message)
  { 
    fwrite($this->device, $message);
  
    $data = trim(stream_get_contents($this->device));
    $this->info($data);
  
    $this->socket->send($data);
  });
  
  $socket->getEmitter()->on("error", function($e)
  {
    $this->line("exception: " . $e->getMessage() . ".");
  });
}
 
public function fire()
{
  $this->device = fopen($this->argument("device"), "r+");
  stream_set_blocking($this->device, 0);
  
  $port = (integer) $this->option("port");
  
  $server = IoServer::factory(
    new HttpServer(
      new WsServer(
        $this->socket
      )
    ),
    $port
  );
  
  $this->info("Listening on port " . $port . ".");
  $server->run();
}
 
protected function getArguments()
{
  return [
    [
      "device",
      InputArgument::REQUIRED,
      "Device to use."
    ]
  ];
}
 
public function __destruct()
{
  if (is_resource($this->device)) {
    fclose($this->device); 
  }
}

We’re using PHP file read/write methods to communicate with the Arduino. In our fire() method, we open a connection to the Arduino and store it in $this->device. We also set the stream to non-blocking. This is so that read requests to the Arduino don’t wait until data is returned before allowing the rest of the PHP processing to take place.

In the __construct() method we also modify the message event listener to write the incoming message (from the browser) to the Arduino. We read any info the Arduino has and send it back to the socket. This effectively creates a bridge between the Arduino and the socket.

We’ve also added two additional methods. The getArguments() method stipulates a required device argument. We want the serve command to be able to use any device name, so this argument makes sense. We’ve also added a __destruct() method to close the connection to the Arduino.

Finally, we need to add some JavaScript to read and write from the Arduino:

try {
  if (!WebSocket) {
    console.log("no websocket support");
  } else {
  
    var socket = new WebSocket("ws://127.0.0.1:8081/");
    var sensor = $("[name='sensor']");
    var led = $("[name='led']");
    var x = $("[name='x']");
    var y = $("[name='y']");
  
    socket.addEventListener("open", function (e) {
      socket.send("pinMode,6,output.");
      socket.send("pinMode,3,servo.");
      socket.send("pinMode,5,servo.");
    });
  
    socket.addEventListener("error", function (e) {
      // console.log("error: ", e);
    });
  
    socket.addEventListener("message", function (e) {
  
    var data = e.data;
    var parts = data.split(",");
  
    if (parts[0] == "analogRead") {
      sensor.val(parseInt(parts[2], 10));
    }
  
  });
  
  window.socket = socket;
  
  led.on("change", function() {
    socket.send("analogWrite,6," + led.val() + ".");
  });
  
  x.on("change", function() {
    socket.send("servoWrite,5," + x.val() + ".");
  });
  
  y.on("change", function() {
    socket.send("analogWrite,3," + y.val() + ".");
  });
  
  setInterval(function() {
    socket.send("analogRead,0,void.");
  }, 1000);
  
  }
} catch (e) {
  // console.log("exception: " + e);
}

This script does a number of cool things. When it loads, we set the pinMode of the LED pin (6) and the two servo pins (3, 5) to the correct modes. We also attach a message event listener to receive and parse messages from the Arduino.

We then attach some event listeners for the input elements in the interface. These will respond to changes in value by sending signals to the Arduino to adjust its various pin values.

Finally, we set a timer to ping the Arduino with analogRead requests on the sensor pin. Thanks to the message event listener, the return values will be received and reflected in the sensor input field.

Spinning Up

To connect to the Arduino, you should run the following command:

php artisan embedded:serve /dev/cu.usbmodem1411

On my system, the Arduino is reflected as /dev/cu.usbmodem1411 by this may differ on yours. For instance, my Ubuntu machine shows it as /dev/ttyACM0. The easiest way to find out what it is, is to unplug it, then run the following command:

ls /dev/tty*

Look over the list to familiarise yourself with the devices you see there. The plug the Arduino in, wait a couple seconds and run that command again. This time you should see a new addition to the list of devices. This is most likely your Arduino.

You may be wondering why my device starts with cu and not tty. I first tried the tty version of the Arduino and it would cause the server to hang. I experimented and found that the cu version let me connect and communicate with the Arduino. Go figure…

I usually like to include Vagrant configurations for running these projects. This time I found it confusing to try and communicate with an Arduino through the host machine. So instead I decided to try the server.php script bundled with Laravel applications. Turns out you can run the server with the following command:

php -S 127.0.0.1:8080 -t ./public server.php

Now you can go to http://127.0.0.1:8080 and see the interface we created earlier. You need to start the serve command successfully before this interface will work. If everything is running correctly, you should immediately start to see the sensor values being updated in the interface.

You can now adjust the LED input to control the brightness of the LED, and the x and y inputs to control the rotation of the servos.

Adding A Webcam

Streaming video from a web cam can be tricky, so we’re going to take time-lapse photos instead…

Installing ImageSnap On OSX

The utility we’ll be using on OSX is called ImageSnap. We can install it with homebrew:

brew install imagesnap

Once that’s installed; we can periodically take photos with it by using a command resembling:

imagesnap -d "Microsoft LifeCam" -w 3

The web cam I am using is Microsoft LifeCam but you can find the appropriate one for you with the command:

imagesnap -l

I also had to add some warm-up time, with the -w switch.

Installing Streamer On Ubuntu/Debian

The utility we’ll be using on Ubuntu/Debian is called Streamer. We can install it with the command:

apt-get install -y streamer

You can take a photo with the web cam, using the following command:

streamer -o snapshot.jpeg

Displaying Photos In The Interface

Depending on whether you are using OSX or Ubuntu/Debian; you will need to set up a shell script to periodically take photos. Save them to a web-accessible location and display them with the following changes:

This was extracted from app/views/index/index.blade.php.

setInterval(function() {
  $("[name='photo']").attr("src", "[path to photo]");
}, 1000);

This was extracted from public/js/shared.js.

Conclusion

If you enjoyed this tutorial; it would be helpful if you could click the Recommend button.

This tutorial comes from a book I’m writing. If you like it and want to support future tutorials; please consider buying it. Half of all sales go to Laravel.

Laravel 4 Embedded Systems was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Composer

Christopher Pitt — Tue, 07 Jan 2014 09:02:23 GMT

A crash course

Composer is a PHP dependency manager. It lets you define the dependencies your project needs. It mainly downloads dependencies from http://packagist.org, but can accept other sources as well.

That guy means business.

Installing Composer

You can download Composer from http://getcomposer.org/
download/, where you will also find installation instructions for your system. Here’s I’m using the instructions for installing with Curl. I also move the composer.phar file to /usr/local/bin/composer so that I can use it from anywhere in the system. If you you don’t have Curl installed, or would prefer another installation approach, there are instructions for you too!

Some bad-ass instructions there…

Once Composer is installed, you simply need to know the name of the dependency your project requires, and you specify this dependency in a file called composer.json. The composer.json file also allows you to give your project a name, version and a few other details, which can be used to publish your own Composer packages to Packagist.

Once you’re happy with the dependencies you have defined; it’s time to install them. Go to your command line and type composer install. I typically add--no-dev because Composer will install development dependencies by default. If your dependencies will need to build or test themselves, it’s best to leave this out. Installing dependencies may take some time, but any indication of progress is a good sign. Get a cup of coffee and wait it out.

Composer will automatically download nested dependencies, and the more things it needs to download, the longer it will take to download them. When it’s done; it will also generate a decent class autoloader script. You can immediately start to use auto-loaded dependencies by including vendor/autoload.php in your PHP scripts.

Ain’t nobody got time for…not autoloading?!

The libraries you install with Composer are located in the same vendor folder, and Composer will also create a lock file which records the exact versions of your dependencies so that they can be installed in the same way on production servers.

If your favourite PHP framework installs with Composer; it probably includes this file for you.

If you are using a framework that doesn’t include the class autoload script, or no framework at all, you just need to include the vendor/autoloader.php file to be able to autoload your dependencies.

Finding Composer packages

There are many ways to find Composer packages, but the easiest are in the readme.md files of GitHub repositories, in the library or framework documentation and by searching http://packagist.org.

More and more library authors are creating their own composer.json files and submitting their libraries to Packagist. They will usually explain how to use their libraries as a dependency, but it also helps to check any composer.json files you see in GitHub repositories.

Searching Packagist is a little harder if you don’t know what you are looking for, but a search for “http” quickly returned many results (including Guzzle). Give it a shot if you can’t find what you need using GitHub’s search function.

More packages than a FedEx truck.

Submitting your own packages to Packagist

Go to http://packagist.org and sign in. If you haven’t already got an account, you should create it and link to your GitHub account.

Submit. SUBMIT!

There’s a big “Submit Package” button. Click it and paste the URL to your GitHub repository in the text field. Submit the form and you should be good to go.

Conclusion

If you have any questions; be sure to check out the forums, FAQ and help documents for the thing you’re struggling with.

https://packagist.org/

http://getcomposer.org/

If you found this tutorial helpful, please tell me about it @followchrisp and be sure to recommend it to PHP developers. All PHP developers.

Composer was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Laravel 4 Multisites

Christopher Pitt — Tue, 07 Jan 2014 09:02:10 GMT

A Comprehensive Tutorial

Introduction

Laravel 4 is a huge step forward for the PHP community. It’s beautifully written, full of features and the community is presently exploding. Today we’re going to explore how to build multisite applications with it.

I have spent two full hours getting the code out of a Markdown document and into Medium. Medium really isn’t designed for tutorials such as this, and while much effort has been spent in the pursuit of accuracy; there’s a good chance you could stumble across a curly quote in a code listing. Please make a note and I will fix where needed.

I have also uploaded this code to Github. You need simply follow the configuration instructions in this tutorial, after downloading the source code, and the application should run fine. This assumes, of course, that you know how to do that sort of thing. If not; this shouldn’t be the first place you learn about making PHP applications.

https://github.com/formativ/tutorial-laravel-4-multisites

If you spot differences between this tutorial and that source code, please raise it here or as a GitHub issue. Your help is greatly appreciated.

Installing Laravel 4

Laravel 4 uses Composer to manage its dependencies. You can install Composer by following the instructions at http://getcomposer.org/
doc/00-intro.md#installation-nix.

Once you have Composer working, make a new directory or navigation to an existing directory and install Laravel 4 with the following command:

composer create-project laravel/laravel ./ --prefer-dist

If you chose not to install Composer globally (though you really should), then the command you use should resemble the following:

php composer.phar create-project laravel/laravel ./ --prefer-dist

Both of these commands will start the process of installing Laravel 4. There are many dependencies to be sourced and downloaded; so this process may take some time to finish.

Note on Operating Systems

I work on a Macbook, and deal with Linux servers every day. I seldom interact with Windows-based machines. As a result; most of the work I do is never run on Windows. Remember this as you follow this tutorial — I will not show how to do things on Windows because it’s dead to me. If you are forced to use it; then you have my sympathies.

Note on Server Setup

We’re going to look at how to create virtual hosts in Apache2 and Nginx, but we won’t look at how to get those systems running in the first place. It’s not something I consider particularly tricky, and the internet is filled with wonderful tutorials on the subject.

Note on Dutch

I use it in this tutorial, but I don’t really speak it. Google Translate does. Blame Google Translate.

Virtual Hosts

It may surprise you to know that single domain names do not translate into single web servers. Modern web servers have the ability to load many different domains, and these domains are often referred to as Virtual Hosts or Virtual Domains. We’re going to see how to use them with Laravel 4.

Adding Virtual Host Entries

When you type an address into your browser, and hit enter; your browser goes through a set of steps in order to get you the web page you want. First, it queries what’s called a hosts file to see if the address you typed in is a reference to a local IP address. If not found, the browser then queries whatever DNS servers are available to the operating system.

A DNS server compares an address (e.g. example.com) with a list of IP addresses it has on file. If an IP address is found; the browser’s request is forwarded to it and the web page is delivered.

This is a rather simplified explanation of the steps involved. You can probably find more details at: http://en.wikipedia.org/wiki/Internet.

In a sense; the hosts file acts as a DNS server before any remote requests are made. It follows that the best place to add references to local IP addresses (local web servers) is in the hosts file.

To do that, open the hosts file:

sudo vim /etc/hosts

If that command gives you errors then you can try running it without the sudo part. Sudo is (simply speaking) a way to run a command at the highest permission level possible; to ensure it executes correctly. If may be that you do not have sufficient privileges to run commands as root (with sudo).

Vim is a teminal-based text editor. If you’re uneasy using it; what we’re after is editing /etc/hosts.

On a new line, at the bottom of /etc/hosts, add:

127.0.0.1 dev.tutorial

This was extracted from /etc/hosts for brevity.

This line tells the operating system to send requests to dev.tutorial to 127.0.0.1. You’ll want to replace 127.0.0.1 with the IP address of the server you are using for this tutorial (assuming it’s not LAMP/MAMP on your local machine) and dev.tutorial with whatever you want the virtual host to be.

You’ll need to repeat this process for each virtual host you add. If your application has (for example) three different domains pointing to it; then you will need to set three of these up to test them locally.

Creating Apache 2 Virtual Hosts

Apache2 virtual host entries are created by manipulating the configuration files usually located in /etc/apache2/sites-available/. You can edit the default file, and add the entries to it, or you can create new files.

If you choose to create new files for your virtual host entries, then you will need to symlink them to /etc/apache2/sites-enabled/* where * matches the name of the files you create in the sites-available folder.

The expanded syntax of virtual host entries can be quite a bit to type/maintain; so I have a few go-to lines I usually use:


    DocumentRoot /var/www/site1
    ServerName dev.site1

This was extracted from /etc/apache2/sites-available/default for brevity.

The ServerName property can be anything you like — it’s the address you will use in your browser. The DocumentRoot property needs to point to an existing folder in the filesystem of the web server machine.

You can learn more about virtual host entries, in Apache2, at: http://httpd.apache.org/docs/current/vhosts/examples.html.

Creating Nginx Virtual Hosts

Similar to Apache2, Nginx virtual host entries are created by manipulating the configuration files usually located in /etc/nginx/sites-available/. You can edit the default file, and add the entries to it, or you can create new files.

If you choose to create new files for your virtual host entries, then you will need to symlink them to /etc/nginx/sites-enabled/* where * matches the name of the files you create in the sites-available folder.

The expanded syntax of virtual host entries can be quite a bit to type/maintain; so I have a few go-to lines I usually use:

server {
    listen 80;
    server_name dev.site1;
    root /var/www/site1;
    index index.php;
 
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php5-fpm.sock;
        fastcgi_index index.php
        include fastcgi_params;
    }
}

This was extracted from /etc/nginx/sites-available/default for brevity.

This site definition assumes you are using PHP5 FPM. Getting this installed and running is out of the scope of this tutorial, but there are plenty of great tutorials on the subject.

You can learn more about virtual host entries, in Nginx, at: https://www.digitalocean.com/community/articles/how-to-set-up-nginx-virtual-hosts-server-blocks-on-ubuntu-12-04-lts--3.

Environments

Laravel 4 employs a system of execution environments. Think of these as different contexts in which different configuration files will be loaded; determined by the host name of the machine or command flags.

To illustrate this concept; think of the differences between developing and testing your applications locally and running them on a production server. You will need to target different databases, use different caching schemes etc.

This can be achieved, deterministically, by setting the environments to match the host names of the machines the code will be executed (local and production respectively) and having different sets of configuration files for each environment.

When a Laravel 4 application is executed, it will determine the environment that you are running it in, and adjust the path to configuration files accordingly. This approach has two caveats.

The first caveat is that the PHP configuration files in app/config are always loaded and environment-based configuration files are then loaded on top of them. If you have a database set up in app/config/
database.php and nothing in app/config/production/database.php, the global database configuration details will apply.

The second caveat is that you can override the environment Laravel 4 would otherwise use by supplying an environment flag to artisan commands:

php artisan migrate --env=local

This will tell artisan to execute the database migrations in the local environment, whether or not the environment you are running it in is local.

This is important to multisites because Laravel 4 configuration files have the ability to connect to different database, load different views and send different emails based on environmental configuration.

Note on Running Commands in Local Environment

The moment you add multiple environments to your application, you create the possibility that artisan commands might be run on the incorrect environment.

Just because Laravel 4 is capable of executing in the correct environment doesn’t mean you will always remember which environment you are in or which environment you should be in…

Start learning to provide the environment for every artisan command, when you’re working with multiple environments. It’s a good habit to get into.

Using Site-Specific Views

One of the benefits of multiple environment-specific configuration sets is that we can load different views for different sites. Let’s begin by creating a few:

127.0.0.1 dev.www.tutorial-laravel-4-multisites
127.0.0.1 dev.admin.tutorial-laravel-4-multisites

This was extracted from /etc/hosts for brevity.

You can really create any domains you want, but for this part we’re going to need multiple domains pointing to our testing server so that we can actually see different view files being loaded, based on domain.

Next, update your app/bootstrap/start.php file to include the virtual host domains you’ve created:

$env = $app->detectEnvironment([
    "www"   => ["dev.www.tutorial-laravel-4-multisites"],
    "admin" => ["dev.admin.tutorial-laravel-4-multisites"]
]);

This was extracted from /bootstrap/start.php for brevity.

Phil Sturgeon made an excellent point about not using URL’s to toggle environments, as somebody can easily set a hostname to match your development environment and point it to your production environment to cause unexpected results. This can lead to people gleaning more information than you would expect via debugging information or backtraces.

If you would rather determine the current environment via a server configuration property; you can pass a callback to the detectEnvironment() method:

$env = $app->detectEnvironment(function()
{
    return Input::server("environment", "development");
});

This was extracted from /bootstrap/start.php for brevity.

Clean out the app/views folder and create www and admin folders, each with their own layout.blade.php and index/index.blade.php files.



    
        
        Laravel 4 Multisites
    
    
        @yield("content")

This file should be saved as app/views/www/layout.blade.php.

@extends("layout")
@section("content")
    Welcome to our website!
@stop

This file should be saved as app/views/www/index/index.blade.php.



    
        
        Laravel 4 Multisites — Admin
    
    
        @yield("content")

This file should be saved as app/views/admin/layout.blade.php.

@extends("layout")
@section("content")
    Please log in to use the admin.
@stop

This file should be saved as app/views/admin/index/index.blade.php.

Let’s also prepare the routes and controllers for the rest of the tutorial, by updating both:

Route::any("/", [
    "as"   => "index/index",
    "uses" => "IndexController@indexAction"
]);
This file should be saved as app/routes.php.
class IndexController
extends BaseController
{
    public function indexAction()
    {
        return View::make("index/index");
    }
}
This file should be saved as app/controllers/IndexController.php.
In order for Laravel to know which views to use for each environment, we should also create the configuration files for the environments.
return [
    "paths" => [app_path() . "/views/www"]
];
This file should be saved as app/config/www/view.php.
return [
    "paths" => [app_path() . "/views/admin"]
];
This file should be saved as app/config/admin/view.php.
These new configuration files tell Laravel 4 not only to look for views in the default directory but also to look within the environment-specific view folders we’ve set up. Going to each of these virtual host domains should now render different content.
I would recommend this approach for sites that need to drastically change their appearance in ways mere CSS couldn’t achieve. If, for example, your different sites need to load different HTML or extra components then this is a good approach to take.
Another good time to use this kind of thing is when you want to separate the markup of a CMS from that of a client-facing website. Both would need access to the same business logic and storage system, but their interfaces should be vastly different.
I’ve also used this approach when I’ve needed to create basic mobile interfaces and rich interactive interfaces for the same brands…
You can learn more about environments at: http://laravel.com/docs/
configuration#environment-configuration.
Using Site-Specific Routes
Another aspect to multiple-domain applications is how they can affect (and be affected by) the routes file. Consider the following route groups:
Route::group([
    "domain" => "dev.www.tutorial-laravel-4-multisites"
], function()
{
    Route::any("/about", function()
    {
        return "This is the client-facing website.";
    });
});
Route::group([
    "domain" => "dev.admin.tutorial-laravel-4-multisites"
], function()
{
    Route::any("/about", function()
    {
        return "This is the admin site.";
    });
});
This was extracted from app/routes.php for brevity.
Aside from the basic routes Laravel 4 supports, it’s also possible to group routes within route groups. These groups provide an easy way of applying common logic, filtering and targeting specific domains.
Not only can we explicitly target our different virtual host domains, we can target all subdomains with sub-domain wildcard:
Route::group([
    "domain" => "dev.{sub}.tutorial-laravel-4-multisites"
], function()
{
    Route::any("/whoami", function($sub)
    {
        return "You are in the '" . $sub . "' sub-domain.";
    });
});
This was extracted from app/routes.php for brevity.
This functionality allows some pretty powerful domain-related configuration and logical branching!
Translation
Laravel 4 includes a translation system that can greatly simplify developing multisites. Translated phrases are stored in configuration files, and these can be returned in views.
Using Language Lookups
The simplest example of this requires two steps: we need to add the translated phrases and we need to recall them in a view. To begin with; we’re going to add a few English and Dutch phrases to the configuration files:
return [
    "instructions" => "Follow these steps to operate cheese:",
    "step1"        => "Cut the cheese.",
    "step2"        => "Eat the :product!",
    "product"      => "cheese"
];
This file should be saved as app/lang/en/steps.php.
return [
    "instructions" => "Volg deze stappen om kaas te bedienen:",
    "step1"        => "Snijd de kaas.",
    "step2"        => "Eet de :product!",
    "product"      => "kaas"
];
This file should be saved as app/lang/nl/steps.php.
class IndexController
extends BaseController
{
    public function indexAction()
    {
        App::setLocale("en");
        if (Input::get("lang") === "nl")
        {
            App::setLocale("nl");
        }
        return View::make("index/index");
    }
}
This file should be saved as app/controllers/IndexController.php.
This will toggle the language based on a querystring parameter. The next step is actually using the phrases in views:
@extends("layout")
@section("content")
    
        {{ Lang::get("steps.instructions") }}
    

    
        
            {{ trans("steps.step1") }}
        

        
            {{ trans("steps.step2", [
                "product" => trans("steps.product")
            ]) }}
        

    

@stop
This file should be saved as app/views/www/layout.blade.php.
The Lang::get() method gets translated phrases out of the configuration files (in this case steps.instructions). The trans() method serves as a helpful alias to this.
You may also have noticed that step2 has a strange placeholder (:product). This allows the insertion of variable data into translation phrases. We can pass these in the optional second parameter of Lang::get()/trans().
You can learn more about the Localization class at: http://laravel.com/
docs/localization.
Using Language Lookups in Packages
We’re not going to go into the details of How To Create Packages in Laravel 4, except to say that it’s possible to have package-specific translation. If you’ve set a package up, and registered its service provider in the application configuration, then you should be able to insert the following lines:
public function boot()
{
    $this->package("formativ/multisite", "multisite");
}
This was extracted from workbench/formativ/multisite/src/
Formativ/Multisite/MultisiteServiceProvider.php for brevity.
…in the service provider. Your package will probably have a different vendor/package name, and you need to pay particular attention to the second parameter (which is the alias to your package assets).
Add these translation configuration files also:
return [
    "instructions" => "Do these:"
];
This file should be saved as workbench/formativ/multisite/src/
lang/en/steps.php.
return [
    "instructions" => "Hebben deze:"
];
This file should be saved as workbench/formativ/multisite/src/
lang/nl/steps.php.
Finally, let’s adjust the view to reflect the new translation phrase’s location:

    {{ Lang::get("multisite::steps.instructions") }}
This was extracted from app/views/www/index/index.blade.php for brevity.
It’s as easy at that!
You can learn more about package resources at: http://laravel.com/
docs/packages#package-configuration.
Caching Language Lookups
Getting translated phrases from the filesystem can be an expensive operation, in a big system. What would be even cooler is if we could use Laravel 4's built-in cache system to make repeated lookups more efficient.
To do this, we need to create a few files, and change some old ones:
// 'Lang' => 'Illuminate\Support\Facades\Lang',
"Lang" => "Formativ\Multisite\Facades\Lang",
This was extracted from app/config/app.php for brevity.
This tells Laravel 4 to load our own Lang facade in place of the one that ships with Laravel 4. We’ve got to make this facade…
namespace Formativ\Multisite\Facades;
use Illuminate\Support\Facades\Facade;
class Lang
extends Facade
{
    protected static function getFacadeAccessor()
    {
        return "multisite.translator";
    }
}
This file should be saved as workbench/formativ/multisite/src/
Formativ/Multisite/Facades/Lang.php.
This is basically the same facade that ships with Laravel 4, but instead of returning translator it will return multisite.translator. We need to register this in our service provider as well:
public function register()
{
    $this->app["multisite.translator"] =
         $this->app->share(function($app)
    {
        $loader = $app["translation.loader"];
        $locale = $app["config"]["app.locale"];
        $trans  = new Translator($loader, $locale);
        return $trans;
    });
}
This was extracted from workbench/formativ/multisite/src/
Formativ/Multisite/MultisiteServiceProvider.php for brevity.
I’ve used very similar code to what can be found in vendor/laravel/
framework/src/Illuminate/Translation/TranslationServiceProvider.php. That’s because I’m still using the old file-based loading system to get the translated phrases initially. We’ll only return cached data in subsequent retrievals.
Lastly; we need to override how the translator fetches the data.
namespace Formativ\Multisite;
use Cache;
use Illuminate\Translation\Translator as Original;
class Translator
extends Original
{
    public function get($key, array $replace = array(),
        $locale = null)
    {
        $cached = Cache::remember($key, 15,
            function() use ($key, $replace, $locale)
        {
            return parent::get($key, $replace, $local
        });
        return $cached;
    }
}
This file should be saved as workbench/formativ/multisite/src/
Formativ/Multisite/Translator.php.
The process is as simple as subclassing the Translator class and caching the results of the first call to the get() method.
You can learn more about facades at: http://laravel.com/docs/facades.
Creating Multi-Language Routes
Making multi-language routes may seem needless, but link are important to search engines, and the users who have to remember them.
To make multi-language routes, we first need to create some link terms:
return [
    "cheese" => "cheese",
    "create" => "create",
    "update" => "update",
    "delete" => "delete"
];
This file should be saved as app/lang/en/routes.php.
return [
    "cheese" => "kaas",
    "create" => "creëren",
    "update" => "bijwerken",
    "delete" => "verwijderen"
];
This file should be saved as app/lang/nl/routes.php.
Next, we need to modify the app/routes.php file to dynamically create the routes:
$locales = [
    "en",
    "nl"
];
foreach ($locales as $locale)
{
    App::setLocale($locale);
    $cheese = trans("routes.cheese");
    $create = trans("routes.create");
    $update = trans("routes.update");
    $delete = trans("routes.delete");
    Route::any($cheese . "/" . $create,
        function() use ($cheese, $create)
    {
        return $cheese . "/" . $create;
    });
    Route::any($cheese . "/" . $update,
        function() use ($cheese, $update)
    {
        return $cheese . "/" . $update;
    });
    Route::any($cheese . "/" . $delete,
        function() use ($cheese, $delete)
    {
        return $cheese . "/" . $delete;
    });
}
This was extracted from app/routes.php for brevity.
We hard-code the locale names because it’s the most efficient way to return them in the routes file. Routes are determined on each application request, so we dare not do a file lookup…
What this is basically doing is looping through the locales and creating routes based on translated phrases specific to the locale that’s been set. It’s a simple, but effective, mechanism for implementing multi-language routes.
If you would like to review the registered routes (for each language), you can run the following command:
php artisan routes
You can learn more about routes at: http://laravel.com/docs/routing.
Creating Multi-Language Content
Creating multi-language content is nothing more than having a few extra database table fields to hold the language-specific data. To do this; let’s make a migration and seeder to populate our database:
use Illuminate\Database\Migrations\Migration;
class CreatePostTable
extends Migration
{
    public function up()
    {
        Schema::create("post", function($table)
        {
            $table->increments("id");
            $table->string("title_en");
            $table->string("title_nl");
            $table->text("content_en");
            $table->text("content_nl");
            $table->timestamps();
        });
    }
    public function down()
    {
        Schema::dropIfExists("post");
    }
}
This file should be saved as app/database/migrations/
0000_00_00_000000_CreatePostTable.php.
class DatabaseSeeder
extends Seeder
{
    public function run()
    {
        Eloquent::unguard();
        $this->call("PostTableSeeder");
    }
}
This file should be saved as app/database/seeds/DatabaseSeeder.php.
class PostTableSeeder
extends DatabaseSeeder
{
    public function run()
    {
        $posts = [
            [
                "title_en"   => "Cheese is the best",
                "title_nl"   => "Kaas is de beste",
                "content_en" => "Research has shown...",
                "content_nl" => "Onderzoek heeft aangetoond..."
            ]
        ];
        DB::table("post")->insert($posts);
    }
}
This file should be saved as app/database/seeds/PostTableSeeder.php.
To get all of this in the database, we need to check the settings in app/config/database.php and run the following command:
php artisan migrate --seed --env=local
This should create the post table and insert a single row into it. To access this table/row, we’ll make a model:
class Post
extends Eloquent
{
    protected $table = "post";
}
This file should be saved as app/models/Post.php.
We’ll not make a full set of views, but let’s look at what this data looks like straight out of the database. Update your IndexController to fetch the first post:
class IndexController
extends BaseController
{
    public function indexAction($sub)
    {
        App::setLocale($sub);
        return View::make("index/index", [
            "post" => Post::first()
        ]);
    }
}
This file should be saved as app/controllers/IndexController.php.
Next, update the index/index.blade.php template:

    {{ $post->title_en }}


    {{ $post->content_en }}
This was extracted from app/views/www/index/index.blade.php for brevity.
If you managed to successfully run the migrations, have confirmed you have at least one table/row in the database, and made these changes; then you should be seeing the english post content in your index/index view.
That’s fine for the English site, but what about the other languages? We don’t want to have to add additional logic to determine which fields to show. We can’t use the translation layer for this either, because the translated phrases are in the database.
The answer is to modify the Post model:
public function getTitleAttribute()
{
    $locale = App::getLocale();
    $column = "title_" . $locale;
    return $this->{$column};
}
public function getContentAttribute()
{
    $locale = App::getLocale();
    $column = "content_" . $locale;
    return $this->{$column};
}
This was extracted from app/models/Post.php for brevity.
We’ve seen these attribute accessors before. They allow us to intercept calls to $post->title and $post->content, and provide our own return values. In this case; we return the locale-specific field value. Naturally we can adjust the view use:

    {{ $post->title }}


    {{ $post->content }}
This was extracted from app/views/www/index/index.blade.php for brevity.
We can use this in all the domain-specific views, to render locale-specific database data.
Conclusion
Laravel 4 is packed with excellent tools to build massive, multi-language, multi-domain applications. In addition, it also has an excellent ORM, template language, input validator and filter system. And that’s just the tip of the iceberg!
If you found this tutorial helpful, please tell me about it @followchrisp and be sure to recommend it to PHP developers looking to Laravel 4!
This tutorial comes from a book I’m writing. If you like it and want to support future tutorials; please consider buying it. Half of all sales go to Laravel.
Laravel 4 Multisites was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.

Laravel 4 Packages

Christopher Pitt — Tue, 07 Jan 2014 09:01:43 GMT

A Comprehensive Tutorial

Laravel 4 is a huge step forward for the PHP community. It’s beautifully written, full of features and the community is presently exploding. Let’s contribute to that community by creating reusable packages, with Laravel.

I have spent two full hours getting the code out of a Markdown document and into Medium. Medium really isn’t designed for tutorials such as this, and while much effort has been spent in the pursuit of accuracy; there’s a good chance you could stumble across a curly quote in a code listing. Please make a note and I will fix where needed.

I have also uploaded this code to Github. You need simply follow the configuration instructions in this tutorial, after downloading the source code, and the application should run fine. This assumes, of course, that you know how to do that sort of thing. If not; this shouldn’t be the first place you learn about making PHP applications.

https://github.com/formativ/tutorial-laravel-4-packages

If you spot differences between this tutorial and that source code, please raise it here or as a GitHub issue. Your help is greatly appreciated.

This tutorial follows on from a previous tutorial which covered the basics of creating a deployment process for your applications. It goes into detail about creating a Laravel 4 installation; so you should be familiar with it before spending a great deal of time in this one. You’ll also find the source-code we created there to be a good basis for understanding the source code of this tutorial.

I learned the really technical bits of this tutorial from reading Taylor’s book. If you take away just one thing from this it should be to get and read it.

Composer

While the previous tutorial shows you how to create a Laravel 4 project; we need to do a bit more work in this area if we are to understand one of the fundamental ways in which packages differ from application code.

Laravel 3 had the concept of bundles; which were downloadable folders of source code. Laravel 4 extends this idea, but instead of rolling its own download process, it makes use of Composer. Composer should not only be used to create new Laravel 4 installations; but also as a means of adding packages to existing Laravel 4 applications.

Laravel 4 packages are essentially the same things as normal Composer libraries. They often utilise functionality built into the Laravel 4 framework, but this isn’t a requirement of packages in general.

It follows that the end result of our work today is a stand-alone Composer library including the various deployment tools we created last time. For now, we will be placing the package code inside our application folder to speed up iteration time.

Dependency Injection

One of the darlings of modern PHP development is Dependency Injection. PHP developers have recently grown fond of unit testing and class decoupling. I’ll explain both of these things shortly; but it’s important to know that they are greatly improved by the use of dependency injection.

Let’s look at some non-injected dependencies, and the troubles they create for us.

class Archiver
{
    protected $database;
    public function __construct()
    {
        $this->database = Database::connect(
            "host",
            "username",
            "password",
            "schema"
        );
    }
    public function archive()
    {
        $entries = $this->database->getEntries();
        foreach ($entries as $entry)
        {
            if ($entry->aggregated)
            {
                $entry->archive();
            }
        }
    }
}
$archiver = new Archiver();
$archiver->archive();
Assuming, for a moment, that Database has been defined to pull all entries in such a way that they have an aggregated property and an archive() method; this code should be straightforward to follow.
The Archiver constructor initialises a database connection and stores a reference to it within a protected property. The archive() method iterates over the entries and archives them if they are already aggregated. Easy stuff.
Not so easy to test. The problem is that testing the business logic means testing the database connection and the entry instances as well. They are dependencies to any unit test for this class.
Furthermore; the Archiver class needs to know that these things exist and how they work. It’s not enough just to know that the database instance is available or that the getEntries() method returns entries. If we have thirty classes all depending on the database; something small (like a change to the database password) becomes a nightmare.
Dependency injection takes two steps, in PHP. The first is to declare dependencies outside of classes and pass them in:
class Archiver
{
    protected $database;
    public function __construct(Database $database)
    {
        $this->database = $database;
    }
    // ...then the archive() method
}
$database = Database::connect(
    "host",
    "username",
    "password",
    "schema"
);
$archiver = new Archiver($database);
$archiver->archive();
This may seem like a small, tedious change but it immediately enables independent unit testing of the database and the Archiver class.
The second step to proper dependency injection is to abstract the dependencies in such a way that they provide a minimum of functionality. Another way of looking at it is that we want to reduce the impact of changes or the leaking of details to classes with dependencies:
interface EntryProviderInterface
{
    public function getEntries();
}
class EntryProvider implements EntryProviderInterface
{
    protected $database;
    public function __construct(Database $database)
    {
        $this->database = $database;
    }
    public function getEntries()
    {
        // ...get the entries from the database
    }
}
class Archiver
{
    protected $provider;
    public function __construct(EntryProviderInterface $provider)
    {
        $this->provider = $provider;
    }
    // ...then the archive() method
}
$database = Database::connect(
    "host",
    "username",
    "password",
    "schema"
);
$provider = new EntryProvider($database);
$archiver = new Archiver($provider);
$archiver->archive();
Woah Nelly! That’s a lot of code when compared to the first snippet; but it’s worth it. Firstly; we’re exposing so few details to the Archiver class that the entire entry dependency could be replaced in a heartbeat. This is possible because we’ve moved the database dependency out of the Archiver and into the EntryProvider.
We’re also type-hinting an interface instead of a concrete class; which lets us swap the concrete class out with anything else that implements EntryProviderInterface. The concrete class can fetch the entries from the database, or the filesystem or whatever.
We can test the EntryProvider class by swapping in a fake Database instance. We can test the Archiver class by swapping in a fake EntryProvider instance.
So, to recap the requirements for dependency injection:
Don’t create class instances in other classes (if they are dependencies) — pass them into the class from outside.
Don’t type-hint concrete classes — create interfaces.
“When you go and get things out of the refrigerator for yourself, you can cause problems. You might leave the door open, you might get something Mommy or Daddy doesn’t want you to have. You might even be looking for something we don’t even have or which has expired.
What you should be doing is stating a need, ‘I need something to drink with lunch,’ and then we will make sure you have something when you sit down to eat.” — John Munsch
You can learn more about Dependency Injection, from Taylor’s book, at: https://leanpub.com/laravel.
Inversion Of Control
Inversion of Control (IoC) is the name given to the process that involves assembling class instances (and the resolution of class instances in general) within a container or registry. Where the registry pattern involves defining class instances and then storing them in some global container; IoC involves telling the container how and where to find the instances so that they can be resolved as required.
This naturally aids dependency injection as class instances adhering to abstracted requirements can easily be resolved without first creating. To put it another way; if our classes adhere to certain requirements (via interfaces) and the IoC container can resolve them to class instances, then we don’t have to do it beforehand.
The easiest way to understand this is to look at some code:
interface DatabaseInterface
{
    // ...
}
class Database implements DatabaseInterface
{
    // ...
}

interface EntryProviderInterface
{
    // ...
}
class EntryProvider implements EntryProviderInterface
{
    protected $database;
    public function __construct(DatabaseInterface $database)
    {
        $this->database = $database;
    }
    // ...
}
interface ArchiverInterface
{
    // ...
}
class Archiver implements ArchiverInterface
{
    protected $provider;
    public function __construct(EntryProviderInterface $provider)
    {
        $this->provider = $provider;
    }
    // ...
}
$database = new Database();
$provider = new EntryProvider($database);
$archiver = new Archiver($provider);
This shallowly represents a dependency (injection) chain. The last three lines are where the problem starts to become clear; the more we abstract our dependencies, the more “bootstrapping” code needs to be done every time we need the Archiver class.
We could abstract this by using Laravel 4's IoC container:
// ...define classes
App::bind("DatabaseInterface", function() {
    return new Database();
});
App::bind("EntryProviderInterface", function() {
    return new EntryProvider(App::make("DatabaseInterface"));
});
App::bind("ArchiverInterface", function() {
    return new Archiver(App::make("EntryProviderInterface"));
});
$archiver = App::make("ArchiverInterface");
These extra nine lines (using the App::bind() and App::make() methods) tell Laravel 4 how to find/make new class instances, so we can get to the business of using them!
You can learn more about IoC container at: http://laravel.com/docs/ioc.
Service Providers
The main purpose of services providers is to collect and organise the bootstrapping requirements of your package. They’re not strictly a requirement of package development; but rather a Really Good Idea™.
There are three big things to service providers. The first is that they are registered in a common configuration array (in app/config/app.php):
'providers' => array(
 'Illuminate\Foundation\Providers\ArtisanServiceProvider',
 'Illuminate\Auth\AuthServiceProvider',
 'Illuminate\Cache\CacheServiceProvider',
 // ...
 'Illuminate\Validation\ValidationServiceProvider',
 'Illuminate\View\ViewServiceProvider',
 'Illuminate\Workbench\WorkbenchServiceProvider',
),
This was extracted from app/config/app.php for brevity.
You can also add your own service providers to this list; as many packages will recommend you do. Then there’s the register() method:
use Illuminate\Support\ServiceProvider;
class CookieServiceProvider extends ServiceProvider {
    /**
    * Register the service provider.
    *
    * @return void
    */
    public function register()
    {
        $this->app['cookie'] = $this->app->share(function($app)
        {
            $cookies = new CookieJar($app['request'], $app['encrypter']);
            $config = $app['config']['session'];
            return $cookies->setDefaultPathAndDomain($config['path'], $config['domain']);
        });
    }
}
This file should be saved as vendor/laravel/framework/src/Illuminate/
Cookie/CookieServiceProvider.php.
When we take a look at the register() method of the CookieServiceProvider class; we can see a call to $this->app->share() which is similar to theApp::bind() method but instead of creating a new class instance every time it’s resolved in the IoC container; share() wraps a callback so that it’s shared with every resolution.
The name of the register() method explains exactly what it should be used for; registering things with the IoC container (which App extends). If you need to do other bootstrapping stuff then the method you need to use is boot():
public function boot()
{
    Model::setConnectionResolver($this->app['db']);
    Model::setEventDispatcher($this->app['events']);
}
This was extracted from vendor/laravel/framework/src/Illuminate/
Database/DatabaseServiceProvider.php for brevity.
This boot() method sets two properties on the Model class. The same class also has a register method but these two settings are pet for the boot method.
You can learn more about service providers at: http://laravel.com/docs/
packages#service-providers
Organising Code
Now that we have some tools to help us create packages; we need to port our code over from being application code to being a package. Laravel 4 provides a useful method for creating some structure to our package:
php artisan workbench Formativ/Deployment
You’ll notice a new folder has been created, called workbench. Within this folder you’ll find an assortment of files arranged in a similar way to those in the vendor/laravel/framework/src/Illuminate/* folders.
We need to break all of the business logic (regarding deployment) into individual classes, making use of the IoC container and dependency injection, and make a public API.
We’re not going to spend a lot of time discussing the intricacies of the deployment classes/scripts we made in the last tutorial. Refer to it if you want more of those details.
To recap; the commands we need to abstract are:
asset:combine
asset:minify
clean
copy
distribute
environment:get
environment:remove
environment:set
watch
Many of these were cluttering up the list of commands which ship with Laravel. Our organisation should collect all of these in a common “namespace”.
The first step is to create a few contracts (interfaces) for the API we want to expose through our package:
namespace Formativ\Deployment;
interface DistributionInterface
{
    public function prepare($source, $target);
    public function sync();
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/DistributionInterface.php.
namespace Formativ\Deployment;
interface MachineInterface
{
    public function getEnvironment();
    public function setEnvironment($environment);
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/MachineInterface.php.
namespace Formativ\Deployment\Asset;
interface ManagerInterface
{
    public function add($source, $target);
    public function remove($target);
    public function combine();
    public function minify();
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Asset/ManagerInterface.php.
namespace Formativ\Deployment\Asset;
interface WatcherInterface
{
    public function watch();
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Asset/WatcherInterface.php.
The methods required by these interfaces encompass the functionality our previous commands provided for us. The next step is to fulfil these contracts with concrete class implementations:
namespace Formativ\Deployment;
use Formativ\Deployment\MachineInterface;
use Illuminate\Filesystem\Filesystem;
class Distribution implements DistributionInterface
{
    protected $files;
    protected $machine;
    public function __construct(
        Filesystem $files,
        MachineInterface $machine
    )
    {
        $this->files = $files;
        $this->machine = $machine;
    }
    public function prepare($source, $target)
    {
        // ...copy + clean files for distribution
    }
    public function sync()
    {
        // ...sync distribution files to remote server
    }
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Distribution.php.
namespace Formativ\Deployment;
use Illuminate\Filesystem\Filesystem;
class Machine implements MachineInterface
{
    protected $environment;
    protected $files;
    public function __construct(Filesystem $files)
    {
        $this->files = $files;
    }
    public function getEnvironment()
    {
        // ...get the current environment
    }
    public function setEnvironment($environment)
    {
        // ...set the current environment
    }
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Machine.php.
namespace Formativ\Deployment\Asset;
use Formativ\Deployment\MachineInterface;
use Illuminate\Filesystem\Filesystem;
class Manager implements ManagerInterface
{
    protected $files;
    protected $machine;
    protected $assets = [];
    public function __construct(
        Filesystem $files,
        MachineInterface $machine
    )
    {
        $this->files = $files;
        $this->machine = $machine;
    }   
    public function add($source, $target)
    {
        // ...add files to $assets
    }
    public function remove($target)
    {
        // ...remove files from $assets
    }
    public function combine()
    {
        // ...combine assets
    }
    public function minify()
    {
        // ...minify assets
    }
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Asset/Manager.php.
namespace Formativ\Deployment\Asset;
use Formativ\Deployment\MachineInterface;
use Illuminate\Filesystem\Filesystem;
class Watcher implements WatcherInterface
{
    protected $files;
    protected $machine;
    public function __construct(
        Filesystem $files,
        MachineInterface  $machine
    )
    {
        $this->files = $files;
        $this->machine = $machine;
    }
    public function watch()
    {
        // ...watch assets for changes
    }
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Asset/Watcher.php.
The main to note about these implementations is that they use dependency injection instead of creating class instances in their constructors. As I pointed out before; we’re not going to go over the actually implementation code, but feel free to port it over from the application-based commands.
As you can probably tell; I’ve combined related functionality into four main classes. This becomes even more apparent when you consider what the service provider has become:
namespace Formativ\Deployment;
use App;
use Illuminate\Support\ServiceProvider;
class DeploymentServiceProvider
extends ServiceProvider
{
    protected $defer = true;
    public function register()
    {
        App::bind("deployment.asset.manager", function()
        {
            return new Asset\Manager(
                App::make("files"),
                App::make("deployment.machine")
            );
        });
        App::bind("deployment.asset.watcher", function()
        {
            return new Asset\Watcher(
                App::make("files"),
                App::make("deployment.machine")
            );
        });
        App::bind("deployment.distribution", function()
        {
            return new Distribution(
                App::make("files"),
                App::make("deployment.machine")
            );
        });
        App::bind("deployment.machine", function()
        {
            return new Machine(
                App::make("files")
            );
        });
        App::bind("deployment.command.asset.combine", function()
        {
            return new Command\Asset\Combine(
                App::make("deployment.asset.manager")
            );
        });
        App::bind("deployment.command.asset.minify", function()
        {
            return new Command\Asset\Minify(
                App::make("deployment.asset.manager")
            );
        });
        App::bind("deployment.command.asset.watch", function()
        {
            return new Command\Asset\Watch(
                App::make("deployment.asset.manager")
            );
        });
        App::bind("deployment.command.distribute.prepare", function()
        {
            return new Command\Distribute\Prepare(
                App::make("deployment.distribution")
            );
        });
        App::bind("deployment.command.distribute.sync", function()
        {
            return new Command\Distribute\Sync(
                App::make("deployment.distribution")
            );
        });
        App::bind("deployment.command.machine.add", function()
        {
            return new Command\Machine\Add(
                App::make("deployment.machine")
            );
        });
        App::bind("deployment.command.machine.remove", function()
        {
            return new Command\Machine\Remove(
                App::make("deployment.machine")
            );
        });
        $this->commands(
            "deployment.command.asset.combine",
            "deployment.command.asset.minify",
            "deployment.command.asset.watch",
            "deployment.command.distribute.prepare",
            "deployment.command.distribute.sync",
            "deployment.command.machine.add",
            "deployment.command.machine.remove"
        );
    }
    public function boot()
    {
        $this->package("formativ/deployment");
        include __DIR__ . "/../../helpers.php";
        include __DIR__ . "/../../macros.php";
    }
    public function provides()
    {
        return [
            "deployment.asset.manager",
            "deployment.asset.watcher",
            "deployment.distribution",
            "deployment.machine",
            "deployment.command.asset.combine",
            "deployment.command.asset.minify",
            "deployment.command.asset.watch",
            "deployment.command.distribute.prepare",
            "deployment.command.distribute.sync",
            "deployment.command.machine.add",
            "deployment.command.machine.remove"
       ];
    }
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/DeploymentServiceProvider.php.
I’ve folded the copy() and clean() methods into a single prepare() method.
The first four bind() calls bind our four main classes to the IoC container. The remaining bind() methods bind the artisan commands we still have to create (to replace those we make last time).
There’s also a call to $this->commands(); which registers commands (bound to the IoC container) with artisan. Finally; we define the provides() method, which coincides with the $defer = true property, to inform Laravel which IoC container bindings are returned by this service provider. By setting $defer = true; we’re instructing Laravel to not immediately load the provided classes and commands, but rather wait until they are required.
namespace Formativ\Deployment\Command\Asset;
use Formativ\Deployment\Asset\ManagerInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Combine
extends Command
{
    protected $name = "deployment:asset:combine";
    protected $description = "Combines multiple resource files.";
    public function __construct(ManagerInterface $manager)
    {
        parent::__construct();
        $this->manager = $manager;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Asset/Combine.php.
namespace Formativ\Deployment\Command\Asset;
use Formativ\Deployment\Asset\ManagerInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Minify
extends Command
{
    protected $name = "deployment:asset:minify";
    protected $description = "Minifies multiple resource files.";
    public function __construct(ManagerInterface $manager)
    {
        parent::__construct();
        $this->manager = $manager;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Asset/Minify.php.
namespace Formativ\Deployment\Command\Asset;
use Formativ\Deployment\Asset\ManagerInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Watch
extends Command
{
    protected $name = "deployment:asset:watch";
    protected $description = "Watches files for changes.";
    public function __construct(ManagerInterface $manager)
    {
       parent::__construct();
       $this->manager = $manager;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Asset/Watch.php.
namespace Formativ\Deployment\Command\Distribute;
use Formativ\Deployment\DistributionInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Prepare
extends Command
{
    protected $name = "deployment:distribute:prepare";
    protected $description = "Prepares the distribution folder.";
    protected $distribution;
    public function __construct(
        DistributionInterface $distribution
    )
    {
        parent::__construct();
        $this->distribution = $distribution;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Distribute/Prepare.php.
namespace Formativ\Deployment\Command\Distribute;
use Formativ\Deployment\DistributionInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Sync
extends Command
{
    protected $name = "deployment:distribute:sync";
    protected $description = "Syncs changes to a target.";
    protected $distribution;
    public function __construct(
        DistributionInterface $distribution
    )
    {
        parent::__construct();
        $this->distribution = $distribution;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Distribute/Sync.php.
namespace Formativ\Deployment\Command\Machine;
use Formativ\Deployment\MachineInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Add
extends Command
{
    protected $name = "deployment:machine:add";
    protected $description = "Adds the current machine to an environment.";
    protected $machine;
    public function __construct(MachineInterface $machine)
    {
        parent::__construct();
        $this->machine = $machine;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Machine/Add.php.
namespace Formativ\Deployment\Command\Machine;
use Formativ\Deployment\MachineInterface;
use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;
class Remove
extends Command
{
    protected $name = "deployment:machine:remove";
    protected $description = "Removes the current machine from an environment.";
    protected $machine;
    public function __construct(MachineInterface $machine)
    {
        parent::__construct();
        $this->machine = $machine;
    }
    // ...
}
This file should be saved as workbench/formativ/deployment/src/
Formativ/Deployment/Command/Machine/Remove.php.
I’ve also omitted the fire() method from the new commands; consider it an exercise to add these in yourself.
Now, when we run the artisan list command; we should see all of our new package commands neatly grouped. Feel free to remove the old commands, after you’ve ported their functionality over to the new ones.
Publishing Configuration Files
Often you’ll want to add new configuration files to the collection which ship with new Laravel applications. There’s an artisan command to help with this:
php artisan config:publish formativ/deployment --path=
workbench/Formativ/Deployment/src/config
This should copy the package configuration files into the app/config/packages/formativ/deployment directory.
Since we have access to a whole new kind of configuration; we no longer need to override the configuration files for things like environment. As long as our helpers/macros use the package configuration files instead of the the default ones; we can leave the underlying Laravel 4 application structure (and bootstrapping code) untouched.
Creating Composer.json
Before we can publish our package, so that others can use it in their applications; we need to add a few things to the composer.json file that the workbench command created for us:
{
    "name"        : "formativ/deployment",
    "description" : "All sorts of cool things with deployment.",
    "authors"     : [
        {
            "name"  : "Christopher Pitt",
            "email" : "cgpitt@gmail.com"
        }
    ],
    "require" : {
        "php"                : ">=5.4.0",
        "illuminate/support" : "4.0.x"
    },
    "autoload" : {
        "psr-0" : {
            "Formativ\\Deployment" : "src/"
        }
    },
    "minimum-stability" : "dev"
}
This file should be saved as workbench/formativ/deployment/
composer.json.
I’ve added a description, my name and email address. I also cleaned up the formatting a bit; but that’s not really a requirement. I’ve also set the minimum PHP version to 5.4.0 as we’re using things like short array syntax in our package.
You should also create a readme.md file, which contains installation instructions, usage instructions, license and contribution information. I can’t understate the import ants of these things — they are your only hope to attract contributors.
You can learn more about the composer.json file at: http://getcomposer.org/doc/01-basic-usage.md
#composer-json-project-setup.
Submitting A Package To Packagist
To get others using your packages; you need to submit them to packagist.org. Go to http://packagist.org and sign in. If you haven’t already got an account, you should create it and link to your GitHub account.
You’ll find a big “Submit Package” button on the home page. Click it and paste the URL to your GitHub repository in the text field. Submit the form and you should be good to go.
You can learn more about package development at: http://laravel.com/
docs/packages.
Note On Testing
Those of you who already know about unit testing will doubtlessly wonder where the section on testing is. I ran short on time for that in this tutorial, but it will be the subject of a future tutorial; which will demonstrate the benefits of dependency injection as it relates to unit testing.
Conclusion
Laravel 4 is packed with excellent tools to enable secure deployment. In addition, it also has an excellent ORM, template language, input validator and filter system. And that’s just the tip of the iceberg!
If you found this tutorial helpful, please tell me about it @followchrisp and be sure to recommend it to PHP developers looking to Laravel 4!
This tutorial comes from a book I’m writing. If you like it and want to support future tutorials; please consider buying it. Half of all sales go to Laravel.
Laravel 4 Packages was originally published in Laravel 4 Tutorials on Medium, where people are continuing the conversation by highlighting and responding to this story.