note: this is applicable to building regular php packages, not just laravel.
I was in the process of creating this laravel php package when I decided that it might be beneficial — due to this package’s extreme simplicity—to publish a tutorial that shows how easy it can be to create a laravel package that is install-able via composer.
My intention is simple for this package, yet it is of grave importance to humanity: provide alternative helper functions in the laravel development environment that will print an ascii cat before dumping the data using laravel’s own dd() and dump() functions. My functions will be aptly named cc() and c(). First I’ll walk through the very bare-bones basic process of setting up a package and getting it on packagist, then you can read on for more info about packages and how to manage them.
Step 1: initial project
Create a new laravel project and add a directory for your package. We will be using, as an example, the project name of ‘unreal-project’ and the package name will be ‘laravel-cats’.
laravel new unreal-project
mkdir -p unreal-project/packages/laravel-cats/src && cd unreal-project/packages/laravel-cats
Step 2: initialize package
Now that you have created the package directory and navigated to it in the terminal. Run the following command and follow the prompts/questions and a composer.json file will be created for you:
In the composer.json file that was created automatically by ‘composer init’, we will manually add in the autoloading of your package. This will tell any project which uses your package that it should automatically load your code that lives in the
/src directory (unreal-project/packages/laravel-cats/src).
Now any project which uses your package can simply include the line
use Djaxho/Laracats in their files and have access to whichever classes you put in your unreal-project/packages/laravel-cats/src directory. Notice that we also added in a ‘files’ array which you can do if you want specific files to be autoloaded also. In the laravel-cats case, this is actually the only thing we need to do since we are only adding a couple of helper functions.
Final Step 3: publish
Make your package available to the world with composer and packagist.
Once you have actually written your package, create a git repository to host them (we will use github) and then add the package to packagist so anyone can use it by simply running
composer require djaxho/laravel-cats --dev.
In the terminal, navigate to your package directory (i.e. unreal-project/packages/laravel-cats). Run the following commands:
# initialize the git repository
> git init
# link it to the github repo
> git remote add origin https://github.com/djaxho/laravel-cats.git
# add and commit all of your files
> git add --all
> git commit -m "Initial release"
# tag your release version number
> git tag -a v0.0.1 -m "Initial release"
# upload to github
> git push -u origin master
> git push origin --tags
Now when anyone wants to use your package in a project, all they need to do is run
composer require djaxho/laravel-cats --dev.
Additional notes and options
I’ve intentionally left the first part of this article above very simple to show how easy it is to set up a package. Many tutorials and documentation sites seem to be a bit confusing for newcomers. There are some other topics that you should probably consider when publishing a package though, and I’ll lay out some of them now.
Readme, licence, contributing, change log and more…
There are a number of files you should include in a package to handle more than just composer.json dependency management. A good way to learn about all the files you can include and the way to lay them out (this goes for your composer.json file as well) is to look at other popular open source packages like laravel-debugbar and more. You can add some badges to your readme with this.
Of considerable note here, is that you should also provide tests for your packages and autoload them in your composer.json like laravel does:
This tutorial assumes you have composer installed, laravel installed, and git installed and set up, a github account and a packagist account. If you are on windows it may be a bit more difficult for you, but all, or most, of the commands should work on your gitbash terminal.
I’ve left the code out of this tutorial for clarity and brevity. But you can view it here. It is very basic and just adds a couple of helper functions.
Additionally, I did not use the same autoloading as I specified in the tutorial because this package’s autoloading is a bit different from what an ordinary package would use. It does not need to do a psr4 autoload of the src directory because all I needed it to do was load the functions from one file.
I also included laravel and php as requirements since this package depends heavily on them.
Laravel-specific package development
While this laravel-cats package relies on laravel, this tutorial is not specific to laravel because it is so simple. It is more of a starting point to get your autoloading, composer settings, and packagist set up. Once you make it this far, you can start to run through the laravel documentation on package development to take advantage of all the cool things it offers like:
- using Service Providers to tie into the laravel framework
- custom routes, migrations, and views that are provided to the parent laravel app that is using your package
- publishing configuration files
- and more…
These can all be very powerful tools to make package/code re-use between projects much easier to maintain.
Hopefully this tutorial gets you through the initial confusion about how to get to the point where you can actually start using all the laravel package development features encountered in the documentation.