Sell, license, and distribute your PHP package

Learn how to configure your private composer packages' billing, licensing, and distribution.

This guide will take a step-by-step approach to configuring billing, licensing, and distribution for your PHP composer packages via a private repository.

Create your product

Let's start by creating your product. From your dashboard, click on "Add Product." Next, fill in the form with the following information:

Product Configuration
  • Name
    This is the name displayed throughout Unlock (including publicly accessible pages if applicable). You can modify this later.
  • Identifier
    The identifier is a unique identifier for your product, and this identifier is unique across all products managed via Unlock. Unlock will use your product identifier to generate your product's public-facing URLs. You cannot change the product identifier afterward.
  • Product Type
    In this guide, we will select PHP as the product type. Choosing the appropriate product type will ensure we can use all the features Unlock provides for PHP packages.

You can choose to configure your first licensing policy and distribution now or later. Let's keep these options enabled and continue to the next step.

Product Licensing Policy

Before creating a new license, a licensing policy must be available. A policy is a set of rules that applies to a license. For example, the duration a license is valid or how many times a customer can use a license. Let's take a look at the available policy options:

  • Name
    The name of your policy. We recommend picking a name that describes your policy. For example, "1 Year", "Unlimited", "Basic", "Pro", etc.
  • Duration / Expiration
    If you want your licenses to expire, you can set the expiration date. When a license is created, it will inherit the policy's expiration date.
  • Expiration consequence
    You have the option to set a consequence when a license expires. By default, the consequence is to "Revoke access" upon expiration. Alternatively, you can select the consequence "Restrict access":
    • Revoke Access
      Upon expiration, revoke all access.
    • Restrict Access
      Upon expiration, access is restricted to the latest release that was available up until the license expiry date. This is common if you have a product that can always be used, but your customers must renew their license to receive updates.
  • Activations
    By default, activating a license is not required before a customer can use it. However, you can enable this option if you want to keep track of your license usage across multiple domains, applications, etc. You can also restrict the number of activations. An everyday use case for this is restricting your customer to using your product on only two computers at a time.
  • Release constraints
    You can use a release constraint to restrict license access to a major, minor and/or specific release. Click here to learn more.

Unlock makes distribution a joy by integrating with your existing stack. Connect your GitHub account, connect your private GitHub repositories, and create a new release, and that's it. Unlock will automatically import the files from your private repositories, and make these private packages available for distribution to your customers.

Let's connect our GitHub account and select the repository that holds our private package:

Product Distribution Settings
  • Account
    You can connect one or more of your GitHub accounts to Unlock and set granular permissions for each account.
  • Repository
    You can select the repository that holds your PHP package from the list of repositories you granted Unlock access.
  • Distribution Integration
    Unlock provides you with a list of available distribution integrations for each product type. Unlock offers a plug & play integration with Composer, PHP's package manager for PHP.
  • Auto Publish
    When you enable the auto-publish option, Unlock will automatically publish your package when you publish a new release on GitHub.
  • Public Downloads Page
    Unlock can host a public download page for your product that will allow your customers to download your product manually in case someone doesn't use Composer, for example.

Creating your first release

Now that your product has been set up, we can create our first release. Ensure the root of your repository contains a valid composer.json. There are several ways to do this:

  1. Import an existing release from GitHub
    You can click the "Import release" button from the release overview to import an existing release from GitHub. Import an existing release from GitHub
  2. Create a new release via GitHub
    Visit your repository on GitHub and choose "Releases" on the right side. Next, click "Draft a new release." Create a tag like "1.0.0" and additional details about your release. If you decide to attach a file of your own (e.g., a custom distribution build) Unlock will use this instead of the source code. Create a new release via GitHub
  3. Use a GitHub actions workflow to publish a release automatically
    You can use a GitHub actions workflow to publish a release automatically when you publish a new tag. We will use this approach in our example below. Use a GitHub actions workflow to publish a release automatically
  4. Use a GitHub actions workflow to build a distribution version of your package
    In some cases, you might want to create a special distribution build, for example, with compiled CSS and Javascript. Unlock will choose a custom file instead of the source code if it detects a build file -- More on this below. Use a GitHub actions workflow to publish a release automatically

In this example, we will use a GitHub action workflow to automatically create a release every time a new tag is created. Optionally, you can create a custom distribution build as shown in the .github/workflows/release.yml file below as option 2.

