Building a Laravel Translation Package – Scaffolding

In Part 1, we introduced that this series would cover the process of building and maintaining an open-source package for Laravel. Check it out for an overview of what we’ll create in this series. Next, we are going to get to work on scaffolding a new Laravel package.

Scaffolding the Package

The first thing you need to do when creating a PHP package of any kind is setting up the repository, and most importantly the composer file. There’s no de-facto standard approach to organizing Composer packages; however, I will walk you through my approach.

I tend to start by installing a fresh version on Laravel using the installer. Using a test Laravel installation gives me a shiny new playground in which to work.

In the root of my newly installed Laravel project, I create a directory called packages. Within this directory, I create a directory structure for my package which aligns with the GitHub repository where the code will ultimately reside – in this case, joedixon/laravel-translation.

From within the package directory, I run git init to set up version control. Next, I run composer init and follow the instructions which create my composer.json file for managing any dependencies I may require and for later submission to Packagist.

Next, I create an src directory at the root of my package which will contain all of the domain specific logic of the package.

In the composer.json file, I add the following PSR-4 configuration to tell Composer how to autoload my package namespace:

"autoload": {
    "psr-4": {
        "JoeDixon\\Translation\\": "src"
    }
},

Finally, before I write a single line of code, I amend the composer.json file at the root of the Laravel application to tell it how to load my app.

"require": {
    …
    "joedixon/laravel-translation": "dev-master"
},
"repositories": [
    {
        "type": "path",
        "url": "./packages/joedixon/laravel-translation",
        "options": {
            "symlink": true
        }
    }
]

Hopefully, the require section will look familiar to you. The repositories section, however, may not.

The repositories section tells Composer to symlink the package from the local installation. Using this approach allows us to work on and test the package locally without having to composer update anytime something changes.

When using the local file path approach, it’s worth noting the package can be anywhere on your machine; however, I like to keep it contained within the application structure for development.

Now that the package has been bootstrapped and autoload configured, we can start writing some code.

Package structure

When building a package, I try to mirror the Laravel application structure as much as possible. As such, everything typically found in my app directory such as controllers, console commands, event listeners, etc. go into my package src directory and things such as routes and resources live at the root of the package.

Service Provider

For Laravel to start using the package, we need to build a service provider. The service provider class is where we will bootstrap the package by performing actions such as binding services to the container, registering routes, publishing configuration, and just about anything else you can imagine that need tying into the Laravel app!

Tip
Typically, I will run php artisan make:provider TranslationServiceProvider which will scaffold a service provider in the Providers directory of the Laravel application. I then move it to my package and update the namespace accordingly.

At this stage, I will register things like routes, config, views, and translations without necessarily fleshing out all of the details. I find doing it in this way makes things faster later on in development.

Testing

No good package would be complete without tests.

Setting up tests in a package can be quite tricky; mainly if you want to be able to access Laravel’s testing helpers. Fortunately, the orchestra/testbench package makes it possible to use all of Laravel’s native test helpers within your packages tests.

Run composer require --dev orchestra/testbench to install it as a development dependency. Running Composer should give you the following configuration in the composer.json file:

"require-dev": {
    "orchestra/testbench": "~3.0"
}

Before we’re done, let’s commit what we have to the master branch:

# within ./packages/joedixon/laravel-translation
echo "vendor/" >> .gitignore
git add .
git commit -m"Initial Commit"

That just about wraps up the package scaffolding. Next time, we’ll start building out some package functionality, starting by building out the file based translation driver.