Learn how to configure billing, licensing and distribution for your PHP package.
This guide will take a step-by-step approach to configure billing, licensing, and distribution for your PHP
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:
This is the name displayed throughout Unlock (including public accessible pages if applicable). You can
modify this later.
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 afterwards.
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.
Before creating a new license, a licensing policy must be available. A policy is a set of rules that applies to
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:
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.
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":
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.
By default, it's not required to activate a license 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
use your product on only two computers at a time.
You can use a release constraint to restrict license access to a major, minor and / or specific release.
here to learn
Unlock makes distribution a joy by integrating with your existing stack. Connect your GitHub account, create a
new release, and that's it. Unlock will automatically import the files from GitHub and make these available for
distribution to your customers.
Let's connect our GitHub account and select the repository that holds our PHP package:
You can connect one or more of your GitHub accounts to Unlock and set granular permissions for each account.
You can select the repository that holds your PHP package from the list of repositories you granted Unlock
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.
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. There are several ways to do this:
Import a existing release from GitHub
From the release overview, you can click the "Import release" button to import an existing release from
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.
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 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
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
file below as option 2.
1name: Build release
3# Run this workflow when a tag is published that follows the semantic versioning schema.
7 - "*.*.*"
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 # ---------------------------------------------------------------------------
18 runs-on: ubuntu-latest
21 # Create a new release and use the source code from the tag for this release
22 - name: Release and publish release
25 # That's it! All done 🚀
27 # ---------------------------------------------------------------------------
28 # Option 2
29 # The following example will show you how to create a custom distribution
30 # build of your package
31 # ---------------------------------------------------------------------------
34 runs-on: ubuntu-latest
37 # Checkout the code of this repository
38 - name: Checkout
41 # Setup PHP 8.0
42 - name: Setup PHP
45 php-version: 8.0
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
51 # Create a zip archive of all the files and exclude certain files from the archieve
52 - name: Create release archive
55 type: 'zip'
56 filename: 'release.zip'
57 exclusions: '*.git* /*node_modules/* .editorconfig'
59 # Create a new release and include the build artifact from the previous step
60 - name: Release and publish release
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.
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.
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.
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.
The name of the package, will be shown on the checkout page.
The license policy to use to generate a license on a successful purchase.
A short description of the package will be shown on the checkout page.
The price for this package, excluding any taxes.
If you set a renewal price, you can discount customers who renew their licenses.
The currency to be used for this package.
The type of charge to be used for this package. You can choose one-time charges or recurring charges
There are a few more additional settings you can configure regarding billing. Let's take a look.
When a customer purchases your product, Unlock will generate a license. If your policy requires a fingerprint
(activation), the following options can be configured to allow the customer to activate or revoke their license
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,
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.
On the purchase page we will show the image you upload.
You could use this to upload a screenshot of your application for example:
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.