Laravel Filesystem Qiniu

https://github.com/overtrue/laravel-filesystem-qiniu
Admin
Laravel Filesystem Qiniu is a PHP package that adds a qiniu disk driver to Laravel's Storage,...
Tokens:46,566
Snippets:286
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Usage example for adapter methods and temporary upload URLs

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Shows how to get an upload token, a public URL, and how to customize temporary upload URL building with a closure.

```php
$token = $disk->getAdapter()->getUploadToken('folder/my_file.txt', 3600); // README usage
$disk->getAdapter()->getUrl('folder/my_file.txt');
$disk->buildTemporaryUploadUrlsUsing(fn ($path, $expiration) => [
    'url'     => $disk->getAdapter()->getUploadToken($path, $expiration - time()),
    'headers' => [],
]);
```

--------------------------------

### Wrapper-Level Error Handling with Storage::disk('qiniu')

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/errors.md

When using the wrapper, exceptions are caught and converted to false or null returns unless the disk config sets 'throw' => true. This example shows typical return values for put, get, delete, and copy operations.

```php
$disk = Storage::disk('qiniu');

$ok = $disk->put('a.txt', $data);          // false instead of UnableToWriteFile
$data = $disk->get('missing.txt');         // null instead of UnableToReadFile
$ok = $disk->delete(['a.txt', 'b.txt']);   // false if any path failed
$ok = $disk->copy('a.txt', 'b.txt');       // false on failure
```

--------------------------------

### Write usage examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows various put calls and a direct adapter write with a URL. The URL example uploads remote content via Qiniu's follow-redirect behavior.

```php
$disk->put('avatars/filename.jpg', $fileContents);           // via FilesystemAdapter (Config [] → mime application/octet-stream)
$disk->put('file.md', $contents);                             // put($path, $contents, [])
$disk->put('file.md', $contents, ['visibility' => 'public']); // options string/array → write with Config(mime only read)

$adapter->write('file.md', 'http://httpbin.org/robots.txt', new Config(['mime' => 'application/redirect302']));
```

--------------------------------

### Server-side fetch usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Example of using fetch to download a remote URL into the bucket. On failure (false), falls back to client-side put with file_get_contents.

```php
$file = $disk->getAdapter()->fetch('folder/save_as.txt', 'https://example.com/source.txt');
// server-side fetch: the bucket downloads the URL. $file === false on failure, else API response array
if ($file === false) {
    // retry or fall back to client-side put
    $disk->put('folder/save_as.txt', file_get_contents('https://example.com/source.txt'));
}
```

--------------------------------

### Usage Examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/README.md

Common operations using the Qiniu disk: put, has, lastModified, copy, move, read, fetch, getUrl, getUploadToken, and privateDownloadUrl.

```php
$disk = Storage::disk('qiniu');

// create a file
$disk->put('avatars/filename.jpg', $fileContents);

// check if a file exists
$exists = $disk->has('file.jpg');

// get timestamp
$time = $disk->lastModified('file1.jpg');

// copy a file
$disk->copy('old/file1.jpg', 'new/file1.jpg');

// move a file
$disk->move('old/file1.jpg', 'new/file1.jpg');

// get file contents
$contents = $disk->read('folder/my_file.txt');

// fetch url content
$file = $disk->getAdapter()->fetch('folder/save_as.txt', $fromUrl);

// get file url
$url = $disk->getAdapter()->getUrl('folder/my_file.txt');

// get file upload token
$token = $disk->getAdapter()->getUploadToken('folder/my_file.txt');
$token = $disk->getAdapter()->getUploadToken('folder/my_file.txt', 3600);

// get private url
$url = $disk->getAdapter()->privateDownloadUrl('folder/my_file.txt');
```

--------------------------------

### URL usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Example calls to the URL methods on a disk instance, showing expected outputs and return values for Qiniu.

```php
$url = $disk->url('folder/my_file.txt');        // http://xxx.clouddn.com/folder/my_file.txt
$url = $disk->temporaryUrl('folder/my_file.txt', now()->addMinutes(5));
$disk->providesTemporaryUrls();                 // true
$disk->providesTemporaryUploadUrls();           // false (Qiniu: use getUploadToken instead)
```

--------------------------------

### makeDirectory usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows calling makeDirectory on a disk. It returns true but nothing is created server-side; writes to 'new/prefix/x' still work.

```php
$disk->makeDirectory('new/prefix/');  // true — nothing is created server-side; writes to 'new/prefix/x' still work
```

--------------------------------

### getUrl usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Example of generating a public URL for a file and reading it with file_get_contents. Requires a public bucket for unauthenticated access.

```php
$url = $disk->getAdapter()->getUrl('folder/my_file.txt');
// 'http://xxx.clouddn.com/folder/my_file.txt'
file_get_contents($url); // public read (bucket must be public for this to work unauthenticated)
```

--------------------------------

### Usage example for directory listing and creation

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Shows how to list files, iterate recursively, and create a directory. `makeDirectory` returns true because Qiniu treats directories as implicit.

