Install and authenticate the private NextPDF premium package with Composer

At a glance

The NextPDF premium packages — nextpdf/pro, nextpdf/enterprise, and the nextpdf/premium metapackage — are not published on the public Packagist index. They live in a private Composer repository tied to your account, so a plain composer require nextpdf/premium cannot find them until you tell Composer two things: where the repository is, and how to authenticate to it.

This page picks up where Licensing and activation leaves off. Once you have credentials, you configure Composer once, install the package, and verify it. Everything here is standard Composer behavior; none of it is NextPDF-specific tooling. Treat your repository token like an API key, exactly as the licensing page treats the signed license envelope: keep it out of public version control.

Get your credentials from your account

Your NextPDF premium packages, Composer credentials, and licence file come from your NextPDF account at app.getnextpdf.com, issued once you obtain a licence and your delivery channel is set up — by purchasing through our Merchant of Record or by starting an evaluation. The guided install flow at app.getnextpdf.com/account/install walks the sequence and tracks the server-observable steps as you go; this page documents the Composer mechanics behind it. From your account you get:

• Your private Composer repository URL — the token-creation step shows it, and the generated composer.json already contains it.
• A Composer token — an HTTP Basic credential pair: the token id is the username, the token secret is the password. The secret is shown once, at creation.

For the purchase path, the two-contract model (purchase versus licence), and who to contact for billing versus product help, see Buying and licensing.

1. Where the premium packages live

The private repository is served from one host for every account — app.getnextpdf.com — at a repository path that is specific to your account:

https://app.getnextpdf.com/composer/<your-account-path>/

<your-account-path> is an opaque identifier from your account (it is not a secret); your token is what authenticates. Because credentials in Composer are matched by host, the authentication key in step 3 is always http-basic.app.getnextpdf.com.

2. Add the private repository to composer.json

The simplest path: download the generated composer.json from your account’s install guide — it already carries the repository block and the require entry for your edition. To add the repository to an existing project instead, run one command in your project root, substituting your repository URL:

composer config repositories.nextpdf composer https://app.getnextpdf.com/composer/<your-account-path>/

The composer repository type points Composer at a Composer-format index (a packages.json), which is what the endpoint serves. That command writes a repositories block into composer.json. You can also add it by hand:

{
    "repositories": {
        "nextpdf": {
            "type": "composer",
            "url": "https://app.getnextpdf.com/composer/<your-account-path>/"
        }
    }
}

The repository definition is not a secret — it only names a location, so it is safe to commit. The credentials in the next step are what you must protect.

3. Authenticate with one of three standard methods

Composer reads HTTP Basic credentials for a host from several places. Pick the method that matches where you are installing.

Method A — auth.json (local development)

For a developer machine, store the credential in an auth.json file next to composer.json. The key is the repository host — always app.getnextpdf.com:

composer config --auth http-basic.app.getnextpdf.com your-token-id your-token-secret

This creates (or updates) a project-local auth.json:

{
    "http-basic": {
        "app.getnextpdf.com": {
            "username": "your-token-id",
            "password": "your-token-secret"
        }
    }
}

The host key (app.getnextpdf.com) must match the host in the repository URL exactly — no scheme, no path, no trailing slash — because Composer matches credentials to requests by host.

Method B — COMPOSER_AUTH environment variable (CI/CD)

In continuous integration you usually do not want a file on disk. Composer reads the same credentials from the COMPOSER_AUTH environment variable, whose value is a JSON string with the same shape as auth.json:

export COMPOSER_AUTH='{"http-basic":{"app.getnextpdf.com":{"username":"your-token-id","password":"your-token-secret"}}}'
composer install

Inject COMPOSER_AUTH from your CI provider’s secret store (masked variable, secret, or vault binding) so the token never appears in the pipeline definition or the build log.

Method C — global per-user auth (shared workstation)

To authenticate every project for the current user without a per-project file, write the credential into Composer’s global auth.json:

composer config --global --auth http-basic.app.getnextpdf.com your-token-id your-token-secret

This stores the credential under your Composer home directory (COMPOSER_HOME, e.g. ~/.composer/auth.json or ~/.config/composer/auth.json). It applies to all projects you build as that user, so prefer Method A or B when a credential should be scoped to one project or pipeline.

