Lumen is a brand spanking new PHP micro-framework developed by the author of the Laravel framework, Taylor Otwell. Don't stress, though—Lumen is not meant to replace Laravel. In fact, the idea behind Lumen is that it complements your existing or future Laravel applications.

Taylor Otwell developed Lumen with some very specific purposes in mind, namely, microservices and APIs. Just briefly, a microservice is a smaller, decoupled process that communicates with a larger application, e.g. our Laravel application.

In this article I want to go over what's different in Lumen, when we should use Lumen, and how we can use Lumen. I'll also explain how we can take our Lumen application and easily migrate it to a full-stack Laravel application. There won't be a whole lot of code, as Lumen is much the same as Laravel. Let's get started.

So What's New?

This will most likely be the first question that many of you will be asking. In reality, not a whole lot is actually "new" with Lumen aside from the glue. Lumen still utilizes most of the Illuminate components that make up the Laravel framework (there are only a couple missing). Think of it as a slimmed down Laravel installation. 

Its goal is to maximize performance, and to get this increase in performance, several things have been changed. The most important of these are the following:

1. Less configuration. Much of Lumen comes pre-configured. In fact, you'll find that there's no config directory in a Lumen install. Instead, you'll utilize the .env files to configure most of your application.
2. Different router. This is probably the biggest difference and the reason why it can be as fast as it is. Lumen doesn't utilize the Symfony router like its big brother Laravel. Instead, Lumen uses FastRoute, a lightweight routing implementation developed by Nikita Popov.

There are a few trade-offs here. FastRoute is a very fast implementation, but it's not as feature-packed as the Symfony router. If you want to use sub-domain routing then you'll have to stick with a Laravel install which uses the Symfony router. 

The other trade-off worth mentioning is that for finer control over configuration of certain components you'll need to modify configuration files within the vendor/laravel/lumen-framework directory. The majority of the configuration can be done through the .env files, but some lesser configured things aren't directly configurable.

Should I Switch to Lumen Right Now?

The answer here will depend, but probably not. If you're developing or have developed an application on Laravel (4 or 5), then you probably won't need to switch to Lumen right this very minute. While Lumen is capable of developing a full-blown web application, it is better suited to the smaller, decoupled services and APIs.

So When Can I Use It?

I can't tell you when you can and can't use a framework that's available to you. I will, however, make some recommendations on when you might consider using Lumen for a part of your next project.

Let's say you're building a large web shop application. So you go ahead and install Laravel and get to work on a monolithic application. Now, there's nothing wrong with this approach, and you may find it works fine for you. If so, carry on. If you find you're becoming overwhelmed with the complexity, or things seem to be getting a little out of hand, then you may want to split it up into some smaller, more manageable pieces.

You would use Lumen to create separate applications for each decoupled service. For our shop we might split off the billing, e-mail notifications, shipping, and tracking to separate applications. Each of these applications would be a self-contained Lumen install and each application would only do a specific task. 

To enable our main application to communicate with our decoupled services, we'd make use of queues and a service like Amazon SQS. We can use queues to easily queue up jobs, and each service would listen for its particular jobs and process them as they're queued. The benefit to this approach is that each service can be scaled and deployed independently of one another. 

You could also use Lumen to build an API which could also be consumed by your main application with the help of an HTTP client such as Guzzle. This decoupling allows you to scale and optimize the business side of your application without interfering with the rest.

Okay, How Do I Use It?

By now you should have a good idea as to whether or not using Lumen is the right step for you. Installing Lumen is as easy as installing Laravel: a simple composer create-project command, or you can install the lumen command to create new projects. We'll just use Composer to grab a fresh install.

composer create-project laravel/lumen LumenProject --prefer-dist

Composer will pull down all the dependencies. You can use Artisan to quickly serve up the application to take a look, or you can set up a Virtual Host or Homestead site. Either way, once you hit the path to your Lumen installation you'll see the shiny splash page informing you that Lumen is good to go.

Configuration is all done in the .env files, so you'll either want to rename the .env.example file or copy its contents into a new file.

The remaining bootstrapping that you'll want to be aware of is in the bootstrap/app.php file. If you're using the .env configuration mentioned above then you'll want to uncomment Dotenv::load(__DIR__.'/../');. Scrolling through this file you'll see several commented lines that you may want to uncomment. There's the loading of facades, Eloquent, some middlewares, and the registration of other service providers.

You've now got yourself a freshly installed and configured copy of Lumen ready to build something amazing.

But Wait, I Need Laravel Now!

You might be building your Lumen application and everything is going absolutely fine, until one fateful day when you realise you need something that only the full-stack Laravel framework offers. Don't stress, though, as it's an extremely painless upgrade. Here are the steps to follow:

1. Install a fresh copy of Laravel 5.
2. Copy across your app directory. Be aware that you may need some things from the L5 app directory, such as the providers.
3. Copy across your configuration to the appropriate file in the config directory.
4. Copy across any custom bootstrapping.
5. Fix some routes. Because Lumen uses FastRoute, you'll probably need to tweak some of your routes so that they're compatible with the Symfony router.

That should be the bulk of what you need to copy in order to migrate your Lumen application to Laravel. Of course, this works both ways, so you can easily migrate a Laravel application to Lumen if you realize you don't need everything the full-stack framework offers.

Conclusion

To wrap this up, I just want to point out that I'm advocating the use of Lumen primarily for decoupled services and APIs, which is its intended use. That's not to say you can't build an entire application on Lumen, because you can. If you choose to do it, that's fine. There aren't any rules carved in a stone tablet telling you what you can and can't use for your projects. At the end of the day the decision is left up to you. Weigh your options, plan your project, decide what you'll need, consult your team, and then make your final decision.