```php
$all = $disk->files('photos/');          // array<string>
foreach ($disk->allFiles() as $path) { /* recursive */ }
$disk->makeDirectory('new/prefix/');     // true (implicit directories)
```

--------------------------------

### FilesystemAdapter reading usage examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Shows typical usage of the reading methods: get, read, json, download, and response. Note that get returns null when the file is not found, and readStream requires allow_url_fopen.

```php
$contents = $disk->get('folder/my_file.txt');               // string | null
$contents = $disk->read('folder/my_file.txt');              // same underlying driver->read
$data     = $disk->json('config.json');                     // decoded array | null
$disk->download('invoices/2024-01.pdf', 'invoice.pdf');     // HTTP attachment response
$disk->response('img.png', headers: ['X-Cache' => 'hit']);  // inline response
```

--------------------------------

### buildTemporaryUrlsUsing(Closure $callback)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Installs a Closure URL builder for temporary URLs.

```APIDOC
## buildTemporaryUrlsUsing(Closure $callback)

### Description
Installs a Closure URL builder for temporary URLs.

### Method
buildTemporaryUrlsUsing

### Parameters
- **$callback** (Closure) - Required - The callback to build temporary URLs.
```

--------------------------------

### Usage examples for existence checks

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Example calls for checking file and directory existence. `$disk->has('file.jpg')` is resolved via `__call` to `driver->has` and returns true/false as shown in the README.

```php
$disk->has('file.jpg');              // true/false — README usage; resolved via __call → driver->has
$disk->fileExists('file.jpg');
$disk->directoryExists('folder/');
```

--------------------------------

### Usage examples for prepend, append, delete, copy, move

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Shows how to call the filesystem methods for prepending, appending, deleting (single or multiple), copying, and moving files. The delete method accepts a string, array, or variadic arguments.

```php
$disk->prepend('logs/app.log', '--- new session ---');
$disk->append('logs/app.log', 'line');
$disk->delete('old/file1.jpg');                // single
$disk->delete(['a.txt', 'b.txt']);             // multiple; variadic form also allowed
$disk->copy('old/file1.jpg', 'new/file1.jpg');
$disk->move('old/file1.jpg', 'new/file1.jpg');
```

--------------------------------

### Existence check usage examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows how to check file and directory existence via the FilesystemAdapter. directoryExists returns false unless a file with the exact path exists.

```php
$disk->has('file.jpg');             // FilesystemAdapter → Filesystem::has (fileExists || directoryExists)
$disk->directoryExists('folder/');  // false unless a file 'folder/' literally exists
```

--------------------------------

### setVisibility usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows calling setVisibility on a disk. It returns false via FilesystemAdapter (exception caught+reported) or throws with 'throw'.

```php
$disk->setVisibility('f.txt', 'public');  // → false via FilesystemAdapter (exception caught+reported), or throws with 'throw'
```

--------------------------------

### privateDownloadUrl usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Generates a signed private download URL with a configurable expiration in seconds. Default is 3600 seconds.

```php
$url = $disk->getAdapter()->privateDownloadUrl('folder/my_file.txt');      // 3600s
$url = $disk->getAdapter()->privateDownloadUrl('folder/my_file.txt', 7200); // 2h
redirect($url);
```

--------------------------------

### buildTemporaryUploadUrlsUsing(Closure $callback)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Installs a Closure URL builder for temporary upload URLs.

```APIDOC
## buildTemporaryUploadUrlsUsing(Closure $callback)

### Description
Installs a Closure URL builder for temporary upload URLs.

### Method
buildTemporaryUploadUrlsUsing

### Parameters
- **$callback** (Closure) - Required - The callback to build temporary upload URLs.
```

--------------------------------

### put and putFile usage examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Usage examples from the README: put with file contents, put with a URL (fetched server-side by Qiniu), and putFile returning the stored path or false.

```php
$disk->put('avatars/filename.jpg', $fileContents);                 // README usage
$disk->put('remote/robots.txt', 'http://httpbin.org/robots.txt');  // Qiniu: string contents uploaded (URL fetched server-side)
$path = $disk->putFile('files/photo.jpg', $uploadedFile);          // path or false
```

--------------------------------

### Install via Composer

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/README.md

Install the package using Composer. Requires Laravel >= 9.0.

```shell
$ composer require "overtrue/laravel-filesystem-qiniu"
```

--------------------------------

### Upload token usage examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Examples of generating upload tokens: bucket-wide, scoped to a single key, and with custom policy. The token can be handed to a client for direct PUT to https://up.qiniup.com.

```php
$token = $disk->getAdapter()->getUploadToken();                 // bucket-wide, 3600s
$token = $disk->getAdapter()->getUploadToken('folder/x.jpg');   // scoped to one key
$token = $disk->getAdapter()->getUploadToken('folder/x.jpg', 7200, [
    'callbackUrl' => 'https://app.example.com/upload-callback',
    'callbackBody' => 'key=$(key)&hash=$(etag)&size=$(fsize)',
]);
// hand $token to a client; it can PUT directly to https://up.qiniup.com with the token
```

--------------------------------

