========================================================================
    phpQ ENTERPRISE INSTALLATION & USAGE GUIDE FOR UBUNTU LINUX
    Certified: Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS (x64)
    Supported PHP Runtimes: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4
========================================================================

This manual consists of two sections:
  - PART 1: Installing RUNTIME LOADER (phpQ-nts.so) to run encoded applications
  - PART 2: Installing COMPILER (phpQ) to encode projects & issue licenses

========================================================================
PART 1: INSTALLING LOADER (phpQ-nts.so) FOR PRODUCTION SERVERS
========================================================================
(Follow these steps on client / production web servers running protected code)

STEP 1: DEPLOY LOADER BINARY TO SYSTEM DIRECTORY
------------------------------------------------------------------------
Copy "phpQ-nts.so" to your Ubuntu server and run:

  sudo mkdir -p /usr/local/lib/phpq
  sudo cp phpQ-nts.so /usr/local/lib/phpq/phpQ-nts.so
  sudo chmod 755 /usr/local/lib/phpq/phpQ-nts.so


STEP 2: CONFIGURE PHP EXTENSION (UBUNTU / DEBIAN STANDARD)
------------------------------------------------------------------------
Run the following commands (automatically detects active PHP version):

  PHP_VER=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
  sudo bash -c "echo 'extension=/usr/local/lib/phpq/phpQ-nts.so' > /etc/php/$PHP_VER/mods-available/phpq.ini"
  sudo phpenmod phpq


STEP 3: RESTART WEB SERVER & PHP-FPM
------------------------------------------------------------------------
* For NGINX + PHP-FPM:
  sudo systemctl restart php$PHP_VER-fpm

* For APACHE:
  sudo systemctl restart apache2


STEP 4: VERIFY INSTALLATION
------------------------------------------------------------------------
Run the following verification command in Terminal:

  php -m | grep phpq

If the output prints "phpq", the loader is loaded and active (100% functional)!


STEP 5: QUERY SERVER HARDWARE MACHINE ID (IF REQUIRED)
------------------------------------------------------------------------
If your software vendor issues hardware-locked licenses:
Run this command on your Ubuntu server:

  php -r "echo phpq_machine_id() . PHP_EOL;"

Copy the resulting 64-character SHA-256 hash and send it to your vendor
to receive your customized "web.lic" license key.


========================================================================
PART 2: INSTALLING & USING phpQ COMPILER ON UBUNTU LINUX
========================================================================
(For developers / CI-CD servers encoding PHP applications on Linux)

STEP 1: INSTALL PHP CLI (IF NOT ALREADY PRESENT)
------------------------------------------------------------------------
phpQ runs on the local system PHP CLI engine:

  sudo apt update
  sudo apt install -y php-cli


STEP 2: INSTALL phpQ EXECUTABLE INTO SYSTEM PATH
------------------------------------------------------------------------
Copy the "phpQ" native binary to /usr/local/bin:

  sudo cp phpQ /usr/local/bin/phpq
  sudo chmod +x /usr/local/bin/phpq

Verify by running:
  phpq --help


STEP 3: PRACTICAL CLI COMMANDS & WORKFLOWS
------------------------------------------------------------------------

1. BUILD ENTIRE PROJECT FROM CONFIG FILE (protect.txt):
   Run in the directory containing protect.txt:

     phpq protect.txt

   * Override source and target directories on the fly:
     phpq protect.txt -s /var/www/source -t /var/www/dist


2. RAPID ENCODING FOR A SINGLE FILE:
   Syntax: phpq encode -i <source_file> -o <target_file>

   Example:
     phpq encode -i index.php -o index_encrypted.php

   * Encode with AST obfuscation and comment stripping:
     phpq encode --obfuscate --strip -i index.php -o index_encrypted.php


3. ENCODE WITH HARDWARE MACHINE ID LOCK:
   phpq encode --machine-id b857dbc162a4e36aca703dcd3008336b324e60bb87306f285090285c7b9829b1 -i app.php -o app_locked.php


4. ENCODE WITH EXPIRATION DATE LOCK:
   phpq encode --expire "2027-12-31" -i app.php -o app_expired.php


5. GENERATE OFFLINE ASYMMETRIC LICENSE (web.lic):
   Syntax:
     phpq license --project-id <ID> --project-key <KEY> -o <path/web.lic> [options]

   Example: Issue license locking Domain and Expiration:
     phpq license --project-id "MY_APP" --project-key "MY_SECRET_KEY" --domain "client.com" --expire "2027-12-31" -o /var/www/web.lic


6. DISPLAY CURRENT SERVER MACHINE ID:
     phpq machine-id


7. INSPECT RUNTIME LOADER DIAGNOSTICS:
     phpq info

========================================================================