Tips For Building Your First Laravel Package

Laravel is a powerful and modern framework. It has tons of different features, which make our work faster and easier. But you can’t push everything into the single box. At one time or another, we’ve all been in need of something not implemented in the framework out of the box. So, you’re writing code by yourself; it works, and you are happy. Yep?

But what if you need the same functionality in another project? Will you write it again? Copy-paste it? Both solutions are bad because you’re solving the same problem again and again. And what about bugs? Imagine finding a bug in that code a few days later. Now you have to fix it in N places. Ufff, not fun!

A package can be a solution. Write your code once and use it in any number of projects. Maybe you found a bug, or want to make some changes? Do it just once in your package code and then pull required changes in all of your projects. Sounds good?

#The First Step

Before diving into the work with your head, check Packagist first. It is possible someone has already solved your problem. If you can’t find an existing package, try to explore the question a little bit deeper. Maybe you’re not using the most accurate keywords in your search. Don’t be afraid to spend another 30 minutes; it could save you 30 days eventually.

#Development

You’ve searched, but no luck and now you’re willing to create a new Laravel package. What are the next steps?

First of all, take a look at the Laravel documentation. The Package Development page is a great starting point. You’ll find out in most cases, the heart of your package would be a service provider. Here you can register event listeners, middleware, routes, translations, views, etc. Maybe your package has its own config file, maybe even its own database migrations. You have to describe all of that in your service provider. It is the connection point between your package and Laravel.

Your head is full of knowledge; you are creating new GitHub repo and starting to write code. Great! What tips can I give to you?

I think one of the most important things, when you’re writing a framework package is to make the package close to the framework. In everything: architecture, naming, code style, documentation, every aspect of it. It will be much easier for people to understand and use your package if it looks like the part of the framework. But, it’s not always easy to choose those best names for classes, methods, variables, etc. I really like Jeffrey Way’s method, which I learned at Laracasts. When you’re feeling a name isn’t very good, delete it and write it as you’d want it to be in a perfect world, then use it. Simple enough, but it works. Naming is not the easiest thing in programming, and there are a lot of good books about it.

I’ve received the following feedback from someone using my package: “Nice readme file! It’s really easy to read it, it feels like I’m reading one of the Laravel docs!” That was my victory!

If people feel your package is a natural part of the framework — you’re on the right path.

#Testing

Package testing can be really tricky. And the first question I had, before even starting to write tests was this: how should I test it? Should I create a new instance of my Laravel project, install my package there, and write my tests? These were the real usage conditions of my package, but my tests would be located outside of the package, which is really bad.

Luckily, there is Testbench Component to solve that problem. It provides a way to test your package without a standalone Laravel install. You can easily register your package service provider, aliases, set up the database, load migrations, etc.

The great thing about open source is you can use cool GitHub integrations for free. They can help you in different ways. My favorites are:

• SensioLabs Insight – for code quality;
• StyleCI – for code style;
• Travis – for running tests automatically;
• Coveralls – for measuring code coverage by tests;

#Documentation

Your code is ready and, your tests are green. You think you’re done at this point? Nope.

Don’t be lazy; create a nice readme file. It can be really useful for you because you’re taking another look at your package in general. There have been so many times while writing a readme file that new ideas have come to me. And having a good readme allows others to be able to use your package as well. Isn’t it great to know your code is useful for someone?

I think a readme file is really important, and it should be as simple as possible. Use images, where possible. They are easier to understand. Write your documentation as close to Laravel Documentation as you can.

There is a really great article “How to write a readme that rocks“, take a look! There are a lot of cool tips and tools described there. For example, Michael Dyrynda’s Readme Generator, Grammarly, Hemingway App, etc.

#Release

Don’t forget to add your package to Packagist, so it will be available through Composer. That will make your package installation really easy, and make it searchable through Composer. Use keywords in your composer.json file. You can also set up GitHub Topics to make your package even more searchable.

Use GitHub Releases for your package. Read and follow Semantic Versioning rules.

It doesn’t matter how cool is your package if people don’t know about it. Tell them!

Write short notes on community forums, for example, Laracasts Forum, Larachat, etc. Add a link to your package on Laravel News. Don’t be afraid to tell!

#Conclusion

Creating your own packages can make your code cleaner, preventing you from repeating yourself over and over in different projects. I’m not saying you have to extract everything into the packages, no. It’s all about the balance, like in coding. Should I extract that code into the separate method? Or, maybe even into the separate class? Remember those questions? I think “Should I extract that code into the separate package?” is something similar to these questions. It depends. Feel it, and make a decision according to your context and experience.

There are a lot of aspects, which are not covered in this short article, but I really hope it will be useful for someone. Please, contact me if you have any thoughts or questions.

Wish you tons of stars on your own packages!