### CDN cache refresh usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Example of refreshing a single URL or a batch of URLs. Both are converted to full URLs before the refresh call.

```php
$adapter->refresh('index.html');          // single
$adapter->refresh(['a.css', 'b.js']);     // batch — both are converted to full URLs first
```

--------------------------------

### Get configured bucket name (QiniuAdapter::getBucket)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Returns the bucket name configured for the adapter, which is the promoted constructor property. Example usage: $bucket = $adapter->getBucket(); // e.g. 'test'

```php
public function getBucket(): string   // src/QiniuAdapter.php:301
```

```php
$bucket = $adapter->getBucket(); // e.g. 'test'
```

--------------------------------

### Metadata retrieval usage example

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows retrieving mimeType, fileSize, and lastModified attributes from an adapter. The returned FileAttributes are built by normalizeFileInfo, with lastModified floored to Unix seconds.

```php
$attributes = $adapter->mimeType('img/photo.jpg');
$attributes->mimeType();      // e.g. 'image/jpeg'
$adapter->fileSize('a.bin')->fileSize();   // bytes
$adapter->lastModified('a.bin')->lastModified(); // unix seconds
```

--------------------------------

### Local Development Commands

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/AGENTS.md

Run composer install, tests, and style checks for this Laravel filesystem package.

```bash
composer install
composer test
composer check-style
```

--------------------------------

### Usage examples for metadata methods

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Shows how to retrieve file size, last modified time, MIME type, and visibility. Note that getVisibility never returns for Qiniu and throws or reports an error.

```php
$size = $disk->size('file.jpg');
$time = $disk->lastModified('file1.jpg');       // unix seconds (int)
$mime = $disk->mimeType('file.jpg');            // 'image/jpeg' | false
$visibility = $disk->getVisibility('file.jpg'); // never returns for qiniu — throws/reports
```

--------------------------------

### Register Service Provider in config/app.php

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/README.md

Add the service provider to the providers array in Laravel's config/app.php file.

```php
'providers' => [
    // Other service providers...
    Overtrue\LaravelFilesystem\Qiniu\QiniuStorageServiceProvider::class,
],
```

--------------------------------

### providesTemporaryUploadUrls()

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Checks whether the adapter supports temporary upload URLs. Returns true if the adapter has a temporaryUploadUrl method or a callback is installed. For Qiniu, this returns false because the adapter does not have such a method.

```APIDOC
## [GET] providesTemporaryUploadUrls()

### Description
Checks whether the adapter supports temporary upload URLs. Returns true if the adapter has a temporaryUploadUrl method or a callback is installed. For Qiniu, this returns false because the adapter does not have such a method.

### Method
GET

### Endpoint
providesTemporaryUploadUrls()

### Parameters
None

### Request Example
```php
$disk->providesTemporaryUploadUrls();
```

### Response
#### Success Response (200)
- **bool** - True if temporary upload URLs are supported, false otherwise.

#### Response Example
```
false
```
```

--------------------------------

### League\Flysystem\Config class definition

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/types.md

Defines the Config class from league/flysystem 3.32.0 with option constants and methods. The constructor accepts an optional array of options; get() falls back to a default value. Methods like extend() and withDefaults() return new Config instances.

```php
class Config
{
    public const OPTION_COPY_IDENTICAL_PATH = 'copy_destination_same_as_source';
    public const OPTION_MOVE_IDENTICAL_PATH = 'move_destination_same_as_source';
    public const OPTION_VISIBILITY = 'visibility';
    public const OPTION_DIRECTORY_VISIBILITY = 'directory_visibility';
    public const OPTION_RETAIN_VISIBILITY = 'retain_visibility';

    public function __construct(private array $options = []) {}
    public function get(string $property, $default = null)          // $options[$property] ?? $default
    public function extend(array $options): Config                  // merge, new Config
    public function withDefaults(array $defaults): Config           // $this->options + $defaults
    public function toArray(): array
    public function withSetting(string $property, mixed $setting): Config
    public function withoutSettings(string ...$settings): Config
}
```

--------------------------------

### Instantiate QiniuAdapter with environment variables

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows how to create a QiniuAdapter using environment variables, matching what QiniuStorageServiceProvider::boot() builds internally, and how to use it directly without Laravel.

```php
use Overtrue\Flysystem\Qiniu\QiniuAdapter;

// Exactly what QiniuStorageServiceProvider::boot() builds internally
$adapter = new QiniuAdapter(
    env('QINIU_ACCESS_KEY', 'xxxxxxxx'),
    env('QINIU_SECRET_KEY', 'xxxxxxxx'),
    env('QINIU_BUCKET', 'test'),
    env('QINIU_DOMAIN', 'https://xxx.clouddn.com')
);

// Use directly without Laravel
$fs = new League\Flysystem\Filesystem($adapter);
```

--------------------------------

### boot() method signature

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuStorageServiceProvider.md

The boot() method registers the Qiniu filesystem driver by calling app('filesystem')->extend('qiniu', closure). It does not override register(), so registration happens during the boot phase.

```php
public function boot()
```

--------------------------------

