PHPackages hughcube/laravel-alioss - 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. hughcube/laravel-alioss ActiveLibrary[File & Storage](/categories/file-storage) hughcube/laravel-alioss ======================= v2.4.4(2mo ago)05.4k↑335.7%MITPHPPHP >=8.0CI passing Since Mar 24Pushed 2mo agoCompare [ Source](https://github.com/hughcube/laravel-alioss)[ Packagist](https://packagist.org/packages/hughcube/laravel-alioss)[ RSS](/packages/hughcube-laravel-alioss/feed)WikiDiscussions master Synced 3w ago READMEChangelogDependencies (22)Versions (38)Used By (0) Laravel AliOSS ============== [](#laravel-alioss) [ ![Test Actions status](https://github.com/hughcube-php/laravel-alioss/workflows/Test/badge.svg) ](https://github.com/hughcube-php/laravel-alioss/actions?query=workflow%3ATest) [ ![StyleCI](https://camo.githubusercontent.com/ebeea47ad31725256b62452fb6f8b3c58e955684b8315f48382fb940aa4ba0bf/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3437333233343734342f736869656c643f6272616e63683d6d6173746572) ](https://styleci.io/repos/473234744) [ ![Latest Stable Version](https://camo.githubusercontent.com/5d9612e04134c3eaef17270bf6695fdabc2d0446c2de8bbfd280b5bba511bccc/68747470733a2f2f706f7365722e707567782e6f72672f68756768637562652f6c61726176656c2d616c696f73732f762f737461626c65) ](https://packagist.org/packages/hughcube/laravel-alioss) [ ![License](https://camo.githubusercontent.com/0cf599b602943ed04975340eb47fed38552f9e8aa71042df8304c307df865474/68747470733a2f2f706f7365722e707567782e6f72672f68756768637562652f6c61726176656c2d616c696f73732f6c6963656e7365) ](https://packagist.org/packages/hughcube/laravel-alioss) Alibaba Cloud OSS adapter for Laravel, based on [alibabacloud/oss-v2](https://github.com/aliyun/alibabacloud-oss-php-sdk-v2). Requirements ------------ [](#requirements) - PHP >= 8.0 - Laravel 9+ Installation ------------ [](#installation) ``` composer require hughcube/laravel-alioss ``` ServiceProvider auto-discovery is enabled. No manual registration needed. Configuration ------------- [](#configuration) Add a disk to `config/filesystems.php`: ``` 'disks' => [ 'oss' => [ 'driver' => 'alioss', 'bucket' => env('ALIOSS_BUCKET'), 'region' => env('ALIOSS_REGION', 'cn-shanghai'), 'accessKeyId' => env('ALIOSS_ACCESS_KEY_ID'), 'accessKeySecret' => env('ALIOSS_ACCESS_KEY_SECRET'), 'endpoint' => env('ALIOSS_ENDPOINT'), // optional 'prefix' => env('ALIOSS_PREFIX', ''), // optional 'internal' => env('ALIOSS_INTERNAL', false), // use internal endpoint 'isCName' => false, // optional 'securityToken' => null, // optional, STS token 'requestProxy' => null, // optional 'acl' => null, // optional, default ACL 'cdnBaseUrl' => env('ALIOSS_CDN_BASE_URL'), // optional 'uploadBaseUrl' => env('ALIOSS_UPLOAD_BASE_URL'), // optional ], ], ``` Quick Start ----------- [](#quick-start) ``` use HughCube\Laravel\AliOSS\AliOSS; $adapter = AliOSS::getClient(); // or AliOSS::getClient('oss') // Write $adapter->write('path/file.txt', 'content'); // Read $content = $adapter->read('path/file.txt'); // URL $url = $adapter->cdnUrl('path/file.jpg'); echo $url; // https://cdn.example.com/path/file.jpg ``` Flysystem Operations -------------------- [](#flysystem-operations) Standard `FilesystemAdapter` interface: ``` $adapter->write('file.txt', 'content'); $adapter->writeStream('file.txt', $stream); $adapter->read('file.txt'); $adapter->readStream('file.txt'); $adapter->delete('file.txt'); $adapter->fileExists('file.txt'); $adapter->copy('source.txt', 'dest.txt'); $adapter->move('source.txt', 'dest.txt'); $adapter->createDirectory('dir'); $adapter->setVisibility('file.txt', 'public'); $adapter->visibility('file.txt'); $adapter->fileAttributes('file.txt'); ``` Extended operations: ``` // Upload local file, returns OssUrl $url = $adapter->writeFile('/tmp/photo.jpg', 'photos/photo.jpg'); // Download from URL and upload to OSS (stream, supports large files) $url = $adapter->writeFromUrl('https://example.com/photo.jpg', 'photos/photo.jpg'); // Download to local file $adapter->download('photos/photo.jpg', '/tmp/photo.jpg'); // Create symlink $adapter->symlink('link.jpg', 'target.jpg'); // WeChat avatar scenario: upload only when URL changed $url = $adapter->mirrorIfChanged($wechatAvatarUrl, $existingDbUrl, 'avatars'); ``` URL Operations -------------- [](#url-operations) All URL methods return `OssUrl` instances (extends `HUrl`, supports `__toString`). ### Build URLs [](#build-urls) ``` $adapter->url('file.jpg'); // OSS URL (default) $adapter->cdnUrl('file.jpg'); // CDN URL, null if not configured $adapter->uploadUrl('file.jpg'); // Upload URL $adapter->ossUrl('file.jpg'); // OSS external URL $adapter->ossInternalUrl('file.jpg'); // OSS internal URL $adapter->ossUri('file.jpg'); // oss://bucket/file.jpg ``` ### Signed URLs [](#signed-urls) ``` $adapter->signUrl('file.jpg', 60); // GET signed, 60s $adapter->signUploadUrl('file.jpg', 60); // PUT signed, 60s $adapter->presign('file.jpg', 60, 'HEAD'); // PresignResult object ``` ### Domain Detection [](#domain-detection) ``` $adapter->isCdnUrl($url); $adapter->isUploadUrl($url); $adapter->isOssUrl($url); $adapter->isOssInternalUrl($url); $adapter->isBucketUrl($url); // any of the above ``` ### Domain Conversion [](#domain-conversion) ``` $adapter->toCdnUrl($url); $adapter->toUploadUrl($url); $adapter->toOssUrl($url); $adapter->toOssInternalUrl($url); ``` ### Parse URL [](#parse-url) ``` $ossUrl = $adapter->parseUrl('https://cdn.example.com/path/file.jpg'); ``` OssUrl ------ [](#ossurl) `OssUrl` extends `HUrl` with OSS-specific capabilities. All methods are immutable (return new instances). ### Domain Operations [](#domain-operations) ``` $url = $adapter->cdnUrl('photo.jpg'); $url->toCdn(); // switch to CDN domain $url->toUpload(); // switch to upload domain $url->toOss(); // switch to OSS domain $url->toOssInternal(); // switch to internal domain $url->toOssUri(); // "oss://bucket/key" $url->isCdn(); // true/false $url->isUpload(); $url->isOss(); $url->isOssInternal(); $url->isBucket(); // any known domain ``` ### Signing [](#signing) ``` $url->sign(60); // GET signed URL $url->sign(60, 'PUT'); // PUT signed URL $url->sign(60, 'HEAD'); // HEAD signed URL $url->signUpload(60); // shortcut for sign(60, 'PUT') ``` Process parameters are included in the signature automatically: ``` $adapter->ossUrl('photo.jpg') ->imageResize(800) ->imageFormat('webp') ->sign(300); // x-oss-process is signed into the URL ``` ### Image Processing [](#image-processing) Operations chain automatically. `image/` prefix appears only once in the output. ``` $url = $adapter->cdnUrl('photo.jpg') ->imageResize(800, 600, 'fill') ->imageRotate(90) ->imageWatermarkText('Copyright', size: 30, color: 'FF0000') ->imageFormat('webp') ->imageQuality(85); echo $url; // https://cdn.example.com/photo.jpg?x-oss-process=image/resize,m_fill,w_800,h_600/rotate,90/watermark,.../format,webp/quality,q_85 ``` MethodDescription`imageResize($w, $h, $mode)`Scale. Modes: `lfit`, `mfit`, `fill`, `pad`, `fixed``imageResizeByPercent($pct)`Scale by percentage \[1, 1000\]`imageCrop($w, $h, $gravity, $x, $y)`Crop. Gravity: `nw`, `north`, `ne`, `west`, `center`, `east`, `sw`, `south`, `se``imageRotate($angle)`Rotate \[0, 360\]`imageFlip($dir)`Flip: `h`, `v`, `both``imageFormat($fmt)`Convert: `jpg`, `png`, `webp`, `bmp`, `gif`, `tiff`, `heic`, `avif``imageQuality($q, $abs)`Quality \[1, 100\]. `$abs=true` for absolute`imageBlur($r, $s)`Blur. radius/sigma \[1, 50\]`imageBright($val)`Brightness \[-100, 100\]`imageContrast($val)`Contrast \[-100, 100\]`imageSharpen($val)`Sharpen \[50, 399\]`imageCircle($r)`Circle crop, radius \[1, 4096\]`imageRoundedCorners($r)`Rounded corners \[1, 4096\]`imageAutoOrient()`Auto-rotate by EXIF`imageInterlace()`Progressive display (JPG only)`imageIndexCrop($size, $idx, $axis)`Indexed slice`imageWatermarkText($text, ...)`Text watermark`imageWatermarkImage($path, ...)`Image watermark`imageInfo()`Image metadata (JSON)`imageAverageHue()`Dominant colorRemove operations: `imageRemoveResize()`, `imageRemoveRotate()`, `imageRemoveWatermark()`, etc. ### Video Processing [](#video-processing) ``` // Snapshot (sync) $adapter->ossUrl('video.mp4')->videoSnapshot(1000, 800, 600); // Video info (sync) $adapter->ossUrl('video.mp4')->videoInfo(); // Transcode (async) $adapter->ossUrl('video.mp4') ->videoConvert('mp4', 'h264', 'aac', '1280x720') ->saveas('bucket', 'output.mp4') ->notify('my-topic'); // GIF (async) $adapter->ossUrl('video.mp4')->videoGif(5000, 3000, 320, 240); // Sprite sheet (async) $adapter->ossUrl('video.mp4')->videoSprite(5, 10, 10, 160, 90); // Concat (async) $adapter->ossUrl('video1.mp4')->videoConcat(['video2.mp4', 'video3.mp4']); ``` ### Audio Processing [](#audio-processing) ``` $adapter->ossUrl('audio.mp3')->audioInfo(); $adapter->ossUrl('audio.wav')->audioConvert('mp3', 44100, 2, 320); $adapter->ossUrl('audio1.mp3')->audioConcat(['audio2.mp3']); ``` ### Document Processing [](#document-processing) ``` $adapter->ossUrl('doc.docx')->docPreview(); $adapter->ossUrl('doc.docx')->docEdit(); $adapter->ossUrl('doc.docx')->docSnapshot(1); $adapter->ossUrl('doc.docx') ->docConvert('pdf', 'docx', '1,2,4-10') ->saveas('bucket', 'output.pdf'); $adapter->ossUrl('doc.docx')->docTranslate('Hello', 'zh_CN'); ``` ### Generic Process [](#generic-process) ``` $url->process('image/resize,w_800/rotate,90'); // sync $url->asyncProcess('video/convert,f_mp4'); // async $url->clearProcess(); // clear all ``` Validation Rule --------------- [](#validation-rule) `OssFile` validates that a URL points to a valid OSS file. ``` use HughCube\Laravel\AliOSS\Rules\OssFile; $rules = [ 'avatar' => [ 'required', OssFile::make() ->cdnDomain() ->image() ->maxSize(2 * 1024 * 1024) ->maxWidth(4096) ->maxHeight(4096) ->aspectRatio(1, 1), ], 'document' => [ 'required', OssFile::make()->anyDomain()->document()->maxSize(10 * 1024 * 1024), ], 'attachment' => [ 'required', OssFile::make() ->extensions(['pdf', 'docx', 'xlsx']) ->exceptExtensions(['exe', 'php']) ->directory('uploads') ->filenameMaxLength(100), ], ]; ``` ### Constraints [](#constraints) **Domain:** `cdnDomain()`, `uploadDomain()`, `ossDomain()`, `anyDomain()` **File type:** `image()`, `video()`, `audio()`, `media()`, `document()`, `pdf()`, `word()`, `excel()`, `ppt()`, `archive()`, `text()`, `json()`, `xml()`, `mimeTypes([...])` **Size:** `minSize($bytes)`, `maxSize($bytes)`, `sizeBetween($min, $max)` **Image dimensions:** `maxWidth($px)`, `maxHeight($px)`, `aspectRatio($w, $h)`, `minAspectRatio($w, $h)`, `maxAspectRatio($w, $h)` **Path:** `extensions([...])`, `exceptExtensions([...])`, `directory($dir)`, `directories([...])`, `exceptDirectory($dir)`, `filenameMaxLength($len)` **Behavior:** `domainOnly()`, `checkExists(false)` ### Query After Validation [](#query-after-validation) ``` $rule->fileAttributes(); // FileAttributes $rule->fileSize(); // ?int $rule->mimeType(); // ?string $rule->path(); // ?string $rule->filename(); // ?string $rule->extension(); // ?string $rule->getDirectory(); // ?string $rule->domainType(); // "cdn" | "upload" | "oss" | "oss_internal" $rule->failedReason(); // failure code ``` License ------- [](#license) MIT ### Health Score 50 — FairBetter than 95% of packages Maintenance87 Actively maintained with recent releases Popularity23 Limited adoption so far Community8 Small or concentrated contributor base Maturity66 Established project with proven stability Bus Factor1 Top contributor holds 86.7% 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 ~41 days Recently: every ~6 days Total 37 Last Release 66d ago Major Versions v1.4.0 → v2.0.02026-03-27 PHP version history (2 changes)v1.0.0PHP >=7.1 v1.0.2PHP >=8.0 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/5361789?v=4)[hugh.li](/maintainers/hughcube)[@hughcube](https://github.com/hughcube) --- Top Contributors [![hughcube](https://avatars.githubusercontent.com/u/5361789?v=4)](https://github.com/hughcube "hughcube (72 commits)")[![StyleCIBot](https://avatars.githubusercontent.com/u/11048387?v=4)](https://github.com/StyleCIBot "StyleCIBot (11 commits)") ### Code Quality Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/hughcube-laravel-alioss/health.svg) ``` [![Health](https://phpackages.com/badges/hughcube-laravel-alioss/health.svg)](https://phpackages.com/packages/hughcube-laravel-alioss) ``` ### Alternatives [unisharp/laravel-filemanager A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE 2.1k3.4M81](/packages/unisharp-laravel-filemanager)[league/flysystem-aws-s3-v3 AWS S3 filesystem adapter for Flysystem. 1.7k277.8M961](/packages/league-flysystem-aws-s3-v3)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9742.3M121](/packages/roots-acorn)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k12](/packages/tempest-framework)[iidestiny/flysystem-oss Flysystem adapter for the Oss storage. 95628.8k29](/packages/iidestiny-flysystem-oss)[luoyy/ali-oss-storage aliyun oss filesystem storage for laravel 10+ 1430.7k1](/packages/luoyy-ali-oss-storage) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)