Premium phiên bản

Cài đặt và xác thực gói NextPDF premium riêng tư bằng Composer

Tổng quan nhanh

Các gói NextPDF premium — nextpdf/pro, nextpdf/enterprise, và metapackage nextpdf/premium — không được công bố trên chỉ mục Packagist công khai. Chúng nằm trong một kho Composer riêng tư gắn với tài khoản của bạn, nên một lệnh composer require nextpdf/premium thông thường không thể tìm thấy chúng cho đến khi bạn cho Composer biết hai điều: kho nằm ở đâu, và làm sao để xác thực với nó.

Trang này tiếp nối nơi Cấp phép và kích hoạt dừng lại. Khi đã có thông tin xác thực, bạn cấu hình Composer một lần, cài đặt gói, và xác minh nó. Mọi thứ ở đây là hành vi Composer chuẩn; không có gì là công cụ riêng của NextPDF. Hãy đối xử với mã truy cập kho của bạn như một khóa API, đúng như cách trang cấp phép đối xử với phong bì giấy phép đã ký: giữ nó ngoài quản lý phiên bản công khai.

Thông tin xác thực của bạn đến từ đâu

URL kho riêng tư, tên đăng nhập và mã truy cập của bạn được cấp sau khi bạn có được một giấy phép — bằng cách mua thông qua Merchant of Record của chúng tôi hoặc bằng cách bắt đầu một đợt đánh giá — từ cổng giấy phép. Để biết lộ trình mua, mô hình hai hợp đồng (mua so với cấp phép), và liên hệ với ai về thanh toán so với về sản phẩm, hãy xem Mua và cấp phép.

1. Các gói premium nằm ở đâu

Cổng giấy phép của bạn cấp hai thứ cho việc cài đặt:

Một URL kho Composer riêng tư — điểm cuối đã xác thực phục vụ các gói premium.
Một tên đăng nhập và mã truy cập (một cặp thông tin HTTP Basic) cho điểm cuối đó.

Ở bất kỳ chỗ nào trang này hiển thị một host kho, hãy thay bằng URL kho từ cổng giấy phép của bạn. Ở bất kỳ chỗ nào nó hiển thị tên đăng nhập hoặc mã truy cập, hãy thay bằng thông tin xác thực được cấp cho tài khoản của bạn. NextPDF không công bố một URL chung duy nhất; điểm cuối và thông tin xác thực là riêng cho đăng ký của bạn.

2. Thêm kho riêng tư vào composer.json

Cho Composer biết về kho bằng một lệnh, chạy ở thư mục gốc dự án của bạn:

composer config repositories.nextpdf composer https://repo.example.com/nextpdf

Thay https://repo.example.com/nextpdf bằng URL từ cổng của bạn. Loại kho composer trỏ Composer đến một chỉ mục định dạng Composer (một packages.json), là thứ mà một điểm cuối gói riêng tư phục vụ.

Lệnh đó ghi một khối repositories vào composer.json. Bạn cũng có thể thêm nó thủ công:

{
    "repositories": {
        "nextpdf": {
            "type": "composer",
            "url": "https://repo.example.com/nextpdf"
        }
    }
}

Định nghĩa kho không phải là bí mật — nó chỉ nêu tên một vị trí, nên an toàn khi commit. Thông tin xác thực ở bước tiếp theo mới là thứ bạn phải bảo vệ.

3. Xác thực bằng một trong ba phương thức chuẩn

Composer đọc thông tin HTTP Basic cho một host từ nhiều nơi. Hãy chọn phương thức khớp với nơi bạn đang cài đặt.

Phương thức A — auth.json (phát triển cục bộ)

Trên máy của lập trình viên, lưu thông tin xác thực vào một tệp auth.json đặt cạnh composer.json. Dùng host của URL kho làm khóa:

composer config --auth http-basic.repo.example.com your-username your-token

Lệnh này tạo (hoặc cập nhật) một auth.json cục bộ trong dự án:

{
    "http-basic": {
        "repo.example.com": {
            "username": "your-username",
            "password": "your-token"
        }
    }
}

Khóa host (repo.example.com) phải khớp chính xác với host trong URL kho — Composer khớp thông tin xác thực với các yêu cầu theo host.

Phương thức B — biến môi trường COMPOSER_AUTH (CI/CD)

Trong tích hợp liên tục, bạn thường không muốn có tệp trên đĩa. Composer đọc cùng thông tin xác thực đó từ biến môi trường COMPOSER_AUTH, mà giá trị của nó là một chuỗi JSON có cùng hình dạng với auth.json:

export COMPOSER_AUTH='{"http-basic":{"repo.example.com":{"username":"your-username","password":"your-token"}}}'
composer install

Hãy bơm COMPOSER_AUTH từ kho bí mật của nhà cung cấp CI (biến được che, secret, hoặc ràng buộc vault) để mã truy cập không bao giờ xuất hiện trong định nghĩa pipeline hay nhật ký build.

Phương thức C — auth toàn cục theo người dùng (máy trạm dùng chung)

Để xác thực mọi dự án cho người dùng hiện tại mà không cần tệp riêng theo dự án, hãy ghi thông tin xác thực vào auth.json toàn cục của Composer:

composer config --global --auth http-basic.repo.example.com your-username your-token

Lệnh này lưu thông tin xác thực dưới thư mục home của Composer (COMPOSER_HOME, ví dụ ~/.composer/auth.json hoặc ~/.config/composer/auth.json). Nó áp dụng cho mọi dự án bạn build với tư cách người dùng đó, nên hãy ưu tiên Phương thức A hoặc B khi một thông tin xác thực nên giới hạn trong một dự án hoặc pipeline.