### __construct

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Creates a new QiniuAdapter instance with the provided Qiniu credentials and bucket configuration. No validation or I/O occurs during construction; all managers are created lazily.

```APIDOC
## __construct

### Description
Creates a new QiniuAdapter instance with the provided Qiniu credentials and bucket configuration. No validation or I/O occurs during construction; all managers are created lazily.

### Method
Constructor

### Signature
```php
public function __construct(
    protected string $accessKey,
    protected string $secretKey,
    protected string $bucket,
    protected string $domain
)
```

### Parameters
- **$accessKey** (string) - Required - Qiniu AccessKey (account credential)
- **$secretKey** (string) - Required - Qiniu SecretKey (account credential)
- **$bucket** (string) - Required - Qiniu bucket name; operations target this bucket
- **$domain** (string) - Required - Public CDN/bucket domain; may or may not include `http://`/`https://` scheme

### Return
New adapter instance. No validation or I/O occurs; all managers are created lazily.

### Throws
Nothing.

### Behavioral Note
`domain` without a scheme is normalized to `http://` during `getUrl()` (see `normalizeHost`, QiniuAdapter-extended).

### Source
`src/QiniuAdapter.php:29-35`

### Examples
```php
use Overtrue\Flysystem\Qiniu\QiniuAdapter;

// Exactly what QiniuStorageServiceProvider::boot() builds internally
$adapter = new QiniuAdapter(
    env('QINIU_ACCESS_KEY', 'xxxxxxxx'),
    env('QINIU_SECRET_KEY', 'xxxxxxxx'),
    env('QINIU_BUCKET', 'test'),
    env('QINIU_DOMAIN', 'https://xxx.clouddn.com')
);

// Use directly without Laravel
$fs = new League\Flysystem\Filesystem($adapter);
```

```php
// Error handling: adapter methods throw League\Flysystem exceptions; surface them explicitly
try {
    $adapter->write('logs/error.log', "boom", new Config());
} catch (League\Flysystem\UnableToWriteFile $e) {
    // $e->location() === 'logs/error.log'; $e->reason() === Qiniu API error message
    report($e->reason());
}
```
```

--------------------------------

### Using move and copy via FilesystemAdapter

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows how to move and copy files using the FilesystemAdapter. These methods return true or false, with exceptions caught by the adapter.

```php
$disk->move('old/file1.jpg', 'new/file1.jpg');   // true | false (FilesystemAdapter catch)
$disk->copy('old/file1.jpg', 'new/file1.jpg');
```

--------------------------------

### Using listContents via FilesystemAdapter

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Shows how to list files and directories using the FilesystemAdapter. The files() method filters to files only; directories() returns directories.

```php
foreach ($disk->files('photos/') as $file) {    // FilesystemAdapter::files → driver->listContents(...)->filter(isFile)
    echo $file;
}
$names = $disk->directories('prefix/');
```

--------------------------------

### Explicit registration via the manager (equivalent to boot())

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuStorageServiceProvider.md

Manually extends the filesystem manager with a custom Qiniu driver creator, equivalent to what boot() does. The closure creates a QiniuAdapter and wraps it in a FilesystemAdapter.

```php
use Illuminate\Support\Facades\Storage;
use Overtrue\Flysystem\Qiniu\QiniuAdapter;
use League\Flysystem\Filesystem;
use Illuminate\Filesystem\FilesystemAdapter;

app('filesystem')->extend('qiniu', function ($app, $config) {
    $adapter = new QiniuAdapter(
        $config['access_key'], $config['secret_key'],
        $config['bucket'], $config['domain']
    );

    return new FilesystemAdapter(new Filesystem($adapter), $adapter, $config);
});

$disk = Storage::disk('qiniu');
```

--------------------------------

### serve(Request $request, $path, $name = null, array $headers = [])

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Serves a file as an HTTP response, optionally using a custom 'serveUsing' callback if set. Otherwise, delegates to the `response` method.

```APIDOC
## serve(Request $request, $path, $name = null, array $headers = [])

### Description
Serves a file as an HTTP response, optionally using a custom 'serveUsing' callback if set. Otherwise, delegates to the `response` method.

### Method
`serve`

### Parameters
- `$request` (Illuminate\Http\Request) - Required - The incoming HTTP request.
- `$path` (string) - Required - The path to the file.
- `$name` (string|null) - Optional - The name to use in the Content-Disposition header (default: null).
- `$headers` (array) - Optional - Additional HTTP headers (default: []).

### Returns
- `StreamedResponse` - The streamed response.

### Behavior
Uses the `serveUsing` callback if set, otherwise calls `response(...)`.

### Example
```php
$disk->serve($request, 'file.txt');
```
```

--------------------------------

### Add Qiniu Disk Configuration

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/README.md

Add a new disk configuration to config/filesystems.php. Uses environment variables for credentials.

```php
<?php

