Import files from Backblaze in PHP with the Native API

Kevin van Zonneveld

Co-founder · Amsterdam, The Netherlands ·

Backblaze B2’s Native API is an HTTP API, so PHP’s open-source cURL extension is enough to import an object without relying on a wrapper. This example authorizes with API v4 and streams one private object to disk. It limits both responses and only publishes the destination after a complete download.

Requirements

PHP 8.1 or later with ext-curl
A B2 application key with readFiles access
The application key ID and application key; these are different values

$ php -r "exit(extension_loaded('curl') ? 0 : 1);"

Use the B2 Native API

Save this as import-b2.php. It never follows redirects, so credentials cannot be forwarded to a redirect target. It accepts HTTPS endpoints, plus loopback HTTP endpoints for local tests.

Import one object

<?php
declare(strict_types=1);

final class CurlTransport
{
    private const MAX_AUTH_BYTES = 1_048_576;

    /** @return array<string, mixed> */
    public function authorize(string $url, string $keyId, string $applicationKey): array
    {
        $this->assertSafeUrl($url);
        $body = '';
        $curl = curl_init($url);
        if ($curl === false) {
            throw new RuntimeException('Could not initialize cURL');
        }
        try {
            if (!curl_setopt_array($curl, [
                CURLOPT_FOLLOWLOCATION => false,
                CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
                CURLOPT_PROTOCOLS => CURLPROTO_HTTP | CURLPROTO_HTTPS,
                CURLOPT_TIMEOUT => 20,
                CURLOPT_USERPWD => $keyId . ':' . $applicationKey,
                CURLOPT_WRITEFUNCTION => static function ($handle, string $chunk) use (&$body): int {
                    if (strlen($body) + strlen($chunk) > self::MAX_AUTH_BYTES) {
                        return 0;
                    }
                    $body .= $chunk;
                    return strlen($chunk);
                },
            ])) {
                throw new RuntimeException('Could not configure cURL');
            }
            $ok = curl_exec($curl);
            $status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
            if ($ok !== true || $status !== 200) {
                throw new RuntimeException("B2 authorization failed with HTTP {$status}");
            }
        } finally {
            unset($curl);
        }
        $decoded = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
        if (!is_array($decoded)) {
            throw new RuntimeException('B2 returned an invalid authorization response');
        }
        return $decoded;
    }

    /** @param resource $output */
    public function download(string $url, string $token, $output, int $maxBytes): void
    {
        $this->assertSafeUrl($url);
        $written = 0;
        $curl = curl_init($url);
        if ($curl === false) {
            throw new RuntimeException('Could not initialize cURL');
        }
        try {
            if (!curl_setopt_array($curl, [
                CURLOPT_FOLLOWLOCATION => false,
                CURLOPT_HTTPHEADER => ['Authorization: ' . $token],
                CURLOPT_PROTOCOLS => CURLPROTO_HTTP | CURLPROTO_HTTPS,
                CURLOPT_TIMEOUT => 300,
                CURLOPT_WRITEFUNCTION => static function ($handle, string $chunk) use (
                    $output,
                    $maxBytes,
                    &$written,
                ): int {
                    $length = strlen($chunk);
                    if ($written + $length > $maxBytes) {
                        return 0;
                    }
                    $result = fwrite($output, $chunk);
                    if ($result !== $length) {
                        return 0;
                    }
                    $written += $result;
                    return $result;
                },
            ])) {
                throw new RuntimeException('Could not configure cURL');
            }
            $ok = curl_exec($curl);
            $status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
            if ($ok !== true || $status !== 200) {
                throw new RuntimeException("B2 download failed with HTTP {$status}");
            }
        } finally {
            unset($curl);
        }
    }

    private function assertSafeUrl(string $url): void
    {
        $scheme = parse_url($url, PHP_URL_SCHEME);
        $host = parse_url($url, PHP_URL_HOST);
        $loopback = $scheme === 'http' && in_array($host, ['127.0.0.1', '::1'], true);
        if ($scheme !== 'https' && !$loopback) {
            throw new RuntimeException('B2 endpoints must use HTTPS');
        }
    }
}

/** @param array<string, mixed> $authorization */
function requiredString(array $authorization, string $key): string
{
    $value = $authorization[$key] ?? null;
    if (!is_string($value) || $value === '') {
        throw new RuntimeException("B2 authorization response is missing {$key}");
    }
    return $value;
}

function encodeObjectName(string $objectName): string
{
    $segments = explode('/', $objectName);
    if (in_array('.', $segments, true) || in_array('..', $segments, true)) {
        throw new InvalidArgumentException('Object names cannot contain dot path segments');
    }
    return implode('/', array_map('rawurlencode', $segments));
}