1name: Build release
2 
3# Run this workflow when a tag is published that follows the semantic versioning schema.
4on:
5 push:
6 tags:
7 - "*.*.*"
8 
9jobs:
10 
11 # ---------------------------------------------------------------------------
12 # Option 1
13 # The following example will show you how to create a release with just
14 # the source code from your repository
15 # ---------------------------------------------------------------------------
16 
17 build:
18 runs-on: ubuntu-latest
19 steps:
20 
21 # Create a new release and use the source code from the tag for this release
22 - name: Release and publish release
23 uses: softprops/[email protected]
24 
25 # That's it! All done 🚀
26 
27 # ---------------------------------------------------------------------------
28 # Option 2
29 # The following example will show you how to create a custom distribution
30 # build of your package
31 # ---------------------------------------------------------------------------
32 
33 build:
34 runs-on: ubuntu-latest
35 steps:
36 
37 # Checkout the code of this repository
38 - name: Checkout
39 uses: actions/[email protected]
40 
41 # Setup PHP 8.0
42 - name: Setup PHP
43 uses: shivammathur/[email protected]
44 with:
45 php-version: 8.0
46 
47 # Install the composer dependencies
48 - name: Install Dependencies
49 run: composer install -q --no-ansi --no-interaction --no-scripts --no-suggest --no-progress --prefer-dist
50 
51 # Create a zip archive of all the files and exclude certain files from the archieve
52 - name: Create release archive
53 uses: thedoctor0/[email protected]
54 with:
55 type: 'zip'
56 filename: 'release.zip'
57 exclusions: '*.git* /*node_modules/* .editorconfig'
58 
59 # Create a new release and include the build artifact from the previous step
60 - name: Release and publish release
61 uses: softprops/[email protected]
62 with:
63 files: release.zip

Publish a new tag, and you will see a new release created automatically and show up on your dashboard in a matter of seconds.

GitHub release automatically imported

Configure billing and start selling

Perfect! We have our licensing policy set up; our release has been imported and published. Let's continue by setting up billing so we can sell our package. Choose billing from your product navigation.

Stripe onboarding

Unlock partners with Stripe to provide the best checkout experience there is. Click "Start Selling" to start the onboarding process with Stripe. Once you're done, you can configure the billing settings for your product.

Product Billing

From the billing page, you can enable billing for your product, create pricing packages, enable tax collection, manage license settings and upload an image that Unlock will show during checkout. Let's continue by creating our first pricing package.

Pricing package
  • Name
    The name of the package will be shown on the checkout page.
  • Policy
    The license policy to use to generate a license on a successful purchase.
  • Description
    A short description of the package will be shown on the checkout page.
  • Price
    The price for this package, excluding any taxes.
  • Renewal Price
    If you set a renewal price, you can discount customers who renew their licenses.
  • Currency
    The currency to be used for this package.
  • Type
    The type of charge to be used for this package. You can choose one-time charges or recurring charges (coming soon).

There are a few more additional settings you can configure regarding billing. Let's take a look.

Additional billing settings

License settings

When a customer purchases your product, Unlock will generate a license key for your customer. The license key is the personal access token to authorize access to the private repository. If your policy requires a fingerprint (activation), the following options can be configured to allow the customer to activate or revoke their license themselves.

  • Fingerprint label
    The term "fingerprint" is used by Unlock to define a unique identifier for a license activation. This term might be confusing to some customers, so we have provided the option to specify a custom label. This way, you can replace the term fingerprint with something more relevant for your users, like domain or app name, for example.
  • Activation Permissions: Activate
    When you enable the 'activate' option, customers can activate their license themselves after their purchase.
  • Activation Permissions: Revoke
    When you enable the 'revoke' option, customers can revoke a license activation themselves, for example, if they want to use their license for a different device or domain.
License activation by the customer

Branding settings

On the purchase page, we will show the image you upload. You could use this to upload a screenshot of your application, for example:

Branding settings

That's it; you are all set and ready to sell your private PHP package. Unlock will show your customers the installation instructions on adding your private composer repository and requiring your private PHP package.

Install private php composer package instructions

Frequently asked questions

  • How do I create a private Composer package?
    The easiest way to start is by installing the Composer CLI. Next, run the following command: composer init - this command will prompt all the necessary questions to generate a valid composer json file.
  • Do my customers need SSH keys to authenticate?
    Your customers do not need SSH keys to authenticate. Unlock's private Composer repository uses http-basic authentication. The username is equal to the licensee's email, and the password is equal to the license key. If the license is not associated with any licensee, the username is unlock.
  • Do I need Satis?
    You do not need Satis as Unlock provides a managed private Composer repository for your projects which fully integrates with GitHub.