return [
   'disks' => [
        //...
        'qiniu' => [
           'driver'     => 'qiniu',
           'access_key' => env('QINIU_ACCESS_KEY', 'xxxxxxxxxxxxxxxx'),
           'secret_key' => env('QINIU_SECRET_KEY', 'xxxxxxxxxxxxxxxx'),
           'bucket'     => env('QINIU_BUCKET', 'test'),
           'domain'     => env('QINIU_DOMAIN', 'xxx.clouddn.com'), // or host: https://xxxx.clouddn.com
        ],
        //...
    ]
];
```

--------------------------------

### getTemporaryUrl safe expiry normalization

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

If the computed expiration is <= 0, it falls back to 3600 seconds. This example shows an already-expired value.

```php
// Safe expiry normalization: an already-expired/zero value falls back to 3600s
$url = $adapter->getTemporaryUrl('doc/private.pdf', time() - 10); // expires <= 0 → 3600s
```

--------------------------------

### move and copy method signatures

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Defines the adapter's move and copy methods. Both accept a Config parameter that is ignored. They throw exceptions on failure.

```php
public function move(string $source, string $destination, Config $config): void   // src/QiniuAdapter.php:174
public function copy(string $source, string $destination, Config $config): void   // src/QiniuAdapter.php:182
```

--------------------------------

### get($path)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Reads the contents of a file at the given path. Returns the file content as a string, or null if the file cannot be read.

```APIDOC
## get($path)

### Description
Reads the contents of a file at the given path. Returns the file content as a string, or null if the file cannot be read.

### Method
`get`

### Parameters
- `$path` (string) - Required - The path to the file.

### Returns
- `string|null` - The file contents, or null if the file cannot be read.

### Behavior
Calls `driver->read($path)`. Returns null when `UnableToReadFile` is caught (unless `throw` is set).

### Example
```php
$contents = $disk->get('folder/my_file.txt');
```
```

--------------------------------

### serveUsing(Closure $callback)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Overrides the response building for the serve() method with a custom callback.

```APIDOC
## serveUsing(Closure $callback)

### Description
Overrides the response building for the serve() method with a custom callback.

### Method
serveUsing

### Parameters
- **$callback** (Closure) - Required - The callback to build the response.
```

--------------------------------

### getTemporaryUrl usage examples

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Shows different expiration types: DateTime, relative seconds, and absolute epoch. The method normalizes expiration to seconds.

```php
$url = $disk->temporaryUrl('doc/private.pdf', now()->addMinutes(30));       // DateTime → 30-min window
$url = $adapter->getTemporaryUrl('doc/private.pdf', 86400);                // relative: 24h
$url = $adapter->getTemporaryUrl('doc/private.pdf', time() + 60);          // absolute epoch → 60s
```

--------------------------------

### Using Config with QiniuAdapter::write

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/types.md

Shows how to create a Config with a custom mime setting and pass it to QiniuAdapter::write. The adapter reads only the 'mime' key, defaulting to 'application/octet-stream'.

```php
use League\Flysystem\Config;

$config = (new Config)->withSetting('mime', 'image/png')->toArray(); // ['mime' => 'image/png']
$adapter->write('i.png', $bytes, $config);
```

--------------------------------

### mimeType(string $path): FileAttributes

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Retrieves the MIME type of a file. Uses the `stat` operation to get metadata; if the MIME type is null, throws an exception.

```APIDOC
## mimeType(string $path): FileAttributes

### Description
Retrieves the MIME type of a file. Uses the `stat` operation to get metadata; if the MIME type is null, throws an exception.

### Method
mimeType

### Parameters
- **$path** (string) - Required - The file path.

### Returns
- `League\Flysystem\FileAttributes` - Contains the MIME type attribute.

### Exceptions
- If `mimeType` attribute is `null`, throws `UnableToRetrieveMetadata::mimeType($path)`.

### Example
```php
$attributes = $adapter->mimeType('img/photo.jpg');
$attributes->mimeType();      // e.g. 'image/jpeg'
```
```

--------------------------------

### listContents method signature

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Defines the adapter's listContents method. The $deep parameter is accepted but ignored because Qiniu's listFiles always lists with the prefix. Returns an iterable of FileAttributes; requires list permission on the bucket.

```php
public function listContents(string $path, bool $deep): iterable   // src/QiniuAdapter.php:165
```

--------------------------------

### FilesystemAdapter method signatures for prepend, append, delete, copy, move

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Lists the public method signatures for modifying, deleting, copying, and moving files. These methods return booleans and handle specific exceptions unless the 'throw' option is set.

```php
public function prepend($path, $data, $separator = PHP_EOL)     // :533
public function append($path, $data, $separator = PHP_EOL)      // :550
public function delete($paths)                                  // :565
public function copy($from, $to)                                // :593
public function move($from, $to)                                // :615
```

--------------------------------

### fileSize(string $path): FileAttributes

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Retrieves the file size in bytes. Uses the `stat` operation to get metadata; if the file size attribute is null, throws an exception.

```APIDOC
## fileSize(string $path): FileAttributes

### Description
Retrieves the file size in bytes. Uses the `stat` operation to get metadata; if the file size attribute is null, throws an exception.

### Method
fileSize

### Parameters
- **$path** (string) - Required - The file path.

### Returns
- `League\Flysystem\FileAttributes` - Contains the file size attribute (bytes).

