If you’ve been using Laravel for a while, you know that it sometimes feels a little heavy for a small application or service. For that same purpose, Taylor, the creator of Laravel built Lumen. A small micro-framework built on top of Laravel Illuminate components, it doesn’t load all the components by default like Eloquent, Blade, Middleware, etc, remaining light as it boots up. We will explore all of that this short tutorial.
If you’re already a Laravel user, you may be in love with Laravel’s syntax and shortcuts. But, when working on just a small application, you don’t want to have a full stack framework with all the packages wired up. Lumen provides a good starting point for your small application, stripping out all the parts that you probably won’t need.
What We’re Building
To illustrate a practical use case for the micro framework, we will be creating a Markdown parser API application where the user can submit a Markdown text and get back the parsed content as JSON. I will be using the league/commonmark package from the PHP League. You can check the final result on Github.
If you’re creating new applications often, you can use the global installer (
composer global require "laravel/lumen-installer=~1.0") and take advantage of short syntax like
lumen new my-project, or you can use composer to create a new project with
composer create-project laravel/lumen my-project --prefer-dist. You can read more about the installation process in the documentation.
After Lumen is installed, you can go ahead and require the
commonmark package using
composer require league/commonmark. Visit the documentation for more info about it.
The first thing that you’ll notice after installing Lumen is the folder structure. A lot of things are stripped out, like the
resources folders, which can be brought back when necessary using some scaffolding commands, or manually.
Lumen provides you with the
php artisan make command to help you scaffold the missing folders. If you want to work with view templates, you can run
php artisan make views to create the
resources/views folder for your templates. The available commands can be found in the
php artisan make foundation: scaffold the
php artisan make resources: scaffold the
php artisan make database: scaffold the
php artisan make lang: scaffold the
php artisan make views: scaffold the
public function parse(Request $request, CommonMarkConverter $parser)
$text = $request->get('text');
$result = $parser->convertToHtml($text);
return ['html' => $result];
After the user submits the Markdown text to our
/parse endpoint, we will retrieve the content from the request object and parse it. You noticed that we took advantage of the service container type hinting to resolve the markdown and request objects. If you decide to use Facades (
Request::get('text')), just make sure to tell your application to load them (see next section).
Facades, Eloquent and Middleware
Because Facades, Eloquent ORM and Middleware are commonly used in Laravel applications, we have them added by default inside our
bootstrap/app.php file and we only need to uncomment them before starting to use them.
If your application needs to include other services, you can use the
$app->register('AppServiceProvider'); syntax to register the list of providers.
Generally speaking, most of the Lumen parts work the same as in Laravel, they are either not loaded by default or need to be installed and wired into the application. For example, you can use the Laravel FileSystem package as usual (
Storage::disk('local')->put('file.txt', 'Content here');) and it will work as expected. However, if you want to work with Rackspace, you need to pull the
league/flysystem-rackspace package using Composer and specify your credentials inside the
Using the API
After our service is up and running, we can consume our API using Guzzle or any other package or method you prefer.
$client = new GuzzleHttp\Client();
$response = $client->get('http://vaprobash.dev/parse', [
'query' => ['text' => file_get_contents('myFile.md')]
$html = $response->html;
If a part of your service is getting a lot of traffic, it makes sense to have light micro-framework to handle this part of the application without having to load all the domain login and packages to complete a simple task.
Lumen will bring back some Laravel fans who don’t like to use the full framework for small tasks. You can check the documentation for more information. If you’ve already tried Lumen, I would love to know your first impressions of it, and about the advantages you think it has over the other micro frameworks?