4. Giữ thông tin xác thực ngoài quản lý phiên bản

URL kho an toàn khi commit; mã truy cập thì không. Hai quy tắc giữ bí mật ngoài lịch sử của bạn:

Bỏ qua tệp auth cục bộ. Thêm auth.json vào .gitignore để một thông tin xác thực cục bộ trong dự án không bao giờ bị commit:
```
/auth.json
```
Bơm mã truy cập trong CI/CD. Cung cấp COMPOSER_AUTH (Phương thức B) từ kho bí mật của pipeline thay vì commit một auth.json vào kho hoặc nướng nó vào một lớp ảnh container.

Nếu một mã truy cập từng bị commit hoặc in ra, hãy luân chuyển nó qua cổng giấy phép của bạn — coi nó như đã bị xâm phạm, đúng như cách bạn xử lý một khóa API bị lộ.

5. Cài đặt và xác minh

Khi kho và thông tin xác thực đã sẵn sàng, hãy require phiên bản mà giấy phép của bạn cho phép:

# 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

Hãy ghim một phiên bản major nếu dự án của bạn ưa các ràng buộc tường minh — ví dụ composer require nextpdf/pro:^3, khớp với ràng buộc mà các trang module Pro dùng.

Hãy xác minh rằng Composer đã giải quyết được gói riêng tư và bộ tải tự động của nó hoạt động. Trước tiên hãy xác nhận gói đã được cài đặt bằng cách chạy composer show <installed-package> cho phiên bản bạn đã require — ví dụ composer show nextpdf/pro, composer show nextpdf/enterprise, hoặc 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

Nếu composer show báo cáo gói và phiên bản của nó, gói riêng tư đã được giải quyết. Chạy lại composer dump-autoload rồi tái tạo bộ tải tự động một cách sạch sẽ, để các lớp của gói có thể được phát hiện:

composer dump-autoload

Như một kiểm tra tùy chọn ở mức mã, bạn có thể xác nhận rằng một lớp từ phiên bản đã cài tải tự động được. Đừng đoán tên lớp: hãy mở tham chiếu API cho phiên bản bạn đã cài và chọn bất kỳ lớp công khai nào được tài liệu hóa, rồi kiểm tra xem nó có giải quyết được không. Lớp cần tìm phụ thuộc vào phiên bản của bạn — một lớp có trong một phiên bản có thể không có ở phiên bản khác, và việc một lớp duy nhất tải tự động được chỉ chứng minh phiên bản của nó hiện diện, không phải mọi phiên bản đều đã được cài.

<?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));

Cài đặt gói không giống với kích hoạt nó. Bản thân gói không cấp năng lực Pro hay Enterprise — giấy phép đã ký mà bạn kích hoạt mới chọn phiên bản đang hoạt động. Sau khi cài đặt thành công, hãy theo Cấp phép và kích hoạt để đặt và kích hoạt phong bì giấy phép, và, với các bản dựng mã hóa bằng ionCube, hãy thiết lập ionCube Loader.

Khắc phục sự cố

401 Unauthorized hoặc 403 Forbidden

Composer đã tới được kho nhưng thông tin xác thực bị từ chối hoặc không đủ. Hãy xác nhận khóa host trong auth.json / COMPOSER_AUTH khớp chính xác với host kho (không có scheme, không có path, không có dấu gạch chéo cuối), rằng tên đăng nhập và mã truy cập còn hiệu lực, và rằng mã truy cập chưa hết hạn hay đã bị luân chuyển trong cổng của bạn. Một 401 chỉ ra thông tin xác thực sai hoặc thiếu; một 403 chỉ ra một thông tin xác thực hợp lệ nhưng phạm vi của nó không bao gồm gói hay phiên bản bạn yêu cầu — hãy kiểm tra rằng đăng ký của bạn cho phép tên gói bạn đang require.

Không tìm thấy gói / “could not find a matching version”

Điều này thường có nghĩa Composer đã không dùng hoặc không tới được chỉ mục riêng tư (nên nó chỉ tìm trong Packagist công khai), hoặc nó tới được chỉ mục nhưng không tìm thấy gói hay phiên bản nào có thể cài đặt mà khớp. Hãy xác nhận khối repositories.nextpdf tồn tại trong composer.json của chính dự án này với "type": "composer" và URL đúng, và rằng bạn đang require đúng tên gói (nextpdf/pro, nextpdf/enterprise, hoặc nextpdf/premium). Chạy composer config repositories để in ra những gì Composer thấy. Một lỗi gõ trong URL hoặc thiếu khối kho là nguyên nhân phổ biến, nhưng cũng hãy kiểm tra rằng ràng buộc phiên bản của bạn khớp với một phiên bản đã công bố, rằng yêu cầu nền tảng PHP của dự án (và minimum-stability) cho phép gói, và rằng quyền của mã truy cập thực sự bao gồm gói bạn đang require.

Mã truy cập hoạt động cục bộ nhưng thất bại trong CI

Tệp auth.json cục bộ không có mặt trên runner. Hãy đặt COMPOSER_AUTH từ kho bí mật CI của bạn (Phương thức B) thay vì dựa vào một tệp, và đảm bảo biến được export trước khi composer install chạy. Trong các bản dựng container hóa, hãy truyền secret tại thời điểm build mà không lưu nó vào một lớp ảnh.

Khóa host sai

Thông tin xác thực được khớp theo host. Nếu URL kho là https://repo.example.com/nextpdf, khóa phải là repo.example.com — không phải URL đầy đủ và không phải một đường con. Một khóa không khớp khiến Composer gửi yêu cầu mà không xác thực, biểu hiện ra dưới dạng một lỗi 401.