### Exceptions
- If `fileSize` attribute is `null`, throws `UnableToRetrieveMetadata::fileSize($path)`.

### Example
```php
$adapter->fileSize('a.bin')->fileSize();   // bytes
```

### Error Handling
```php
try {
    $adapter->fileSize('missing.bin');
} catch (League\Flysystem\UnableToRetrieveMetadata $e) {
    $e->metadataType();  // 'file_size' (FileAttributes::ATTRIBUTE_FILE_SIZE)
}
```
```

--------------------------------

### Read with try/catch and fallback path

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Attempts to read a file and catches League\Flysystem\UnableToReadFile to recover with a fallback path. The catch block is triggered when the read throws, such as when the file is missing.

```php
try {
    $data = $adapter->read('folder/missing.txt');
} catch (League\Flysystem\UnableToReadFile $e) {
    $data = $adapter->read('folder/fallback.txt'); // recover with a fallback path
}
```

--------------------------------

### getConfig()

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Returns the raw disk configuration array.

```APIDOC
## getConfig()

### Description
Returns the raw disk configuration array.

### Method
getConfig

### Returns
- **array** - The raw disk configuration.
```

--------------------------------

### lastModified(string $path): FileAttributes

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Retrieves the last modified timestamp of a file. Uses the `stat` operation to get metadata; if the last modified attribute is null, throws an exception.

```APIDOC
## lastModified(string $path): FileAttributes

### Description
Retrieves the last modified timestamp of a file. Uses the `stat` operation to get metadata; if the last modified attribute is null, throws an exception.

### Method
lastModified

### Parameters
- **$path** (string) - Required - The file path.

### Returns
- `League\Flysystem\FileAttributes` - Contains the last modified timestamp (Unix seconds).

### Exceptions
- If `lastModified` attribute is `null`, throws `UnableToRetrieveMetadata::lastModified($path)`.

### Example
```php
$adapter->lastModified('a.bin')->lastModified(); // unix seconds
```
```

--------------------------------

### QiniuStorageServiceProvider boot method

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuStorageServiceProvider.md

Registers the 'qiniu' custom driver factory with Laravel's FilesystemManager. The factory creates a QiniuAdapter using the provided access_key, secret_key, bucket, and domain from the configuration, then wraps it in a FilesystemAdapter.

```php
// src/QiniuStorageServiceProvider.php:1-25 (entire file)

namespace Overtrue\LaravelFilesystem\Qiniu;

use Illuminate\Filesystem\FilesystemAdapter;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Filesystem;
use Overtrue\Flysystem\Qiniu\QiniuAdapter;

class QiniuStorageServiceProvider extends ServiceProvider
{
    public function boot()
    {
        app('filesystem')->extend('qiniu', function ($app, $config) {
            $adapter = new QiniuAdapter(
                $config['access_key'],
                $config['secret_key'],
                $config['bucket'],
                $config['domain']
            );

            return new FilesystemAdapter(new Filesystem($adapter), $adapter, $config);
        });
    }
}
```

--------------------------------

### download($path, $name = null, array $headers = [])

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Creates a streamed HTTP response that forces the file to be downloaded as an attachment. Sets the Content-Disposition to 'attachment'.

```APIDOC
## download($path, $name = null, array $headers = [])

### Description
Creates a streamed HTTP response that forces the file to be downloaded as an attachment. Sets the Content-Disposition to 'attachment'.

### Method
`download`

### Parameters
- `$path` (string) - Required - The path to the file.
- `$name` (string|null) - Optional - The name to use in the Content-Disposition header (default: null).
- `$headers` (array) - Optional - Additional HTTP headers (default: []).

### Returns
- `StreamedResponse` - The streamed response.

### Behavior
Same as `response`, but forces `disposition` to 'attachment'.

### Example
```php
$disk->download('invoices/2024-01.pdf', 'invoice.pdf');
```
```

--------------------------------

### FilesystemAdapter reading method signatures

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Lists the public methods for reading files from the FilesystemAdapter, including get, json, response, serve, download, and readStream. Each method's behavior is detailed in the table below.

```php
public function get($path)                                   // FilesystemAdapter.php:293
public function json($path, $flags = 0)                      // :311
public function response($path, $name = null, array $headers = [], $disposition = 'inline')  // :327
public function serve(Request $request, $path, $name = null, array $headers = [])           // :364
public function download($path, $name = null, array $headers = [])                          // :379
public function readStream($path)                            // :694
```

--------------------------------

### temporaryUrl($path, $expiration, array $options = [])

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Generates a temporary URL for a file path. Forwards to the adapter's getTemporaryUrl method (for Qiniu, passes three arguments to a two-parameter method) or uses a callback installed via buildTemporaryUrlsUsing. Throws RuntimeException if not supported.

```APIDOC
## [GET] temporaryUrl($path, $expiration, array $options = [])

### Description
Generates a temporary URL for a file path. Forwards to the adapter's getTemporaryUrl method (for Qiniu, passes three arguments to a two-parameter method) or uses a callback installed via buildTemporaryUrlsUsing. Throws RuntimeException if not supported.

### Method
GET

