cloudinary-labs / cloudinary-laravel
A Laravel Cloudinary Package
Installs: 635 170
Dependents: 2
Suggesters: 0
Security: 0
Stars: 277
Watchers: 14
Forks: 71
Open Issues: 6
Requires
- php: ^8.1
- ext-json: *
- cloudinary/cloudinary_php: ^2.0
- illuminate/support: ^10.0|^11.0
Requires (Dev)
- mockery/mockery: ^1.1
- orchestra/testbench: ^8.0|^9.0
- pestphp/pest: ^2.35
- sempro/phpunit-pretty-print: ^1.0
README
A Laravel Package for uploading, optimizing, transforming and delivering media files with Cloudinary. Furthermore, it provides a fluent and expressive API to easily attach your media files to Eloquent models.
Table of Contents
- Installation
- Configuration
- Usage
- Cloudinary URL Generation
- Blade Components
- Disclaimer
- Contributions
- License
Installation
Requires PHP 8.1+ and Laravel 10+.
composer require cloudinary-labs/cloudinary-laravel
Configuration
Publish the configuration file:
php artisan vendor:publish --provider="CloudinaryLabs\CloudinaryLaravel\CloudinaryServiceProvider" --tag="cloudinary-laravel-config"
Add your Cloudinary credentials to your .env
file:
CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME
CLOUDINARY_UPLOAD_PRESET=your_upload_preset
CLOUDINARY_NOTIFICATION_URL=
Note
You can get your CLOUDINARY_URL
from your Cloudinary console. It typically looks like this: cloudinary://API_KEY:API_SECRET@CLOUD_NAME
. Make sure to replace API_KEY
, API_SECRET
, and CLOUD_NAME
with your actual Cloudinary credentials.
Usage
Upload, Retrieval & Transformation
// Upload $uploadedFileUrl = cloudinary()->upload($request->file('file')->getRealPath())->getSecurePath(); // Upload with transformation $uploadedFileUrl = cloudinary()->upload($request->file('file')->getRealPath(), [ 'folder' => 'uploads', 'transformation' => [ 'width' => 400, 'height' => 400, 'crop' => 'fill' ] ])->getSecurePath(); // Get URL $url = cloudinary()->getUrl($publicId); // Check if file exists $exists = Storage::disk('cloudinary')->fileExists($publicId);
Attach Files to Eloquent Models
First, add the MediaAlly
trait to your model:
use CloudinaryLabs\CloudinaryLaravel\MediaAlly; class Page extends Model { use MediaAlly; // ... }
Then, you can use the following methods:
// Attach media $page->attachMedia($request->file('file')); // Retrieve media $allMedia = $page->fetchAllMedia(); $firstMedia = $page->fetchFirstMedia(); $lastMedia = $page->fetchLastMedia(); // Update media $page->updateMedia($newFile); // Detach media $page->detachMedia($file);
Upload Widget
Add the Cloudinary JS to your layout:
<head> @cloudinaryJS </head>
Use the upload button component:
<x-cld-upload-button> Upload Files </x-cld-upload-button>
Media Management via CLI
php artisan cloudinary:backup php artisan cloudinary:delete php artisan cloudinary:fetch php artisan cloudinary:rename php artisan cloudinary:upload
Cloudinary URL Generation
Use the Cloudinary
facade or the cloudinary()
helper function to generate URLs:
use CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary; $url = Cloudinary::getUrl($publicId); // or $url = cloudinary()->getUrl($publicId);
Blade Components
This package provides several Blade components for easy integration of Cloudinary media in your Laravel views:
Image Component
Basic usage:
<x-cld-image public-id="example" width="300" height="300"></x-cld-image>
With transformations:
<x-cld-image public-id="example" width="300" height="300"> <x-cld-transformation crop="fill" gravity="auto" radius="20" ></x-cld-transformation> </x-cld-image>
Responsive image:
<x-cld-image public-id="example" responsive> <x-cld-transformation width="auto" crop="scale"> <x-cld-transformation width="320" crop="scale" media="(max-width: 320px)" ></x-cld-transformation> <x-cld-transformation width="480" crop="scale" media="(max-width: 480px)" ></x-cld-transformation> </x-cld-transformation> </x-cld-image>
Video Component
Basic usage:
<x-cld-video public-id="example"></x-cld-video>
With transformations:
<x-cld-video public-id="example" controls> <x-cld-transformation width="500" crop="fill"></x-cld-transformation> </x-cld-video>
Upload Button Component
Basic usage:
<x-cld-upload-button>Upload Files</x-cld-upload-button>
With custom options:
<x-cld-upload-button :options="[ 'multiple' => true, 'maxFiles' => 5, 'sources' => ['local', 'camera'], ]" > Upload Multiple Files </x-cld-upload-button>
Image Gallery Component
<x-cld-image-gallery :images="$images" transformation="w_300,h_300,c_fill"> <x-slot name="placeholder"> <div class="spinner">Loading...</div> </x-slot> </x-cld-image-gallery>
Transformation Component
This component can be used within other components to apply transformations:
<x-cld-image public-id="example"> <x-cld-transformation width="300" height="300" crop="fill" gravity="auto" ></x-cld-transformation> <x-cld-transformation effect="sepia:50"></x-cld-transformation> </x-cld-image>
Disclaimer
This software/code provided under Cloudinary Labs is an unsupported pre-production prototype undergoing further development and provided on an “AS IS” basis without warranty of any kind, express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. Furthermore, Cloudinary is not under any obligation to provide a commercial version of the software.
Your use of the Software/code is at your sole risk and Cloudinary will not be liable for any direct, indirect, incidental, special, exemplary, consequential or similar damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of the Software, even if advised of the possibility of such damage.
You should refrain from uploading any confidential or personally identifiable information to the Software. All rights to and in the Software are and will remain at all times, owned by, or licensed to Cloudinary.
Contributions
Contributions are welcome! Please see CONTRIBUTING.md for details.
License
This package is open-sourced software licensed under the MIT license.