Listing Packages on Packagist for Composer

Key Takeaways

• Composer and Packagist are increasingly becoming the modern way to share and find open-source libraries, with the first step being to set a name for your package in the composer.json file, which includes vendor name and project name.
• Additional information such as a brief description of the package, its homepage, the license, and author information can also be included in the composer.json file, along with the requirements for the library, such as the minimum version of PHP needed or any PHP extensions required.
• Once your library’s code is committed to GitHub, it can be listed on Packagist for others to find and download easily, by submitting the URL of your project on GitHub to Packagist, and setting up the Packagist hook on GitHub for auto-updating.

By now I’m sure you’ve seen first-hand how Composer can help manage dependencies; I’ve grown quite fond of it myself, using it for the downloadable code samples on GitHub for our articles. Readers can peruse through just the relevant source code on GitHub if they like, and a quick git clone and composer install can get them the code and all the dependencies necessary to play with the code locally. But what about taking it to the next level? You’ve created an awesome library, and now you’re ready to open source it and share it with the world. Hopefully someone else can benefit from your work, and maybe you’ll even receive a bug report or patch to make the library even better. But none of that can happen unless people can find it… and the modern way is increasingly becoming through Composer and Packagist. In this article I’ll show you what information is needed in your composer.json file and how to list your library on Packagist so others can easily find it.

The composer.json File

Composer’s documentation states that every project is a package. Indeed, your project is just an anonymous package in the eyes of Composer, whether it’s a library, full-fledged application, or whatever else in between.

As soon as you have a composer.json in a directory, that directory is a package. […] The only difference between your project and libraries is that your project is a package without a name.

So, an important first step is to set a name for your package. Package names are made by combining a vendor name and project name, for example psr/log or laravel/framework . What should you use as your vendor name? A good choice is your GitHub username. While that’s all you really need, it’s a good idea to specify some addition information in your library’s composer.json file, such as a brief description of the package, its homepage, the license, and author information.

"name": "tboronczyk/testlib",
"description": "A simple test library",
"homepage": "https://github.com/tboronczyk/testlib",
"license": "WTFPL",
"authors": [
    {
        "name": "The TestLib Team",
        "homepage": "https://github.com/tboronczyk/testlib/graphs/contributors"
    }
]

I’ve seen many project list multiple individual entries for each author, probably since this is what’s presented in the documentation as an example, but I prefer the above practice of listing the name as a team and providing a link to the contributors graph on GitHub, this way everyone receives credit and you won’t have to constantly update your composer.json file. It’s also important to specify the requirements for your library. We’re familiar with the require section as a place to list other packages our code depends on, and obviously this doesn’t change if your library has third-party dependencies. But it can also be used to specify “platform packages”. Platform packages are not actual packages that are installable through Composer, but rather a means of specifying requirements for the execution environment, such as the minimum version of PHP needed, or any PHP extensions that are needed.

"require": {
    "php": ">=5.3",
    "ext-zip": "*",
    "ext-fileinfo": "*",
    "phpunit/phpunit": "3.1.*"
}

Listing on Packagist

Once you have your library’s code committed to GitHub, you’ll want to list it on Packagist so others can find it and easily download it. Luckily, Packagist makes it super easy to advertise your library. Go to packagist.org and click the giant green Submit Package button in the top right corner. If you’re not logged in already, you’ll be taken to a login form first, but ultimately you’ll end up on the package submission page.

Enter the URL to your project on GitHub and click the Check button. Packagist will validate the address and then provide you with a giant Submit button to click. Voila! It’s as simple as that. Packagist crawls your GitHub repository for branches and the composer.json file, and displays the information on your library’s package page.

Allow me to bring your attention to the notice on the package page that warns the package is not auto-updated because you don’t have the Packagist hook enabled on GitHub. Auto updating is a good thing since Packagist will make the latest revisions available as you update your code and commit it to GitHub. So, let’s get this taken care of. First, click the link that’s your username at the top right corner of Pacakgist to go to your account page. There you’ll find your API token, and brief instructions on setting up the Service hook. Second, head over to your repository’s page on GitHub and click the Settings menu item.

Select Service Hooks from the side menu, pick Packagist from the list of hooks, and then supply your information in the form. You’ll definitely need to provide your API token that was listed on your Packagist account page, and your username on Packagist if it isn’t the same as your GitHub username, but you can leave the Domain field blank. Then click the checkbox labeled “Activate” and submit the details.

Conclusion

Listing your package on Packagist so that it can be downloaded easily through Composer by other developers is easy, although many people might think it difficult because they’ve never done it before. Hopefully this article will help you take your Composer usage to the next level, because it really is little more than providing a name for the package and clicking a giant green button. Now go on, share that great code you’ve been working so hard on with the rest of the world! Image via Fotolia

Frequently Asked Questions (FAQs) about Listing Packages on Packagist for Composer