How to create a custom Laravel package of a PWA starter kit

Hire the author: Obua E

Image source https://i.ytimg.com/vi/ivrc1ZKFgHI/maxresdefault.jpg

Introduction

Packages are a great way to make a bunch of code reusable and easy to share. They’re the primary way to add functionality to a Laravel application, for example generating PWA files.

PWA is a website that looks and behaves like a mobile app. PWAs are designed to take advantage of native mobile device features and help people avoid app stores.

You may have already come across many Laravel packages, both official and community-maintained.
There are different types of packages.

Some packages are standalone, meaning they can be used with any PHP framework, while others are specific to Laravel.

These packages may have routes, controllers, views, and configurations specifically designed to enhance your Laravel application.

Any of these packages may be used with Laravel by requiring them in your composer.json file

Note: This guide primarily covers the development of a package that is Laravel specific.

Throughout this article, we’ll demonstrate how to build a package for publishing essential files to a Laravel application-specific directory to make a PWA starter kit.

Glossary

1. PWA. This stands for a progressive web application.
2. Docs. Here Docs stands for documentation
3. PHP. This stands for Hypertext Preprocessor which is a programming language.
4. App. This stands for application.
5. SW. Represents a service worker.
6. API. An API in full is an Application Programming Interface.
   • It is a set of operations of a software component (i.e., a system, a sub-system, class, or a function) provides to its clients.
7. PSR-4. It describes a specification for autoloading classes from file paths in a composer.

Step-by-step procedure

Step 1: Initialize a new package using composer.

To get a new Laravel custom package off the ground, cd into the base directory (ld-laravel-pwa in my case) and execute the composer init command.

This will begin the package initialization process. Make sure to write the package name and description properly.

After that, you can press enter and accept the default for all the options, except when it asks whether you’d like to add your dependencies and dev-dependencies interactively or not, for those two prompts, write n and hit enter to answer in negative.

Step 2: Update composer.json file content with necessary sections required for the package

Once the package has been initialized, you’ll find a new vendor directory and composer.json file inside your base directory. Open the composer.json file but (keep in mind, this composer.json file is separate from your project composer.json file) in your code editor of choice and look for the require {} section.

This is where you’ll have to enlist any other package that your package depends on. Well in this one, you’ll need the php v5.6 and above, and illuminate/support v5.4 and above Laravel package for reusable Laravel components. So, update the require {} section as follows:

Also, add the autoload and extra sections of the composer.json file to load the prs-4 namespace and package autodiscovery, respectively, as shown below.

The final composer should look similar to this, with other values customized as you see fit.

Step 3: Add a .gitignore file to specifically ignore unwanted files and folders from git i.e vendor folder

Step 4: Create a src folder that holds all the logic for the package with the following folders and files listed below.

1. PwaServiceProvider.php. This shall register for us an artisan command that we shall run to publish the assets from the stubs template.
2. PwaFacade.php. This is to get a specific service registered into a Laravel app container through a service provider.
3. A folder called Stubs with these three files inside that folder (sw.stub, offline.stub, manifest.stub). These are template files that shall hold contents that are copied to any other file formats as we shall see at the end of the article.
4. A folder called Commands with a file inside it called PublishPwaAssets.php. This file shall contain the signature, description, and implementation of the command which shall publish the assets.

These are the folder structure and respective files of the Laravel package pwa starter kit.

Step 5: Open the manifest.stub file and add the following content to it.

The code block below is a template of how the manifest.json file should look when published.

Step 6: Open offline.stub file and add the following content to it.

This file is converted to an HTML file readable by the browser with the content of the stub when published. It’s basically the file displayed to users when they are offline.

Step 7: Open the sw.stub file and add the content below to it.

This file is converted to a JavaScript file and contains all the logic to register/install the service worker, fetch the installed content, and as you can see from the code snippet, the code is well documented.

Now that we have created our stub templates and added them to the project, we can use a custom command to publish these assets to the public folder to be accessed by the application where the package will be installed.

Step 8: Open the PublishPwaAssets.php file found inside the Commands folder and add the content below to it.

Here we provide the signature of the command, its description, and the code that implements its handle method.

We publish the pwa assets with their respective file types to the public folder of a Laravel application.

We now need to register this command inside the service provider in order to run it on the terminal using the artisan directive.

Step 9: Open the PwaServiceProvider.php file inside the src directory and populate it with the content below.

We shall import the command and register it inside the register method of the service provider.

At this point, our command is now registered and is ready for execution. Lastly, define an accessor of the command from the service container through the Facade.

Step 10: Open the PwaFacade.php file still under the src directory and add the following content

The name returned from the getFacadeAccessor() method of the facade is the name registered in the service provider’s register() method

You are all set to go, you have successfully built your custom Laravel package. You now need to publish your package to packagist for global access by other developers.

Steps to publish this package to packagist.

• Go to the https://packagist.org link
• If you already have an account, log in to continue. Otherwise, create a new account.
• Once logged in, click on the submit button at the top right corner of the menu and after that, you will then see the page below as can be seen below.

• Go to GitHub where the article source code is, copy the link and paste it here then click the Check button.
• It will then check for similar packages by looking at the name specified in your composer.json file, in this case, it will be ldtalent/pwa-laravel.
• Lastly, you will then be able to submit your package to packagist as can be seen below.

• Once submitted, you can now install it to a Laravel app using a composer as seen below.

Testing the package on a random Laravel app.

Now let’s try to run the artisan command php artisan pwa-laravel:publish on the project terminal after requiring the package.

After this command, you should get the three files in your Laravel app public folder.

Note: Lastly, every time you make changes to the package and push or merge a pull request to the main branch, create a new release with a convention v1.0.0 to control your package version on packagist.

Another key point, every time you create a new release, don’t forget to click on the update button on the package dashboard if you haven’t set up auto-update.

Learning Tools

To best learn about Laravel package development, I recommend reading the official Laravel documentation and relevant blog posts

• Laravel Docs. This provides Laravel package documentation including all the function signatures and relevant usage.
• Service Worker API Docs. This is the official documentation of service worker API.
• Cache API Docs. This page has all the documentation about the Cache object as used in the article.

Learning Strategy

Before thinking about building a Laravel package, I had to understand the basic and architectural concepts of Laravel, including the request lifecycle, service containers, service providers, and facades to make building packages easier.

Also, before writing the sw.js file content, I had to be familiar with the basic concepts and principles of service workers built into different browsers, including useful functions built in.

The package layout and all other components used by the package were easier to build because of this knowledge.

By searching the official documentation, I was able to get the official documents for the Laravel package and service worker respectively. This makes it easier to build this package layout and all other components.

I’m now able to build my own Laravel package thanks to the helpful information in this article.

Reflective Analysis

As a result of building packages, the benefits are best seen when developing a big application where certain functionalities of the system can be built in a limited time.

By requiring packages, you can reduce costs and manage scope timelines.

Conclusion

I believe this article will help boost your creativity in building Laravel packages for use by yourself and developers around the world.

This package can also be used by other PHP frameworks or projects when customizing by removing unwanted logic and adding necessary files, keeping the core concept of publishing template files intact.

Here is the link to the Github repository to get started.

Here are some other articles about Laravel that you might find helpful:

• Laravel, How to Send Multiple Emails and Attachments
• The key usage tricks of Laravel eloquent relationships (ORM) in a resourceful way
• Build A CRUD Application With Laravel And Vuejs And Deploy To Heroku
• How to solve Laravel: Unable to Open File for Reading

Hire the author: Obua E