Release and publish a new PHP SDK version automatically: a step-by-step guide

Introduction

Maintaining a well-organized changelog, releasing a new version of an SDK, then publishing it into a package repository. All these are tedious, repetitive chores that can be automated to save valuable developer time.

In this tutorial, you will learn how to set up tools that do just that. You will walk through the following steps:

1. Create a Packagist account and register your SDK
2. Store your Packagist username and API token securely in GitHub
3. Set up a Github Action to release and publish a new SDK version

Prerequisities

This tutorial assumes that you have already developed a functional SDK and pushed it into a GitHub repository.

Owner: Create a Packagist account and register your SDK

Before publishing your SDK for the first time, you need to create a Packagist account here. Then choose a suitable name for your SDK that follows the Packagist naming convention. Finally, you can submit the package to Packagist by entering the URL of your public GitHub repository.

Owner: Set up credentials

In order to automatically publish an SDK to Packagist on your behalf, GitHub needs access to your Packagist username and API token. You can securely store these credentials directly in GitHub.

1. Go to the Profile section on the Packagist website. Locate your username at the top of the page. Then click on the Show API Token button and copy the token.
2. Go to the GitHub page of your project. Go to Settings > Security > Secrets and Variables > Actions and click on the New repository secret button.
3. Enter `PACKAGIST_USERNAME` in the Name field.
4. Enter your Packagist username in the Secret field. Click on the Add secret button to confirm.
5. Create another secret (New repository secret). This time, enter the values `PACKAGIST_TOKEN` and the token you copied in Step 1 into the Name and Secret fields, respectively. Add this secret.

Release and publish a new version

Owner + Developer: Set up a Github Action to release a new SDK version

To avoid the tedious task of updating the changelog and releasing new versions manually, we recommend using the Github Action release-please. This Action keeps track of code changes since the last release and maintains a pull request with changelog and version changes based on your commit messages. When the time is right to release a new SDK version, all you need to do is merge the pull request.

The following workflow will also publish a new version of your SDK into Packagist after you release it.

Follow these steps to set up the workflow:

Owner:

1. In your Github repository, go to Settings > Actions > General and make sure that the option “Allow Github Actions to create and approve pull requests” is checked.

Developer:

2. In the root folder of your project, create a directory .github/workflows/. This is where GitHub Action configuration files should always be stored.
3. In this directory, create a new configuration YAML file. Name it for example release-and-publish.yml.
4. Copy the following code into your configuration file: 

# This workflow opens and updates a pull request with a new package version
# based on code changes. Merging the pull request updates the version in
# composer.json, updates the changelog and creates release tags.


# This workflow also publishes the package into the Packagist repository after
# a new version has been released.


# For more information, see https://github.com/marketplace/actions/release-please-action


on:
  push:
    branches:
      - master
  
permissions:
  contents: write
  pull-requests: write


name: release-please


jobs:
  release-please:
    runs-on: ubuntu-22.04
    steps:
      - uses: google-github-actions/release-please-action@v3.7.10
        with:
          release-type: php
          package-name: release-please-action
          pull-request-title-pattern: "chore(release): ${version}"
          pull-request-header: ":robot: Merge this PR to release a new version"


  publish-package:
    # after merging the pull request, a release tag first has to be created 
    # in the release-please job above, before the publish job starts
    needs: release-please
    if: contains(github.event.head_commit.message, 'chore(release)') 
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3.5.3


      - uses: hotaruma/packagist-sync@v1.0.1
        with:
          packagist-username: ${{ secrets.PACKAGIST_USERNAME }}
          api-token: ${{ secrets.PACKAGIST_TOKEN }}

If the main branch of your project has a different name than `master` (for example `main`), you need to change this on Line 14. Note that the `publish-package` job is dependent on the `release-please` job and should not start before the latter is completed successfully. This is due to the fact that the release job creates a new version tag and a version release in GitHub, and the publish job needs this info to publish the right version into Packagist.

5. Make sure your composer.json file includes the version property (for example `"version": "1.0.0"`). This property is updated automatically when you merge each new version pull request and this makes it easy to see the current SDK version in code.
6. Commit all these changes and push them into the Github repository. Now the workflow is set up. The next time someone adds something releasable with a conventional commit message (i.e. with a prefix fix: or feat:), release-please will open a pull request . As you add new code, the pull request will be updated automatically. When you are eventually ready to roll out a new version of your SDK, simply merge this pull request. The version will be released and the updated SDK will be published to Packagist.

Note that release-please follows the Semantic Versioning (SemVer) specification, which means that it will automatically generate version numbers based on the significance of your changes. For example, if you have made breaking changes, it will generate a major version number; if you have added new features, it will generate a minor version number; and if you have fixed bugs, it will generate a patch version number. By following this convention, you can make it easy for your users to understand the impact of each new version of your SDK.

Your commit messages should follow the Conventional Commits format for release-please to be able to determine the significance of your changes and generate the correct version number. This means that you should follow a specific format for your commit messages, such as "feat: add new feature" for a new feature, "fix: resolve bug" for a bug fix, and "chore: update dependencies" for a non-code change. By using this format consistently, you can ensure that release-please generates version numbers and changelogs correctly based on the significance of your changes. You can, however, always update the changelog manually in the open pull request before the release.

Conclusion

This guide walked you through the process of setting up automatic tools for releasing a new version of a PHP SDK and publishing it into the Packagist repository. By automating these processes, you save time and resources that you can instead dedicate to developing your code.

If you need help with SDK development or automation setup, our team of experts is ready to assist you. We can help you streamline your SDK development process, optimize your automation setup, and save you time and money in the process.

So why not get in touch with us today and see how we can help you take your SDK development to the next level?

Need an automated release for another technology?

• Automated release for JavaScript
• Automated release for Ruby
• Explore our tool that automates all technologies at once

You might also be interested in:
SDK: What is it and how can it help my business? 

Author

Prokop Simek

CEO

With more than 12 years in software engineering, I use my expertise to link business and technology for our clients.