Packagist (mage.rocks) – The Magento 2 Package Repository

With this post, we’d like to draw you attention to Packagist (https://mage.rocks/) – the Magento 2 community package repository. Being the main repository for Composer, it is used to aggregate some installable via Composer public PHP packages. As a result, you can easily find necessary packages as well as provide Composer with important data. For further information about the Magento 2 Composer tandem, follow this link: Magento 2 Composer Guide. And don’t forget to  check the packagist.org source on GitHub. You can use the same repository to report issues or contribute code.

Let’s start with the Packagist community and useful links. If you have any questions related to our topic, go to the #composer channel on irc.freenode.net. Besides, it is also necessary to check the Composer documentation, since it already provides answers to all your questions.

If you are looking for a commercial tool related to Packagist, it is Toran Proxy. The solution is designed to simplify the installation of packages, provide a private package repository, and support Composer and Packagist financially.

If you are wondering how to submit a package, check the following guide.

1) Name a package

Choose a name for your package. Please note that it should be unique, otherwise, you won’t be able to avoid conflicts.

The name of a package includes two elements a vendor name and a project name joined by “/”. The first one prevents naming conflicts. At the same time, both (the vendor name and the package name) can be identical.

Check some official examples:

Note that package names are case-insensitive, but it’s encouraged to use a dash (-) as separator instead of CamelCased names.

2) Create a composer.json file

The composer.json file is utilized for describing a package to Packagist and Composer. Please note that it should reside at the top of your package’s git/svn/ repository. That is how typical composer.json looks like:

Once the file is ready in an appropriate repository root, you can easily submit your package. To make it available via Packagist, follow the submit link and enter the public repository URL.

3) Manage package versions

Please note that each new version of your package is fetched from tags you create in an appropriate VCS repository automatically.

Thus, the most simple way of versioning management requires omitting the version field from your composer.json file. Consequently, a new version number will be parsed from such sources as the tag and branch names.

Please note that there are some strict requirements to tag/version names. First of all, they should match ‘X.Y.Z’ or ‘vX.Y.Z’. Besides, there can be an optional suffix for beta, alpha, RC,  or patch versions. Check some correct names provided by Packagist:

All your branches appear as “dev” versions automatically, being easily installable by anyone. But you should also tag your releases manually. It is also necessary to mention that there is a strongly encouraged condition – the use of Semantic Versioning.

Update Schedule

• In case you have enabled JavaScript, all your new packages are crawled immediately right after submission.
• In case you have some packages with no auto-updating, the platform will crawl them once a week to make an update.
• For an enabled hook, it crawls packages whenever you push. There is also a scenarium when packages are crawled once a month.
• In case you are  logged in as a maintainer, there is an opportunity to trigger an update manually.
• Please note that the GitHub/BitBucket service hook should be set up for all your packages in order to minimize the load, and update packages.
• As for the the search index, it is updated within five minutes.

Update packages

GitHub Service Hook. If you enable this feature, your package will always be updated any time you push updates to GitHub. To activate GitHub Service Hook, you should:

• Visit to your GitHub repository.
• Hit the Settings button.
• Click the Webhooks & Services button.
• Now, you should ddd a Packagist service.
• Use your API token to configure it (plus your Packagist username).
• Check the Active box and then submit the available form.
• Hit the Test Service button to check if everything works as it should.

Bitbucket POST Service. To enable this feature, you should:

• Open your BitBucket repository.
• Select Hooks from settings.
• Pick and add POST to your repository.
• Enter the Packagist endpoint with your username and API token:

• Save changes.

Manual setup. Alternatively to Bitbucket and GitHub, you can rely on a generic endpoint that can be called manually. For instance, from a git post-receive hook. Do a POST request to:

A request body should look as follows:

The official documentation recommends to achieve this goal with the help of curl:

If you have any other questions related to Magento 2 Packagist pair, leave them in comments or check the aforementioned links, since there are already a lot of answers provided there.