PHPackages                             alphasnow/aliyun-oss-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. alphasnow/aliyun-oss-laravel

ActiveLibrary[File & Storage](/categories/file-storage)

alphasnow/aliyun-oss-laravel
============================

alibaba cloud object storage service for laravel

4.9.0(1y ago)182240.7k↓17.9%172MITPHPPHP ^8.0.2

Since Mar 23Pushed 1y ago1 watchersCompare

[ Source](https://github.com/alphasnow/aliyun-oss-laravel)[ Packagist](https://packagist.org/packages/alphasnow/aliyun-oss-laravel)[ Docs](https://alphasnow.github.io/aliyun-oss-laravel/)[ RSS](/packages/alphasnow-aliyun-oss-laravel/feed)WikiDiscussions 4.x Synced 1mo ago

READMEChangelog (7)Dependencies (7)Versions (33)Used By (2)

English | [简体中文](README-CN.md)

Aliyun OSS Laravel
==================

[](#aliyun-oss-laravel)

[![Latest Stable Version](https://camo.githubusercontent.com/06447e45cdc88f74547600518e27a186313ab2b0aaff241601edbebf20a01e07/68747470733a2f2f706f7365722e707567782e6f72672f616c706861736e6f772f616c6979756e2d6f73732d6c61726176656c2f762f737461626c65)](https://packagist.org/packages/alphasnow/aliyun-oss-laravel)[![Total Downloads](https://camo.githubusercontent.com/5ff11640281e0daa6462c9a33600256b3d605267d6908d88cf28a9ffc8a38329/68747470733a2f2f706f7365722e707567782e6f72672f616c706861736e6f772f616c6979756e2d6f73732d6c61726176656c2f646f776e6c6f616473)](https://packagist.org/packages/alphasnow/aliyun-oss-laravel)[![tests](https://github.com/alphasnow/aliyun-oss-laravel/actions/workflows/tests.yml/badge.svg?branch=4.x)](https://github.com/alphasnow/aliyun-oss-laravel/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/a340baf14c1064b86e0bee6875e2629c91a30bd641df0c1ff455cc351e879a00/68747470733a2f2f706f7365722e707567782e6f72672f616c706861736e6f772f616c6979756e2d6f73732d6c61726176656c2f6c6963656e7365)](https://packagist.org/packages/alphasnow/aliyun-oss-laravel)[![Coverage Status](https://camo.githubusercontent.com/e5fb76de05a87e76d0f03fd9fa4de5637553a500eba08639df53cf76f049fff7/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f616c706861736e6f772f616c6979756e2d6f73732d6c61726176656c2f62616467652e7376673f6272616e63683d34)](https://coveralls.io/github/alphasnow/aliyun-oss-laravel?branch=4)

[![Banner](https://camo.githubusercontent.com/88955cd3e552a798d99189542974565119a6ec8e17eff0b2e3233f777c48c750/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f416c6979756e2532304f53532532304c61726176656c2e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d616c706861736e6f77253246616c6979756e2d6f73732d6c61726176656c267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d416c69626162612b436c6f75642b4f626a6563742b53746f726167652b536572766963652b466f722b4c61726176656c266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)](https://github.com/alphasnow/aliyun-oss-laravel)

This package is a wrapper bridging [aliyun-oss-flysystem](https://github.com/alphasnow/aliyun-oss-flysystem) into Laravel as an available storage disk.
If client direct transmission is required, Use web server signature direct transmission OSS extension package [aliyun-oss-appserver](https://github.com/alphasnow/aliyun-oss-appserver).

Compatibility
-------------

[](#compatibility)

laravelaliyun-oss-laraveldriverreadme>=5.5,<9.0^3.0aliyun[readme](https://github.com/alphasnow/aliyun-oss-laravel/blob/3.x/README.md)>=9.0^4.0oss[readme](https://github.com/alphasnow/aliyun-oss-laravel/blob/4.x/README.md)Installation
------------

[](#installation)

1. If you use the composer to manage project dependencies, run the following command in your project's root directory: ```
    composer require alphasnow/aliyun-oss-laravel
    ```

    Then run `composer install` to install the dependency.
2. Modify the environment file `.env````
    OSS_ACCESS_KEY_ID=
    OSS_ACCESS_KEY_SECRET=
    OSS_BUCKET=
    OSS_ENDPOINT=
    ```
3. (Optional) Modify the configuration file `config/filesystems.php````
    "default" => env("FILESYSTEM_DRIVER", "oss"),
    // ...
    "disks"=>[
        // ...
        "oss" => [
            "driver"            => "oss",
            "access_key_id"     => env("OSS_ACCESS_KEY_ID"),           // Required, yourAccessKeyId
            "access_key_secret" => env("OSS_ACCESS_KEY_SECRET"),       // Required, yourAccessKeySecret
            "bucket"            => env("OSS_BUCKET"),                  // Required, for example: my-bucket
            "endpoint"          => env("OSS_ENDPOINT"),                // Required, for example: oss-cn-shanghai.aliyuncs.com
            "internal"          => env("OSS_INTERNAL", null),          // Optional, for example: oss-cn-shanghai-internal.aliyuncs.com
            "domain"            => env("OSS_DOMAIN", null),            // Optional, for example: oss.my-domain.com
            "is_cname"          => env("OSS_CNAME", false),            // Optional, if the Endpoint is a custom domain name, this must be true, see: https://github.com/aliyun/aliyun-oss-php-sdk/blob/572d0f8e099e8630ae7139ed3fdedb926c7a760f/src/OSS/OssClient.php#L113C1-L122C78
            "prefix"            => env("OSS_PREFIX", ""),              // Optional, the prefix of the store path
            "use_ssl"           => env("OSS_SSL", false),              // Optional, whether to use HTTPS
            "throw"             => env("OSS_THROW", false),            // Optional, whether to throw an exception that causes an error
            "signatureVersion"  => env("OSS_SIGNATURE_VERSION", "v1"), // Optional, select v1 or v4 as the signature version
            "region"            => env("OSS_REGION", ""),              // Optional, for example: cn-shanghai, used only when v4 signature version is selected
            "options"           => [],                                 // Optional, add global configuration parameters, For example: [\OSS\OssClient::OSS_CHECK_MD5 => false]
            "macros"            => []                                  // Optional, add custom Macro, For example: [\App\Macros\ListBuckets::class, \App\Macros\CreateBucket::class]
        ],
        // ...
    ]
    ```

Usage
-----

[](#usage)

```
use Illuminate\Support\Facades\Storage;
$storage = Storage::disk("oss");
```

### Use storage method

[](#use-storage-method)

#### Write

[](#write)

```
Storage::disk("oss")->putFile("dir/path", "/local/path/file.txt");
Storage::disk("oss")->putFileAs("dir/path", "/local/path/file.txt", "file.txt");

Storage::disk("oss")->put("dir/path/file.txt", file_get_contents("/local/path/file.txt"));
$fp = fopen("/local/path/file.txt","r");
Storage::disk("oss")->put("dir/path/file.txt", $fp);
fclose($fp);

Storage::disk("oss")->prepend("dir/path/file.txt", "Prepend Text");
Storage::disk("oss")->append("dir/path/file.txt", "Append Text");

Storage::disk("oss")->put("dir/path/secret.txt", "My secret", "private");
Storage::disk("oss")->put("dir/path/download.txt", "Download content", ["headers" => ["Content-Disposition" => "attachment;filename=download.txt"]]);
```

#### Read

[](#read)

```
Storage::disk("oss")->url("dir/path/file.txt");
Storage::disk("oss")->temporaryUrl("dir/path/file.txt", \Carbon\Carbon::now()->addMinutes(30));

Storage::disk("oss")->get("dir/path/file.txt");

Storage::disk("oss")->exists("dir/path/file.txt");
Storage::disk("oss")->size("dir/path/file.txt");
Storage::disk("oss")->lastModified("dir/path/file.txt");
```

#### Delete

[](#delete)

```
Storage::disk("oss")->delete("dir/path/file.txt");
Storage::disk("oss")->delete(["dir/path/file1.txt", "dir/path/file2.txt"]);
```

#### File operation

[](#file-operation)

```
Storage::disk("oss")->copy("dir/path/file.txt", "dir/path/file_new.txt");
Storage::disk("oss")->move("dir/path/file.txt", "dir/path/file_new.txt");
Storage::disk("oss")->rename("dir/path/file.txt", "dir/path/file_new.txt");
```

#### Folder operation

[](#folder-operation)

```
Storage::disk("oss")->makeDirectory("dir/path");
Storage::disk("oss")->deleteDirectory("dir/path");

Storage::disk("oss")->files("dir/path");
Storage::disk("oss")->allFiles("dir/path");

Storage::disk("oss")->directories("dir/path");
Storage::disk("oss")->allDirectories("dir/path");
```

### Use macro

[](#use-macro)

#### default macro

[](#default-macro)

```
Storage::disk("oss")->appendObject("dir/path/news.txt", "The first line paragraph.", 0);
Storage::disk("oss")->appendObject("dir/path/news.txt", "The second line paragraph.", 25);
Storage::disk("oss")->appendObject("dir/path/news.txt", "The last line paragraph.", 51);

Storage::disk("oss")->appendFile("dir/path/file.zip", "dir/path/file.zip.001", 0);
Storage::disk("oss")->appendFile("dir/path/file.zip", "dir/path/file.zip.002", 1024);
Storage::disk("oss")->appendFile("dir/path/file.zip", "dir/path/file.zip.003", 1024);

Storage::disk("oss")->processObject("dir/path/image.jpg", "image/resize,l_1000");
```

#### Add custom macro

[](#add-custom-macro)

1. Add Macro ```
    namespace App\Macros;
    use AlphaSnow\LaravelFilesystem\Aliyun\Macros\AliyunMacro;

    class ListBuckets implements AliyunMacro
    {
        // ...
    }
    ```

    Reference code: [AppendObject.php](https://github.com/alphasnow/aliyun-oss-laravel/blob/4.5.0/src/Macros/AppendObject.php)
2. Modify the config ```
    [
        "macros" => [\App\Macros\ListBuckets::class]
    ]
    ```
3. Use Macro ```
    Storage::disk("oss")->listBuckets()
    ```

### Use OssClient

[](#use-ossclient)

```
use AlphaSnow\LaravelFilesystem\Aliyun\OssClientAdapter;

$adapter = new OssClientAdapter(Storage::disk("oss"));
$adapter->client()->appendObject($adapter->bucket(), $adapter->path("dir/path/file.txt"), "contents", 0, $adapter->options(["visibility" => "private"]));
```

Documentation
-------------

[](#documentation)

[AlibabaCloud Object Storage Service Documentation](https://www.alibabacloud.com/help/en/oss/)

Issues
------

[](#issues)

[Opening an Issue](https://github.com/alphasnow/aliyun-oss-laravel/issues)

Contributors
------------

[](#contributors)

[ ![](https://camo.githubusercontent.com/02c78b117f089a1ca37f3d730008d86c868f669b1d77da86a97785c709456f85/68747470733a2f2f636f6e747269622e726f636b732f696d6167653f7265706f3d616c706861736e6f772f616c6979756e2d6f73732d6c61726176656c)](https://github.com/alphasnow/aliyun-oss-laravel/graphs/contributors)Star History
------------

[](#star-history)

[![Star History Chart](https://camo.githubusercontent.com/b4f73b240bf9f248c41d15236912129031c8030ae9260240101d490149b54941/68747470733a2f2f6170692e737461722d686973746f72792e636f6d2f7376673f7265706f733d616c706861736e6f772f616c6979756e2d6f73732d6c61726176656c26747970653d54696d656c696e65)](https://star-history.com/#alphasnow/aliyun-oss-laravel&Timeline)

License
-------

[](#license)

[MIT](LICENSE)

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance32

Infrequent updates — may be unmaintained

Popularity52

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 97.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~36 days

Total

33

Last Release

704d ago

Major Versions

2.8.0 → 3.0.02021-08-17

3.0.2 → 4.0.02022-02-25

3.1.0 → 4.4.12022-06-27

3.3.0 → 4.5.02022-07-12

3.x-dev → 4.6.02022-08-03

PHP version history (4 changes)1.2.0PHP >=7.0

2.5.0PHP >=7.0.0

4.0.0PHP ^8.0

4.1.0PHP ^8.0.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/90877a466dd664c9a6b4ccd2a9ccf46e54427307198fa11201976aac968f5fca?d=identicon)[alphasnow](/maintainers/alphasnow)

---

Top Contributors

[![alphasnow](https://avatars.githubusercontent.com/u/8286647?v=4)](https://github.com/alphasnow "alphasnow (182 commits)")[![WOSHIZHAZHA120](https://avatars.githubusercontent.com/u/52521836?v=4)](https://github.com/WOSHIZHAZHA120 "WOSHIZHAZHA120 (2 commits)")[![aspirantzhang](https://avatars.githubusercontent.com/u/24559988?v=4)](https://github.com/aspirantzhang "aspirantzhang (1 commits)")[![fossabot](https://avatars.githubusercontent.com/u/29791463?v=4)](https://github.com/fossabot "fossabot (1 commits)")

---

Tags

aliyunfilesystemflysystem-adapterlaravellaravel-filesystemlaravel-packageossphpstoragelaravelstoragefilesystemsaliyunoss

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/alphasnow-aliyun-oss-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/alphasnow-aliyun-oss-laravel/health.svg)](https://phpackages.com/packages/alphasnow-aliyun-oss-laravel)
```

###  Alternatives

[jacobcyl/ali-oss-storage

aliyun oss filesystem storage for laravel 5+

523566.2k7](/packages/jacobcyl-ali-oss-storage)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)