hejunjie/url-signer

English｜简体中文

---

A PHP library for generating URLs with encryption and signature protection—useful for secure resource access and tamper-proof links.

Built with PHP 8, this library supports SHA256 signing by default and includes built-in AES-256-CBC parameter encryption.

---

✨ Features

• ✅ URL Signing & Verification
• ✅ Signature Expiration Validation
• ✅ Support for Encrypting/Decrypting the file Parameter
• ✅ Auto-Generated Key Configuration (on Installation)
• ✅ No Dependency on Redis, Databases, or Other Services

---

📦 Installation

Install via Composer:

composer require hejunjie/url-signer

A key configuration file will be automatically generated after installation: config/urlsigner.php。

The default configuration file path is config/urlsigner.php, with the following structure:

<?php

return [
    'secretKey' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', // 32-character length string
    'default_expire' => 3600, // Default expiration time (in seconds)
];

🚀 Quick Start

Generate Signed URL

use Hejunjie\UrlSigner\UrlSigner;

$signer = new UrlSigner();
$signedUrl = $signer->sign('https://yourdomain.com/download', [
    'file' => 'path/to/secret.pdf'
]);

echo $signedUrl;
// https://yourdomain.com/download?file=EncryptedContent&_t=Timestamp&_e=ExpirationTime&_sign=Signature

Validate Signed Request

use Hejunjie\UrlSigner\UrlSigner;

$signer = new UrlSigner();

if (!$signer->validate($_GET)) {
    http_response_code(403);
    exit('Invalid request or the link has expired');
}

$file = $signer->decryptParam($_GET['file']);
// Continue processing the file download logic

🧠 Usage Example – Generate a Download Link

Using Webman as an example

1. Create a method for downloading a file:

   <?php
   
   namespace app\controller;
   
   use support\Request;
   use support\Response;
   use Hejunjie\UrlSigner\UrlSigner;
   
   class DownloadController
   {
   
       /**
        * Generic Method for File Download
        * 
        * @param string $path File Path to Download
        * @method GET
        * 
        * @return Response
        */
       public function download(Request $request): Response
       {
           // Get all request parameters
           $param = $request->all();
           // Validate the signature validity
           $urlSigner = new UrlSigner();
           // If a custom `secretKey` is used, it can be passed as configuration when instantiating the class
           // $sign = new UrlSigner([
           //     'secretKey' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', // 32-character length string
           //     'default_expire' => 3600, // Default expiration time (in seconds)
           // ]);
           $sign = $urlSigner->validate($param);
           if ($sign) {
               // If the signature is valid, proceed with the subsequent logic. If there are encrypted parameters, attempt decryption. If successful, continue processing; if failed, return false
               $path = $urlSigner->decryptParam($param['path']);
               if ($path) {
                   // If the path parameter is successfully decrypted, proceed to download the file
                   return response()->download($path);
               }
           }
           return response();
       }
   }

2. Generate a download link, where a download link is needed:

   $url = 'Link to the download method from the first step';
   $path = 'File path to be downloaded';
   
   $urlSigner = new UrlSigner();
   // Generate a download link that expires in 60 seconds
   $download_url = $urlSigner->sign($url, [
       'path' => $urlSigner->encrypt($path)
       // If no encryption is required, the encrypt method does not need to be called, and the decryptParam method does not need to be called in the corresponding parameter retrieval method
   ], 60);
   
   echo $download_url;

🔧 Additional Toolkits (Can be used independently or installed together)

This project was originally extracted from hejunjie/tools. To install all features in one go, feel free to use the all-in-one package:

composer require hejunjie/tools

Alternatively, feel free to install only the modules you need：

hejunjie/utils - A lightweight and practical PHP utility library that offers a collection of commonly used helper functions for files, strings, arrays, and HTTP requests—designed to streamline development and support everyday PHP projects.

hejunjie/cache - A layered caching system built with the decorator pattern. Supports combining memory, file, local, and remote caches to improve hit rates and simplify cache logic.

hejunjie/china-division - Regularly updated dataset of China's administrative divisions with ID-card address parsing. Distributed via Composer and versioned for use in forms, validation, and address-related features

hejunjie/error-log - An error logging component using the Chain of Responsibility pattern. Supports multiple output channels like local files, remote APIs, and console logs—ideal for flexible and scalable logging strategies.

hejunjie/mobile-locator - A mobile number lookup library based on Chinese carrier rules. Identifies carriers and regions, suitable for registration checks, user profiling, and data archiving.

hejunjie/address-parser - An intelligent address parser that extracts name, phone number, ID number, region, and detailed address from unstructured text—perfect for e-commerce, logistics, and CRM systems.

hejunjie/url-signer - A PHP library for generating URLs with encryption and signature protection—useful for secure resource access and tamper-proof links.

hejunjie/google-authenticator - A PHP library for generating and verifying Time-Based One-Time Passwords (TOTP). Compatible with Google Authenticator and similar apps, with features like secret generation, QR code creation, and OTP verification.

hejunjie/simple-rule-engine - A lightweight and flexible PHP rule engine supporting complex conditions and dynamic rule execution—ideal for business logic evaluation and data validation.

👀 All packages follow the principles of being lightweight and practical — designed to save you time and effort. They can be used individually or combined flexibly. Feel free to ⭐ star the project or open an issue anytime!

---

This library will continue to be updated with more practical features. Suggestions and feedback are always welcome — I’ll prioritize new functionality based on community input to help improve development efficiency together.