### Endpoint
temporaryUrl($path, $expiration, array $options = [])

### Parameters
#### Path Parameters
- **$path** (string) - Required - The file path.
- **$expiration** (DateTimeInterface|int) - Required - The expiration time.
- **$options** (array) - Optional - Additional options.

### Request Example
```php
$url = $disk->temporaryUrl('folder/my_file.txt', now()->addMinutes(5));
```

### Response
#### Success Response (200)
- **string** - The temporary URL.

#### Response Example
```
http://xxx.clouddn.com/folder/my_file.txt?sign=...
```

### Error Handling
- Throws `RuntimeException` if the driver does not support temporary URLs.
```

--------------------------------

### Accessor and customization method signatures

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Lists methods for retrieving the driver, adapter, config, and for overriding URL building. `getAdapter()` is the documented route to Qiniu-specific methods.

```php
public function getDriver()                    // :999  → League\Flysystem\FilesystemOperator
public function getAdapter()                   // :1009 → League\Flysystem\FilesystemAdapter (QiniuAdapter)
public function getConfig()                    // :1019 → array (raw disk config)
public function serveUsing(Closure $callback)  // :1051
public function buildTemporaryUrlsUsing(Closure $callback)        // :1062
public function buildTemporaryUploadUrlsUsing(Closure $callback)  // :1073
```

--------------------------------

### url($path)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Returns the URL for a given file path. Prepends the configured prefix if set, then uses the adapter's getUrl method (for Qiniu, returns the unsigned CDN URL). Throws RuntimeException if the driver does not support retrieving URLs.

```APIDOC
## [GET] url($path)

### Description
Returns the URL for a given file path. Prepends the configured prefix if set, then uses the adapter's getUrl method (for Qiniu, returns the unsigned CDN URL). Throws RuntimeException if the driver does not support retrieving URLs.

### Method
GET

### Endpoint
url($path)

### Parameters
#### Path Parameters
- **$path** (string) - Required - The file path to get the URL for.

### Request Example
```php
$url = $disk->url('folder/my_file.txt');
```

### Response
#### Success Response (200)
- **string** - The URL of the file.

#### Response Example
```
http://xxx.clouddn.com/folder/my_file.txt
```

### Error Handling
- Throws `RuntimeException` if the driver does not support retrieving URLs.
```

--------------------------------

### createDirectory(string $path, Config $config): void

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Creates a directory in Qiniu storage. This is a no-op because Qiniu uses implicit directories (prefixes); it always returns normally and never throws.

```APIDOC
## createDirectory(string $path, Config $config): void

### Description
Creates a directory in Qiniu storage. This is a no-op because Qiniu uses implicit directories (prefixes); it always returns normally and never throws.

### Method
createDirectory

### Parameters
- **$path** (string) - Required - The directory path to create.
- **$config** (Config) - Required - Configuration object.

### Behavior
- No-op: nothing is created server-side; writes to paths under the prefix still work.

### Example
```php
$disk->makeDirectory('new/prefix/');  // true — nothing is created server-side; writes to 'new/prefix/x' still work
```
```

--------------------------------

### allDirectories($directory = null)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Lists all directories recursively from a directory. Returns an array of directory paths.

```APIDOC
## allDirectories($directory = null)

### Description
Lists all directories recursively from a directory. Returns an array of directory paths.

### Method
allDirectories

### Parameters
- **$directory** (string|null) - Optional - The directory to list. Defaults to root.

### Returns
- **array<string>** - List of directory paths.
```

--------------------------------

### Delete with try/catch and logging

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Attempts to delete a file and catches League\Flysystem\UnableToDeleteFile to log a warning. The catch block is triggered when the key does not exist or credentials lack delete permission.

```php
// when the key does not exist, or credentials lack delete permission
try {
    $adapter->delete('gone/file.txt');
} catch (League\Flysystem\UnableToDeleteFile $e) {
    logger()->warning("delete failed: {$e->location()}");
}

// via FilesystemAdapter with 'throw' => true, the same exception propagates; otherwise delete() returns false
```

--------------------------------

### listContents

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Lists files under a given prefix in the Qiniu bucket. The deep parameter is accepted but ignored because Qiniu's listFiles always lists with the prefix.

```APIDOC
## listContents

### Description
Lists files under a given prefix in the Qiniu bucket. The deep parameter is accepted but ignored because Qiniu's listFiles always lists with the prefix.

### Method
listContents

### Endpoint
public function listContents(string $path, bool $deep): iterable

### Parameters
#### Path Parameters
- `$path` (string) - Required - prefix to list under the bucket
- `$deep` (bool) - Required - accepted but ignored; Qiniu's listFiles always lists with the prefix; no recursion flag exists

### Returns
- iterable (generator) of FileAttributes, one per entry in `$result[0]['items'] ?? []` from `BucketManager::listFiles($bucket, $path)`. `normalizeFileInfo` populates key/fsize/lastModified/mimeType; visibility is `null`. Requires the bucket to have `list` permission (storage API v2 list fails without it and yields nothing per the `?? []` guard).

### Throws
- No adapter-level throws (list errors surface as empty listings).

