How to set up Lumen with Doctrine
Hey! In this post I’d like to show how to set up simple lumen-based CRUD API which uses Doctrine as ORM.
Lumen is micro-framework built on Laravel
Out of box Laravel and Lumen use Eloquent ORM which implements Active Record pattern. Simply, Active Record is pattern which represents particular row in the database as a single instance of the particular model class.
Let’s say we have some table in our database called ‘posts’ which has only three fields: id, title and body. Using Eloquent in this case we have to create our model called Post
As you can see we have to inherit Eloquent model. Basically this might be all the set up for our model. Then we create an instance of our first post:
I deliberately omitted the migration stuff since it’s not the point of this article. So you might ask how the heck we use all of the methods and fields if we didn’t set them up at all? All the magic is done by Eloquent as long as we extend basic model class. And here is another interesting thing.
However Eloquent is quite simple to use and might be useful in case you want to create simple prototype application quickly it completely breaks the S (Single Responsibility principle) in SOLID:
Keep in mind that every model you’ve created has methods for:
- creating, updating, deleting and fetching records from DB
- SQL query methods: select, where etc
- paginators
- sorting and filtering collections of objects
- scopes which breaks autocompletion
To avoid such a mess it’s a good point to use Doctrine ORM. Open-source enthusiasts are already done some good things and delivered a good package for laravel: https://www.laraveldoctrine.org/
So let’s get started:
Install Lumen app
composer create-project — prefer-dist laravel/lumen lumen-blog
Run lumen app
php -S localhost:8000 -t public
Create .env file by running
cp .env.example .env
Set up your local database connection and add credentials to .env file. In my case it looks like this:
Now we can set up doctrine
First of all install composer package:
composer require "laravel-doctrine/orm:1.4.*"
Open bootstrap/app.php file and register Doctrine Service Provider:
Next create config/database.php file and add paste this code to it:
I assume you’re using mysql, if you’re not, feel free to change your driver to postgres or whatever.
Don’t forget to .env file for your lumen app and provide database credentials
Next we want to add config/doctrine.php
Now the most interesting part!
Let’s create our post model which in Doctrine world should be called an entity.
Inside the lumen-blog/app/ create folder called Entities and inside it create Post.php file.
The basic set up for it should look like this:
Note that we don’t need to inherit any kind of classes to get our model working.
Let’s add the fields for this entity:
As you can see we explicitly defined all of the fields of our database table. However that’s not enough to get it working. This is the place where we are ready to add doctrine and let it know what DB table should be used with this entity:
Next let’s tell Doctrine what it should do with our fields:
Almost done. The last thing is to add constructor along with getters and setter to be able to (obviously :) ) get and set values for our posts.
Good job! Our entity is ready to be used.
Let’s create our PostController.php inside lumen-blog/app/Http/Controllers:
We want to create our first post so let’s first of all create the action for it:
I didn’t add the validation just for the simplicity of example, I’ll cover this topic next time.
As you can see here we use Entity Manager to save our post. Basically Entity Manager is an implementation of the data mapper which keeps the in-memory representation of a persistent data store (relational database in our case)
The last but not least is to create a route for this action
Navigate to lumen-blog/routes/web.php and add this code:
Now the last thing you need to do before hitting the database is to create posts table. Inside the lumen-blog folder run:
php artisan doctrine:schema:create
You’re all set. Get the postman or some other software for testing REST apis and create your first post.
Now we want to fetch the entire list of our posts.
Let’s add a new route for it:
And of course a new action in our controller
This will fetch the list of all posts however won’t output it. We need also to transform the list of Post entities to an appropriate JSON format. To do it we need to create some kind of a transformer. Let’s go to lumen-blog/app and create Transformers folder inside of which create PostTransformer.php file
Note! In the next series we will use more transformers for other entities and we don’t want to define transformAll method in each of them. Just to simplify understanding the material this implementation will do.
So let’s add our transformer and finally get the output:
go to postman and call GET http://localhost:8000/posts
You’ll get the list of your posts
Next we want to fetch a particular post. Pretty simple.
adding a route:
adding an action:
go to postman and call GET http://localhost:8000/post/1
You’ll get the post with id = 1
Next we probably want to update the post
Let’s add the route. To update existing post we need to use PUT method:
Adding an action:
Just to make sure we won’t mess everything up let’s update setters in our Post entity:
Test that out:
PUT http://localhost:8000/post/1
And finally we want to be able to delete our posts
A route:
An action:
Alright then. I guess we’ve done a great job of understanding basics of Doctrine ORM and how to use it with Lumen (or Laravel). Hope you liked it. Next time I will show you how you can build the authorization with JWT and Doctrine. Feel free to reach out if you have any questions. Thanks!