function importB2Object(
    CurlTransport $transport,
    string $authorizeUrl,
    string $keyId,
    string $applicationKey,
    string $bucket,
    string $objectName,
    string $destination,
    int $maxBytes,
): void {
    if ($maxBytes < 1 || $bucket === '' || $objectName === '') {
        throw new InvalidArgumentException('Bucket, object name, and a positive limit are required');
    }
    $authorization = $transport->authorize($authorizeUrl, $keyId, $applicationKey);
    $apiInfo = $authorization['apiInfo'] ?? null;
    $storageApi = is_array($apiInfo) ? ($apiInfo['storageApi'] ?? null) : null;
    if (!is_array($storageApi)) {
        throw new RuntimeException('B2 authorization response is missing storageApi');
    }
    $downloadUrl = requiredString($storageApi, 'downloadUrl');
    $token = requiredString($authorization, 'authorizationToken');
    $url = rtrim($downloadUrl, '/') . '/file/' . rawurlencode($bucket) . '/'
        . encodeObjectName($objectName);

    $directory = dirname($destination);
    $realDirectory = realpath($directory);
    if ($realDirectory === false || !is_dir($realDirectory) || !is_writable($realDirectory)) {
        throw new RuntimeException('Destination directory must exist and be writable');
    }
    $temporary = tempnam($realDirectory, '.b2-');
    if ($temporary === false) {
        throw new RuntimeException('Could not create a temporary destination');
    }
    if (dirname($temporary) !== $realDirectory) {
        @unlink($temporary);
        throw new RuntimeException('Temporary file was not created beside the destination');
    }
    $output = fopen($temporary, 'wb');
    if ($output === false) {
        @unlink($temporary);
        throw new RuntimeException('Could not open the temporary destination');
    }
    try {
        $transport->download($url, $token, $output, $maxBytes);
        $flushed = fflush($output);
        $closed = fclose($output);
        $output = null;
        if (!$flushed || !$closed) {
            throw new RuntimeException('Could not finish writing the downloaded object');
        }
        if (!rename($temporary, $destination)) {
            throw new RuntimeException('Could not publish the downloaded object');
        }
    } finally {
        if (is_resource($output)) {
            fclose($output);
        }
        if (file_exists($temporary)) {
            unlink($temporary);
        }
    }
}

function main(array $arguments): void
{
    foreach (['B2_KEY_ID', 'B2_APPLICATION_KEY', 'B2_BUCKET', 'B2_OBJECT'] as $name) {
        if (getenv($name) === false || getenv($name) === '') {
            throw new RuntimeException("Missing environment variable: {$name}");
        }
    }
    $configuredMaxBytes = getenv('B2_MAX_BYTES');
    $maxBytes = filter_var(
        $configuredMaxBytes === false ? 100 * 1024 * 1024 : $configuredMaxBytes,
        FILTER_VALIDATE_INT,
        ['options' => ['min_range' => 1]],
    );
    if ($maxBytes === false) {
        throw new RuntimeException('B2_MAX_BYTES must be a positive integer');
    }
    importB2Object(
        new CurlTransport(),
        getenv('B2_AUTHORIZE_URL') ?: 'https://api.backblazeb2.com/b2api/v4/b2_authorize_account',
        (string) getenv('B2_KEY_ID'),
        (string) getenv('B2_APPLICATION_KEY'),
        (string) getenv('B2_BUCKET'),
        (string) getenv('B2_OBJECT'),
        $arguments[1] ?? (__DIR__ . '/imported-object'),
        $maxBytes,
    );
}

try {
    main($argv);
} catch (Throwable) {
    error_log('B2 import failed');
    exit(1);
}

B2_KEY_ID='your-key-id' \
B2_APPLICATION_KEY='your-application-key' \
B2_BUCKET='my-bucket' \
B2_OBJECT='photos/sunset.jpg' \
php import-b2.php ./sunset.jpg

The 100 MiB limit is application policy. The code retains an existing destination if authorization, download, size validation, disk writing, or rename fails.

Adapt the importer

This focused importer does not list objects or probe for existence. B2 exposes those operations as b2_list_file_names and a HEAD request, but a service that knows both names can download directly.

Secure and efficient file handling

Restrict the key to the required bucket, filename prefix, and readFiles capability.
The key ID is the Basic Auth username; the application key is its password.
Add bounded retries with jitter for 429 and transient 5xx responses in a worker.
Keep the temporary and destination files on the same filesystem so rename() publishes atomically.

Conclusion

The Native API keeps this PHP importer small while using Backblaze’s current v4 authorization contract. For directories or processing pipelines, Transloadit’s Backblaze import Robot can handle the workflow.