4. Keep credentials out of version control

The repository URL is safe to commit; the token is not. Two rules keep secrets out of your history:

• Ignore the local auth file. Add auth.json to .gitignore so a project-local credential is never committed:

  /auth.json

• Inject the token in CI/CD. Provide COMPOSER_AUTH (Method B) from your pipeline’s secret store rather than checking an auth.json into the repository or baking it into a container image layer.

If a token is ever committed or printed, treat it as compromised, exactly as you would a leaked API key: revoke it on the licence page in your account and create a new one from the install guide.

5. Install and verify

With the repository and credentials in place, require the edition your license entitles:

# Pick the package for your entitlement:
composer require nextpdf/pro
# or
composer require nextpdf/enterprise
# or the metapackage, which the licensing page uses:
composer require nextpdf/premium

Pin a major version if your project prefers explicit constraints — for example composer require nextpdf/pro:^3, matching the constraint the Pro module pages use.

Verify that Composer resolved the private package and that its autoloader works. First confirm the package is installed by running composer show <installed-package> for whichever edition you required — for example composer show nextpdf/pro, composer show nextpdf/enterprise, or composer show nextpdf/premium:

# Use the package name you actually required:
composer show nextpdf/pro
# or
composer show nextpdf/enterprise
# or
composer show nextpdf/premium

If composer show reports the package and its version, the private package resolved. Re-running composer dump-autoload then regenerates the autoloader cleanly, so the package’s classes are discoverable:

composer dump-autoload

As an optional code-level check, you can confirm that a class from your installed edition autoloads. Do not guess a class name: open the API reference for the edition you installed and pick any documented public class, then test that it resolves. The class to look for depends on your edition — a class that ships in one edition may not be present in another, and a single class autoloading proves only that its edition is present, not that every edition is installed.

<?php
require __DIR__ . '/vendor/autoload.php';

// Replace the placeholder with a documented public class from YOUR edition's
// API reference. Do not hardcode a class from a different edition.
$class = 'Your\\Installed\\Edition\\DocumentedClass';
var_dump(class_exists($class));

Installing the package is not the same as activating it. The package alone does not grant Pro or Enterprise capabilities — the signed license you activate selects the active edition. After a successful install, follow Licensing and activation to place and activate the license envelope, and, for ionCube-encoded builds, set up the ionCube Loader.

Troubleshooting

401 Unauthorized or 403 Forbidden

Composer reached the repository but the credentials were rejected or insufficient. Confirm the host key in auth.json / COMPOSER_AUTH is exactly app.getnextpdf.com (no scheme, no path, no trailing slash), that the token id and secret are current, and that the token has not expired or been revoked in your account. A 401 points to a wrong or missing credential; a 403 points to a valid credential whose scope does not include the package or edition you requested — check that your subscription entitles the package name you are requiring.

Package not found / “could not find a matching version”

This usually means Composer did not use or reach the private index (so it only searched public Packagist), or it reached the index but found no installable package or version that matches. Confirm the repositories.nextpdf block exists in this project’s composer.json with "type": "composer" and the correct URL, and that you are requiring the exact package name (nextpdf/pro, nextpdf/enterprise, or nextpdf/premium). Run composer config repositories to print what Composer sees. A typo in the URL or a missing repository block is a common cause, but also check that your version constraint matches a published version, that your project’s PHP platform requirement (and minimum-stability) allows the package, and that your token’s entitlement actually covers the package you are requiring.

Token works locally but fails in CI

The local auth.json is not present on the runner. Set COMPOSER_AUTH from your CI secret store (Method B) rather than relying on a file, and make sure the variable is exported before composer install runs. In containerized builds, pass the secret at build time without persisting it into an image layer.

Wrong host key

Credentials are matched by host. The repository URL is https://app.getnextpdf.com/composer/<your-account-path>/, so the key must be app.getnextpdf.com — not the full URL and not the account path. A mismatched key makes Composer send the request unauthenticated, which surfaces as a 401.

See also

• Licensing and activation
• Set up the ionCube Loader
• NextPDF Premium
• Choose your path
• License portal