Building a Laravel Translation Package – The Database Driver


December 14th, 2018

Building a Laravel Translation Package – The Database Driver

In the previous article of the series, we talked about how to handle missing translations, which brings us very close to making the package feature complete. To finish up the build phase of this series, we will discuss how we go about adding a database driver.

Signing the contract

As, you may recall from earlier in the series we used an interface to define all the methods the file deriver needed to implement to function. The main reason for doing that was it was always on the package roadmap to be able to support multiple drivers. Defining an interface meant we had a contract on which all new drivers could rely to provide the required functionality.


To kick off the database driver, we’ll need some database tables in which to store our translations. This doesn’t need to be too complex – a table to store languages and another to store the translations is sufficient.

1// languages table
2public function up()
4 Schema::create(config('translation.database.languages_table'), function (Blueprint $table) {
5 $table->increments('id');
6 $table->string('name')->nullable();
7 $table->string('language');
8 $table->timestamps();
9 });
12// translations table
13public function up()
15 Schema::create(config('translation.database.translations_table'), function (Blueprint $table) {
16 $table->increments('id');
17 $table->unsignedInteger('language_id');
18 $table->foreign('language_id')->references('id')->on(config('translation.database.languages_table'));
19 $table->string('group')->nullable();
20 $table->text('key');
21 $table->text('value')->nullable();
22 $table->timestamps();
23 });

We use the package configuration to decide the names of the tables in the migration. This allows users of the package to name their own and avoid any potential conflicts.

It’s also worth pointing out the presence of the language_id foreign key on the translations table. This tells us which language each translation belongs to.

There is also a nullable field called group which will be used to track whether it’s a single or group translation.

Finally, there are fields for key and value which, as the names suggest, store the key and value of each translation.

In order for the migrations to be automatically run when our users run php artisan migrate, we need to load them in our service provider by using the loadMigrationsFrom method and passing in the path to the newly created migrations.

1public function boot()
3 $this->loadMigrationsFrom(__DIR__.'/../database/migrations');


Our models can also be kept relatively simple. Given that we are allowing users to define their own table names, each model will need to explicitly define its associated table. We can do this in the constructor of the model by assigning the value that’s set in the configuration.

1public function __construct(array $attributes = [])
3 parent::__construct($attributes);
4 $this->table = config('translation.database.languages_table');

Finally, each table will need to define its relation to the other:

3class Langauge extends Model
5 ...
7 public function translations()
8 {
9 return $this->hasMany(Translation::class);
10 }
3class Translation extends Model
5 ...
7 public function language()
8 {
9 return $this->belongsTo(Language::class);
10 }

Wiring Up the Driver

With the migrations and models defined, we are now in a position to start building out the database driver implementation. To do this, we will create a new class called Database and implement the driver interface. We’ll also extend the Translation abstract class which contains some methods common to all driver implementations.

1class Database extends Translation implements DriverInterface
3 ...

Now it is just a case of building out the required methods. For this, we will lean quite heavily on Eloquent. I have documented some of the more interesting methods below, but if you are interested in seeing the full implementation, you can check it out on GitHub.

1public function allLanguages()
3 return Language::all()->mapWithKeys(function ($language) {
4 return [$language->language => $language->name ?: $language->language];
5 });
8// $this->allLanguages();
10// [
11// ‘en’ => ‘en’,
12// ‘fr’ => ‘fr’,
13// ‘es’ => ‘es’,
14// ];

Here, we use Eloquent to get all the languages from the database and map over each to return the languages in the same format as the file driver.

1public function getGroupTranslationsFor($language)
3 $translations = $this->getLanguage($language)
4 ->translations()
5 ->whereNotNull('group')
6 ->where('group', 'not like', '%single')
7 ->get()
8 ->groupBy('group');
10 return $translations->map(function ($translations) {
11 return $translations->mapWithKeys(function ($translation) {
12 return [$translation->key => $translation->value];
13 });
14 });
17// $this->getGroupTranslationsFor('en');
19// [
20// ‘auth’ => [
21// ‘failed’ => ‘These credentials do not match our records’,
22// ],
23// ]

Here, we are returning all the group translations for a given language. We do this by using eloquent to get all the translations for said language where the group field doesn’t include single. We then map over the Eloquent collection to return the results in the correct format.

1public function addGroupTranslation($language, $key, $value = '')
3 list($group, $key) = explode('.', $key);
5 Language::where('language', $language)
6 ->first()
7 ->translations()
8 ->updateOrCreate([
9 'group' => $group,
10 'key' => $key,
11 ], [
12 'group' => $group,
13 'key' => $key,
14 'value' => $value,
15 ]);

Here, we explode the key on the period to get the group and the key for the translation. Then we use Eloquent’s updateOrCreate method to determine if the translation already exists. If it does, we update it in case the value has changed. If not, we create a new translation for that language.

Using the Driver

In order to tell Laravel which driver to instantiate, we will create a new TranslationManager class which uses the package configuration to determine which driver to return.

1public function resolve()
3 $driver = $this->config['driver'];
4 $driverResolver = studly_case($driver);
5 $method = "resolve{$driverResolver}Driver";
7 return $this->{$method}();
10protected function resolveFileDriver()
12 return new File(...);
15protected function resolveDatabaseDriver()
17 return new Database(...);

Here, we take the driver value defined in the configuration file, turn that into a method which is responsible for understanding how to instantiate the driver and return it. Doing it this way means adding new drivers in the future will be a much easier task. As an example, if we were to add a new driver defined as cloud in the configuration, we would add a method called resolveCloudDriver to the TranslationManager which return a new instance of that driver.

Now, in the register method of our service provider, we can bind the translation driver as a singleton to the container. This means any time we grab it from the container, the same instance will be returned.

1use JoeDixon\Translation\Drivers\Translation;
5$this->app->singleton(Translation::class, function ($app) {
6 return (new TranslationManager($app, $app['config']['translation'], $app->make(Scanner::class)))->resolve();

You may notice the class we are actually binding is the abstract Translation class. This is possible because all of our drivers extend this class. It’s useful because it means no matter which driver is instantiated, it can be obtained from the container in the same way.

With this driver in place, our package is nearly ready to be released to the world. In the next article of the series, we’ll talk about documentation and what is needed to help get your users up and running.

As usual, if you have any questions in the mean time, feel free to reach out on Twitter.

Filed in:

Joe Dixon

Founder and CTO of ubisend. Proud Father to two tiny heroes, Husband, developer, occasional globetrotter.