PHP

Building a Micro Markdown API App with Lumen

Younes Rafie
Share

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.

Lumen Header

Why Lumen?

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.

Installation

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.

Folder Structure

The first thing that you’ll notice after installing Lumen is the folder structure. A lot of things are stripped out, like the config, database and 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 Laravel\Lumen\Console\Commands\MakeCommand class.

  • php artisan make foundation: scaffold the resources and database folders.
  • php artisan make resources: scaffold the resources folder.
  • php artisan make database: scaffold the database folder.
  • php artisan make lang: scaffold the resources/lang folder.
  • php artisan make views: scaffold the resources/views folder.

Parsing Markdown

// app/Http/routes.php

$app->get('/parse', 'App\Http\Controllers\MarkdownController@parse');
// app/Http/Controllers/MarkdownController.php

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).

HTML result

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.

// bootstrap/app.php

$app->withFacades();
$app->withEloquent();
$app->middleware([
    //...
]);

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 .env file.

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')]
])->json();
$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.

Conclusion

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?