All Products
Search

This Product

    Object Storage Service:Hotlink protection using OSS SDK for PHP 2.0

    Document Center

    Object Storage Service:Hotlink protection using OSS SDK for PHP 2.0

    Last Updated:Mar 20, 2026

    Configure bucket-level access control policies based on the Referer request header using OSS SDK for PHP 2.0. Define a Referer whitelist, a Referer blacklist, and the behavior for requests with an empty Referer header to block unauthorized hotlinking and reduce unnecessary data transfer costs.

    Prerequisites

    Before you begin, ensure that you have:

    • An OSS bucket

    • The oss:PutBucketReferer permission to set or clear hotlink protection configurations

    • The oss:GetBucketReferer permission to retrieve hotlink protection configurations

    • OSS SDK for PHP 2.0 installed (vendor/autoload.php available)

    • AccessKey ID and AccessKey secret stored as environment variables

    For information about granting permissions to a RAM user, see Grant custom permissions to a RAM user.

    Usage notes

    • Review how hotlink protection works before configuring it. See Hotlink protection.

    • The examples use the China (Hangzhou) region (cn-hangzhou) with a public endpoint. To access OSS from another Alibaba Cloud service in the same region, specify the internal endpoint. For all supported regions and endpoints, see Regions and endpoints.

    Set hotlink protection

    The following example configures a hotlink protection policy that disallows requests with an empty Referer header and sets a Referer list.

    <?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Parse command-line arguments.
$optsdesc = [
    "region"   => ['help' => 'The region where the bucket is located', 'required' => true],
    "endpoint" => ['help' => 'The endpoint for accessing OSS',         'required' => false],
    "bucket"   => ['help' => 'The name of the bucket',                 'required' => true],
];

$longopts = array_map(fn($key) => "$key:", array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $meta) {
    if ($meta['required'] && empty($options[$key])) {
        echo "Error: --$key is required. {$meta['help']}" . PHP_EOL;
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

// Load credentials from environment variables.
// Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this example.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);

if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

// Build the hotlink protection configuration.
// allowEmptyReferer: false — block requests that have no Referer header.
// refererList: add allowed or blocked Referer values here.
$request = new Oss\Models\PutBucketRefererRequest(
    bucket: $bucket,
    refererConfiguration: new Oss\Models\RefererConfiguration(
        allowEmptyReferer: false,
        refererList: new Oss\Models\RefererList([""]),
    )
);

$result = $client->putBucketReferer($request);
printf(
    "status code: %s" . PHP_EOL .
    "request ID:  %s" . PHP_EOL,
    $result->statusCode,
    $result->requestId
);

    Retrieve hotlink protection settings

    The following example retrieves the current hotlink protection configuration for a bucket.

    <?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Parse command-line arguments.
$optsdesc = [
    "region"   => ['help' => 'The region where the bucket is located', 'required' => true],
    "endpoint" => ['help' => 'The endpoint for accessing OSS',         'required' => false],
    "bucket"   => ['help' => 'The name of the bucket',                 'required' => true],
];

$longopts = array_map(fn($key) => "$key:", array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $meta) {
    if ($meta['required'] && empty($options[$key])) {
        echo "Error: --$key is required. {$meta['help']}" . PHP_EOL;
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

// Load credentials from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);

if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

$request = new Oss\Models\GetBucketRefererRequest(bucket: $bucket);

$result = $client->getBucketReferer($request);
printf(
    "status code:    %s" . PHP_EOL .
    "request ID:     %s" . PHP_EOL .
    "referer config: %s" . PHP_EOL,
    $result->statusCode,
    $result->requestId,
    var_export($result->refererConfiguration, true)
);

    API reference