### Example
```php
foreach ($disk->files('photos/') as $file) {    // FilesystemAdapter::files → driver->listContents(...)->filter(isFile)
    echo $file;
}
$names = $disk->directories('prefix/');
```
```

--------------------------------

### createDirectory method signature

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Declares the createDirectory method in QiniuAdapter. It is a no-op because Qiniu storage uses implicit directories (prefixes); it never throws.

```php
public function createDirectory(string $path, Config $config): void   // src/QiniuAdapter.php:120
```

--------------------------------

### allFiles($directory = null)

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Lists all files recursively from a directory. Returns an array of file paths.

```APIDOC
## allFiles($directory = null)

### Description
Lists all files recursively from a directory. Returns an array of file paths.

### Method
allFiles

### Parameters
- **$directory** (string|null) - Optional - The directory to list. Defaults to root.

### Returns
- **array<string>** - List of file paths.
```

--------------------------------

### response($path, $name = null, array $headers = [], $disposition = 'inline')

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Creates a streamed HTTP response for the file at the given path. Sets Content-Type, Content-Length, and Content-Disposition headers, and streams the file content.

```APIDOC
## response($path, $name = null, array $headers = [], $disposition = 'inline')

### Description
Creates a streamed HTTP response for the file at the given path. Sets Content-Type, Content-Length, and Content-Disposition headers, and streams the file content.

### Method
`response`

### Parameters
- `$path` (string) - Required - The path to the file.
- `$name` (string|null) - Optional - The name to use in the Content-Disposition header (default: null).
- `$headers` (array) - Optional - Additional HTTP headers (default: []).
- `$disposition` (string) - Optional - The disposition type: 'inline' or 'attachment' (default: 'inline').

### Returns
- `Symfony\Component\HttpFoundation\StreamedResponse` - The streamed response.

### Behavior
Fills Content-Type (mimeType), Content-Length (size), and Content-Disposition (makeDisposition) headers, and streams `readStream($path)` via a response callback.

### Example
```php
$disk->response('img.png', headers: ['X-Cache' => 'hit']);
```
```

--------------------------------

### prepend

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/FilesystemAdapter.md

Prepends data to an existing file. If the file exists, the data is prepended with a separator; otherwise, it creates the file. Returns a boolean indicating success.

```APIDOC
## prepend

### Description
Prepends data to an existing file. If the file exists, the data is prepended with a separator; otherwise, it creates the file. Returns a boolean indicating success.

### Method
prepend

### Signature
`public function prepend($path, $data, $separator = PHP_EOL)`

### Parameters
- **$path** (string) - Required - The path to the file.
- **$data** (string) - Required - The data to prepend.
- **$separator** (string) - Optional - Separator between existing and new data. Defaults to PHP_EOL.

### Return Value
- **bool** - True on success, false on failure.

### Example
```php
$disk->prepend('logs/app.log', '--- new session ---');
```
```

--------------------------------

### getBucket

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter-extended.md

Returns the configured bucket name for the Qiniu adapter.

```APIDOC
## getBucket

### Description
Returns the configured bucket name for the Qiniu adapter.

### Method
getBucket

### Signature
```php
public function getBucket(): string
```

### Parameters
None

### Returns
- (string) - The configured bucket name

### Example
```php
$bucket = $adapter->getBucket(); // e.g. 'test'
```
```

--------------------------------

### Manual provider registration and Qiniu disk configuration

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuStorageServiceProvider.md

Shows how to manually register the QiniuStorageServiceProvider in config/app.php and configure the qiniu disk in config/filesystems.php. The disk requires access_key, secret_key, bucket, and domain; missing keys throw UndefinedOffsetError at first disk resolution.

```php
// config/app.php
<?php

return [
    'providers' => [
        // ...other providers
        Overtrue\LaravelFilesystem\Qiniu\QiniuStorageServiceProvider::class,
    ],
];
```

```php
// config/filesystems.php
<?php

return [
    'default' => 'local',
    'disks' => [
        'qiniu' => [
            'driver'     => 'qiniu',
            'access_key' => env('QINIU_ACCESS_KEY', 'xxxxxxxxxxxxxxxx'),
            'secret_key' => env('QINIU_SECRET_KEY', 'xxxxxxxxxxxxxxxx'),
            'bucket'     => env('QINIU_BUCKET', 'test'),
            'domain'     => env('QINIU_DOMAIN', 'xxx.clouddn.com'),
        ],
    ],
];
```

--------------------------------

### Metadata method signatures

Source: https://github.com/overtrue/laravel-filesystem-qiniu/blob/master/_autodocs/api-reference/QiniuAdapter.md

Declares mimeType, lastModified, and fileSize methods. Each returns FileAttributes and may throw UnableToRetrieveMetadata if the corresponding attribute is null.

```php
public function mimeType(string $path): FileAttributes      // src/QiniuAdapter.php:134
public function lastModified(string $path): FileAttributes  // src/QiniuAdapter.php:145
public function fileSize(string $path): FileAttributes      // src/QiniuAdapter.php:155
```
Tokens:
Raw