Manage custom domain names for a bucket using the PHP SDK - Object Storage Service

OSS automatically generates URLs for uploaded objects using the bucket's public endpoint. To serve objects under your own domain — for example, to support branded URLs, CDN integration, or HTTPS with your own certificate — map a custom domain name to the bucket by adding a CNAME record.

To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint instead of a custom domain. For supported regions and endpoints, see Regions and endpoints.

Prerequisites

Before you begin, make sure you have:

An OSS bucket
An AccessKey ID and AccessKey secret
A registered custom domain name
The OSS PHP SDK V2 installed

Create a CnameToken

Before binding a custom domain, create a CnameToken to verify that you own the domain.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        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);

// Create a CnameToken for domain ownership verification.
$request = new Oss\Models\CreateCnameTokenRequest(
    bucket: $bucket,
    bucketCnameConfiguration: new Oss\Models\BucketCnameConfiguration(
        cname: new Oss\Models\Cname(
            domain: 'example.com' // Replace with your custom domain name.
        )
    )
);

$result = $client->createCnameToken($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'cname token:' . var_export($result->cnameToken, true) . PHP_EOL
);

Get a CnameToken

Retrieve an existing CnameToken for a custom domain.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

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

$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\GetCnameTokenRequest(
    bucket: $bucket,
    cname: 'example.com' // Replace with your custom domain name.
);

$result = $client->getCnameToken($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'cname token:' . var_export($result->cnameToken, true) . PHP_EOL
);

Add a CNAME record

All examples in this section use PutCname to bind a custom domain to a bucket. Use the first example for a basic domain mapping, or the second to attach an SSL certificate at the same time.

Map a custom domain name

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

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

$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(config: $cfg);

$request = new Oss\Models\PutCnameRequest(
    bucket: $bucket,
    bucketCnameConfiguration: new Oss\Models\BucketCnameConfiguration(
        cname: new Oss\Models\Cname(
            domain: 'example.com' // Replace with your custom domain name.
        )
    )
);

$result = $client->putCname($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId
);

Map a custom domain name and attach a certificate

To enable HTTPS for the custom domain, include a CertificateConfiguration in the same PutCname call.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

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

$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(config: $cfg);

$request = new Oss\Models\PutCnameRequest(
    bucket: $bucketName,
    bucketCnameConfiguration: new Oss\Models\BucketCnameConfiguration(
        cname: new Oss\Models\Cname(
            domain: 'www.example.com', // Replace with your custom domain name.
            certificateConfiguration: new Oss\Models\CertificateConfiguration(
                force: true,                             // Set to true to overwrite an existing certificate.
                certId: '92******-cn-hangzhou',          // Replace with your certificate ID.
                certificate: '-----BEGIN CERTIFICATE-----MIIFBzCCA++gT2H2hT6Wb3nwxjpLIfXmSVcV*****-----END CERT', // Replace with your certificate content.
                privateKey: '-----BEGIN CERTIFICATE-----MIIFBzCCA++gT2H2hT6Wb3nwxjpLIfXmSVcV*****-----END CERTIFICATE-----' // Replace with your private key content.
            )
        )
    )
);

$result = $client->putCname($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId
);

Replace the following placeholders before running the code:

Placeholder	Description
`92******-cn-hangzhou`	Your certificate ID
`-----BEGIN CERTIFICATE-----...`	Your certificate content (PEM format)
`-----BEGIN CERTIFICATE-----...` (private key)	Your private key content (PEM format)

Detach a certificate

If you no longer want to use a certificate for a custom domain, you can detach the certificate by setting deleteCertificate to true in a PutCname call.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

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

$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(config: $cfg);

$request = new Oss\Models\PutCnameRequest(
    bucket: $bucketName,
    bucketCnameConfiguration: new Oss\Models\BucketCnameConfiguration(
        cname: new Oss\Models\Cname(
            domain: 'www.example.com', // Replace with your custom domain name.
            certificateConfiguration: new Oss\Models\CertificateConfiguration(
                deleteCertificate: true // Detach the certificate from this domain.
            )
        )
    )
);

$result = $client->putCname($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId
);

List CNAME records

List all custom domains bound to a bucket to verify the current configuration.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

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

$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\ListCnameRequest(
    bucket: $bucket
);

$result = $client->listCname($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'cnames:' . var_export($result->cnames, true) . PHP_EOL
);

Delete a CNAME record

The following code provides an example of how to delete a CNAME record.

<?php

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

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

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

$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\DeleteCnameRequest(
    bucket: $bucket,
    bucketCnameConfiguration: new Oss\Models\BucketCnameConfiguration(
        cname: new Oss\Models\Cname(
            domain: 'example.com' // Replace with the custom domain name to remove.
        )
    )
);

$result = $client->deleteCname($request);

printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId
);

API reference

Operation	API
Create a CnameToken	CreateCnameToken
Get a CnameToken	GetCnameToken
Add a CNAME record	PutCname
List CNAME records	ListCname
Delete a CNAME record	DeleteCname