📖 Documentation

🚀 Getting Started

Prerequisites

Before you begin, ensure you have:

• A valid php-next license (TRIAL, PRO, ULTRA, or ULTRA_V1)
• PHP 7.4 or higher installed (for your original source code)
• Access to your customer dashboard
• Command-line access to your development machine

Quick Start (5 Minutes)

$ php-next-encoder encode yourfile.php output.enc.php --license license.json

✓ Encoded to output.enc.php (687 bytes)
✓ License validated
✓ Build ID: BUILD-ABC123

<?php
// For native loader (PRO/ULTRA/ULTRA_V1)
php_next_run('output.enc.php');

// For DEV loader (development/OSS only)
require 'php-next-loader.php';
PhpNextDevLoader::run('output.enc.php');
?>

📦 Loader Installation

Native Loader (PRO/ULTRA/ULTRA_V1)

The native loader is a compiled PHP extension that provides maximum security and performance for protected blobs.

Linux Installation

1. Download the appropriate loader from /loaders.php:
   • Linux x86_64: php-next-loader-linux-x86_64-v1.0.0.tar.gz
   • Linux ARM64: php-next-loader-linux-arm64-v1.0.0.tar.gz
2. Extract the archive:

   $ tar -xzf php-next-loader-linux-x86_64-v1.0.0.tar.gz
   $ cd php-next-loader-linux-x86_64-v1.0.0

3. Copy the extension to your PHP extensions directory:

   $ sudo cp php_next_loader.so $(php-config --extension-dir)/

4. Enable the extension in php.ini:

   extension=php_next_loader.so

5. Restart PHP-FPM or your web server:

   $ sudo systemctl restart php-fpm
   # or
   $ sudo systemctl restart nginx

6. Verify installation:

   $ php -m | grep php_next_loader
   $ php -r "print_r(php_next_info());"

Windows Installation

1. Download php-next-loader-windows-x86_64-v1.0.0.zip from /loaders.php
2. Extract php_next_loader.dll to your PHP ext/ directory
3. Add to php.ini:

   extension=php_next_loader.dll

4. Restart your web server

DEV Loader (Development/OSS Only)

The DEV loader is a pure PHP implementation for development and open-source blobs. It explicitly blocks PRO/ULTRA/ULTRA_V1 blobs.

1. Clone or download from GitHub
2. Include in your project:

   <?php
   require 'php-next-loader.php';
   PhpNextDevLoader::run('your-blob.enc.php');
   ?>

🛠️ CLI Tools

php-next-encoder

The encoder compiles PHP source code into encrypted RuntimeBlobV2 blobs.

Basic Usage

$ php-next-encoder encode input.php output.enc.php --license license.json

Options

Examples

# Encode with domain lock
$ php-next-encoder encode app.php app.enc.php --license license.json --domain-lock example.com

# Encode with expiration
$ php-next-encoder encode plugin.php plugin.enc.php --license license.json --expires 2025-12-31

# Verbose output
$ php-next-encoder encode file.php file.enc.php --license license.json --verbose

php-next-inspect

Inspect blob metadata without revealing secrets.

$ php-next-inspect blob.enc.php

Blob Information:
  Edition: PRO
  License ID: LIC-PRO-ABCD-1234
  Build ID: BUILD-ABC123
  Size: 687 bytes
  Created: 2025-01-15 10:30:00
  Domain Lock: example.com (if set)
  Expires: Never (if set)

🔑 License Editions

php-next offers four editions, each with different security features and use cases:

Choosing an Edition

• TRIAL: 7-day full PRO features, ideal for testing and evaluation
• PRO: Production-grade protection for commercial projects, compatible with shared hosting
• ULTRA: Maximum security with multi-stream bytecode, ideal for high-value applications
• ULTRA V1: Flagship "zero-knowledge" edition with decoy VM and advanced anti-tamper for regulated industries

❓ FAQ & Troubleshooting

Common Issues

Q: "Loader not found" or "Extension not loaded"

A: Ensure the native loader extension is installed and enabled in your php.ini:

$ php -m | grep php_next_loader
$ php -i | grep extension_dir

If not found, check that:

• The .so or .dll file is in the correct directory
• extension=php_next_loader.so is in your php.ini
• You've restarted PHP-FPM or your web server

Q: "License validation failed"

A: Check that:

• Your license.json file is valid and not corrupted
• The license hasn't expired
• Hardware binding matches (if enabled)
• Domain lock matches (if enabled)

Q: "DEV loader refuses to run PRO blob"

A: This is by design. PRO/ULTRA/ULTRA_V1 blobs require the native loader for security reasons. Use the native loader from /loaders.php.

Q: "Encoding failed" or "Invalid license"

A: Verify:

• Your license file is correctly signed and not tampered with
• You're using the correct encoder binary for your license edition
• The license hasn't been revoked

Q: Performance concerns

A: php-next adds minimal overhead:

• Startup time: ~2ms (decryption + VM initialization)
• Runtime overhead: <5% for typical web applications
• Memory overhead: ~512 KB (VM runtime + state)

For high-traffic applications, consider caching decoded bytecode or using opcode caches.

Getting Help

If you're still experiencing issues:

• Check the white paper for technical details
• Review the changelog for known issues and fixes
• Open an issue on GitHub
• Contact support: support@php-next.com