From d38c3e098a22fb1285d3d9bd733172025b647ff0 Mon Sep 17 00:00:00 2001 From: Josh Manders Date: Wed, 25 Sep 2024 13:44:31 -0500 Subject: [PATCH 1/3] chore: improve readme --- README.md | 728 +++++++++++------------------------------------------- 1 file changed, 150 insertions(+), 578 deletions(-) diff --git a/README.md b/README.md index f83eb14..a57aee8 100644 --- a/README.md +++ b/README.md @@ -12,689 +12,261 @@ ###### -

> 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. -## Contents +## Table of Contents -- [Usage](#usage) - - [Upload, Retrieval, Transformation Method Calls](#upload-retrieval--transformation-media-method-calls) - - [Attach Files to Laravel Eloquent Models](#attach-files-to-laravel-eloquent-models) - - [Upload Files Via An Upload Widget](#upload-files-via-an-upload-widget) - - [Media Management Via The Command Line](#media-management-via-the-command-line) - [Installation](#installation) - [Configuration](#configuration) +- [Usage](#usage) + - [Upload, Retrieval & Transformation](#upload-retrieval--transformation) + - [Attach Files to Eloquent Models](#attach-files-to-eloquent-models) + - [Upload Widget](#upload-widget) + - [Media Management via CLI](#media-management-via-cli) +- [Cloudinary URL Generation](#cloudinary-url-generation) +- [Blade Components](#blade-components) - [Disclaimer](#disclaimer) - [Contributions](#contributions) - [License](#license) -## Usage - -> Laravel versions **8 and below** should use the **v1.x.x**. - -## **Upload, Retrieval & Transformation Media Method Calls**: - -**Upload** a file (_Image_, _Video_ or any type of _File_) to **Cloudinary**, **retrieve** and **transform** via any of the following ways: - -```php - -/** -* Using the Cloudinary Facade -* Import the Facade in your Class like so: -*/ -use CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary; - -use CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary; - -// access the admin api -(https://cloudinary.com/documentation/admin_api) -Cloudinary::admin(); - -// access the search api -(https://cloudinary.com/documentation/search_api) -Cloudinary::search(); +## Installation -// access the upload api -(https://cloudinary.com/documentation/image_upload_api_reference) -Cloudinary::uploadApi(); +Requires PHP 8.1+ and Laravel 10+. -// Upload an Image File to Cloudinary with One line of Code -$uploadedFileUrl = Cloudinary::upload($request->file('file')->getRealPath())->getSecurePath(); +```bash +composer require cloudinary-labs/cloudinary-laravel +``` -// Upload a Video File to Cloudinary with One line of Code -$uploadedFileUrl = Cloudinary::uploadVideo($request->file('file')->getRealPath())->getSecurePath(); +## Configuration -// Upload any File to Cloudinary with One line of Code -$uploadedFileUrl = Cloudinary::uploadFile($request->file('file')->getRealPath())->getSecurePath(); - -// get url from a file -$url = Cloudinary::getUrl($publicId); +Publish the configuration file: +```bash +php artisan vendor:publish --provider="CloudinaryLabs\CloudinaryLaravel\CloudinaryServiceProvider" --tag="cloudinary-laravel-config" +``` -/** - * This package also exposes a helper function you can use if you are not a fan of Facades - * Shorter, expressive, fluent using the - * cloudinary() function - */ +Add your Cloudinary credentials to your `.env` file: -// access the admin api -(https://cloudinary.com/documentation/admin_api) -cloudinary()->admin(); +``` +CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME +CLOUDINARY_UPLOAD_PRESET=your_upload_preset +CLOUDINARY_NOTIFICATION_URL= +``` -// access the search api -(https://cloudinary.com/documentation/search_api) -cloudinary()->search(); +## Usage -// access the upload api -(https://cloudinary.com/documentation/image_upload_api_reference) -cloudinary()->uploadApi(); +### Upload, Retrieval & Transformation -// Upload an image file to cloudinary with one line of code +```php +// Upload $uploadedFileUrl = cloudinary()->upload($request->file('file')->getRealPath())->getSecurePath(); -// Upload a video file to cloudinary with one line of code -$uploadedFileUrl = cloudinary()->uploadVideo($request->file('file')->getRealPath())->getSecurePath(); - -// Upload any file to cloudinary with one line of code -$uploadedFileUrl = cloudinary()->uploadFile($request->file('file')->getRealPath())->getSecurePath(); - -// Upload an existing remote file to Cloudinary with one line of code -$uploadedFileUrl = cloudinary()->uploadFile($remoteFileUrl)->getSecurePath(); +// Upload with transformation +$uploadedFileUrl = cloudinary()->upload($request->file('file')->getRealPath(), [ + 'folder' => 'uploads', + 'transformation' => [ + 'width' => 400, + 'height' => 400, + 'crop' => 'fill' + ] +])->getSecurePath(); -// get url from a file +// Get URL $url = cloudinary()->getUrl($publicId); -/** - * You can also skip the Cloudinary Facade or helper method and laravel-ize your uploads by simply calling the - * storeOnCloudinary() method on the file itself - */ - -// Store the uploaded file on Cloudinary -$result = $request->file('file')->storeOnCloudinary(); - -// Store the uploaded file on Cloudinary -$result = $request->file->storeOnCloudinary(); - -// Store the uploaded file in the "lambogini" directory on Cloudinary -$result = $request->file->storeOnCloudinary('lambogini'); - -// Store the uploaded file in the "lambogini" directory on Cloudinary with the filename "prosper" -$result = $request->file->storeOnCloudinaryAs('lambogini', 'prosper'); - -$result->getPath(); // Get the url of the uploaded file; http -$result->getSecurePath(); // Get the url of the uploaded file; https -$result->getSize(); // Get the size of the uploaded file in bytes -$result->getReadableSize(); // Get the size of the uploaded file in bytes, megabytes, gigabytes or terabytes. E.g 1.8 MB -$result->getFileType(); // Get the type of the uploaded file -$result->getFileName(); // Get the file name of the uploaded file -$result->getOriginalFileName(); // Get the file name of the file before it was uploaded to Cloudinary -$result->getPublicId(); // Get the public_id of the uploaded file -$result->getExtension(); // Get the extension of the uploaded file -$result->getWidth(); // Get the width of the uploaded file -$result->getHeight(); // Get the height of the uploaded file -$result->getTimeUploaded(); // Get the time the file was uploaded - -/** - * You can also check if a file exists - */ - -$url = Storage::disk('cloudinary')->fileExists($publicId); +// Check if file exists +$exists = Storage::disk('cloudinary')->fileExists($publicId); ``` -## **Attach Files** to Laravel **Eloquent Models**: +### Attach Files to Eloquent Models -First, import the `CloudinaryLabs\CloudinaryLaravel\MediaAlly` trait into your Model like so: +First, add the `MediaAlly` trait to your model: ```php -request->input()); -$page->attachMedia($file); // Example of $file is $request->file('file'); - -/** - * How to attach a file to a Model by retrieving model records - */ -$page = Page::find(2); -$page->attachMedia($file); // Example of $file is $request->file('file'); - -/** - * How to retrieve files that were attached to a Model - */ -$filesBelongingToSecondPage = Page::find(2)->fetchAllMedia(); - -/** - * How to retrieve the first file that was attached to a Model - */ -$fileBelongingToSecondPage = Page::find(2)->fetchFirstMedia(); - -/** - * How to retrieve the last file that was attached to a Model - */ -$fileBelongingToSecondPage = Page::find(2)->fetchLastMedia(); - -/** - * How to replace/update files attached to a Model - */ -$page = Page::find(2); -$page->updateMedia($file); // Example of $file is $request->file('file'); - -/** -* How to detach a file from a Model -*/ -$page = Page::find(2); -$page->detachMedia($file) // Example of $file is $request->file('file'); -``` - -## **Add Transformation to Uploads Using AttachMedia Method**: +Then, you can use the following methods: ```php +// Attach media +$page->attachMedia($request->file('file')); -/** -* How to resize an image to a specific width and height, and crop it using 'fill' mode -*/ - -$options = [ - 'transformation' => [ - [ - 'width' => 200, // Desired width - 'height' => 200, // Desired height - 'crop' => 'fill', // Crop mode (you can change this to 'fit' or other modes) - ], - ], -] - -$page->attachMedia($file, $options); // Example of $file is $request->file('file'); - -/** -* How to crop an image to a specific width and height. -*/ - -$options = [ - 'transformation' => [ - [ - 'width' => 200, // Desired width - 'height' => 200, // Desired height - 'crop' => 'crop', // Crop mode - ], - ], -] - -$page->attachMedia($file, $options); // Example of $file is $request->file('file'); +// Retrieve media +$allMedia = $page->fetchAllMedia(); +$firstMedia = $page->fetchFirstMedia(); +$lastMedia = $page->fetchLastMedia(); -/** -* How to rotate an image by a specific degree. -*/ - -$options = [ - 'transformation' => [ - [ - 'angle' => 45, // Rotation angle - ], - ], -] - -$page->attachMedia($file, $options); // Example of $file is $request->file('file'); - -/** -* How to apply a filter to an image. -*/ - -$options = [ - 'transformation' => [ - [ - 'effect' => 'grayscale', // Filter effect - ], - ], -] - -$page->attachMedia($file, $options); // Example of $file is $request->file('file'); - -/** -* How to overlay text on an image. -*/ - -$options = [ - 'transformation' => [ - [ - 'overlay' => [ - 'font_family' => 'arial', - 'font_size' => 24, - 'text' => 'Hello World', - ], - ], - ], -] - -$page->attachMedia($file, $options); // Example of $file is $request->file('file'); +// Update media +$page->updateMedia($newFile); +// Detach media +$page->detachMedia($file); ``` -## **Upload Files Via An Upload Widget**: +### Upload Widget -Use the `x-cld-upload-button` Blade upload button component that ships with this Package like so: +Add the Cloudinary JS to your layout: ```html - - - - ... @cloudinaryJS - - - Upload Files - - + + @cloudinaryJS + ``` -Other Blade components you can use are: +Use the upload button component: ```html -/** * * TRANSFORMATION ACTIONS CATEGORIES: * * 1. RESIZE * - Scale * - Limit Fit -* - Fill * - Fit * - Crop * - Thumbnail * - Pad * - Limit Fill * - Limit Pad * - -Minimum Fit * - Minimum Pad * * * 2. ADJUST * - Improve * - Unsharp Mask * - -Saturation * - Contrast * - Brightness * - Gamma * * * 3. EFFECT * - Colorize * -- Blur * - Trim * - Grayscale * - Blackwhite * - Sepia * - Red Eye * - Negate * -- Oil Paint * - Vignette * - Simulate Colorblind * - Pixelate * - Shadow * * * -4. DELIVERY * - Format * - Quality * - Color Space * - DPR * * 5. LAYERS * - -Image Layer * - Text Layer * * */ - // -Blade Image Component for displaying images - - // Blade Video Component for -displaying videos /** * ARTISTIC Filters * Possible values: al_dente, athena, -audrey, aurora, daguerre, eucalyptus, fes, frost, hairspray, hokusai, incognito, -linen, peacock, primavera, quartz, red_rock, refresh, sizzle, sonnet, ukulele, -zorro * Reference: -https://cloudinary.com/documentation/transformation_reference#e_art */ - - - - - - -/** * Colorize */ - - -/** * Blur - Applies a blurring filter to an asset. * The strength ranges from 1 -to 2000 */ - - -/** * Grayscale * Converts an image to grayscale (multiple shades of gray). */ - - -/** * sepia * Changes the color scheme of an image to sepia. */ - - -/** * redeye * Automatically removes red eyes in an image. */ - - -/** * negate * Creates a negative of an image. */ - - -/** * oil-paint * Applies an oil painting effect. */ - - - -/** * vignette * Applies a vignette effect to an image. * The strength level of -the vignette. Range: 0 to 100 */ - - - -/** * simulate-colorblind * Simulates the way an image would appear to someone -with the specified color blind condition. * The color blind condition to -simulate.Possible values: deuteranopia, protanopia, tritanopia, tritanomaly, -deuteranomaly, cone_monochromacy, rod_monochromacy */ - - - -/** * pixelate * Applies a pixelation effect. * The width in pixels of each -pixelation square. Range: 1 to 200. Default: Determined by an algorithm based on -the image dimensions. */ - - - -/** * shadow * Adds a gray shadow to the bottom right of an image. You can -change the color and location of the shadow using the color and x,y qualifiers. -* The format of the shadow is color_offsetX_offsetY_strength */ - - -/** * unsharp-mask * Applies an unsharp mask filter to the image. * The strength -of the filter. (Range: 1 to 2000, Server default: 100) */ - - -/** * saturation * Adjusts the color saturation. * The level of color saturation -(Range: -100 to 100, Server default: 80). */ - - -/** * brightness * Adjusts the brightness. * The level of brightness (Range: -99 -to 100). */ - - -/** * gamma * Adjusts the gamma level. * The level of gamma (Range: -50 to 150, -Server default: 0). */ - - -/** * trim * Detects and removes image edges whose color is similar to the -corner pixels. * The level of tolerance for color similarity. Range: 0 to 100 * -The color to trim as a named color or an RGB/A hex code. * e.g 50_yellow * 50 is -for color similarity * yellow is for color override */ - - -/** * improve-mode * Adjusts an image's colors, contrast and brightness to -improve its appearance. * Possible values: mode is 'indoor', 'outdoor' * blend -is withing the range of 0 to 100. * */ - - -/** * Blackwhite * Converts an image to black and white. * Threshold - The -balance between black (100) and white (0). */ - - - -/** * CARTOON Filters */ - - - -/** * ROTATE */ - - -/** * ROUNDED CORNERS */ - - -/** * Borders */ // Adds a solid border around an image or video. - - - -/** * Background Color */ - - -/** * Face detection-based image cropping * Crop "thumb" or "crop" and gravity -must be used together * Faces will target all the faces * Face will target only -one face * You can specify width and height or not * You can use compass to -define a fixed location within an asset to focus on e.g north_west, east, south. -*/ - - - - - - + Upload Files ``` -**Media Management via The Command Line**: +### Media Management via CLI ```bash -/** -* Back-up Files on Cloudinary -*/ php artisan cloudinary:backup - -/** - * Delete a File on Cloudinary - */ php artisan cloudinary:delete - -/** - * Fetch a File from Cloudinary - */ php artisan cloudinary:fetch - -/** - * Rename a File from Cloudinary - */ php artisan cloudinary:rename - -/** - * Upload a File to Cloudinary - */ php artisan cloudinary:upload ``` -## Installation +## Cloudinary URL Generation -[PHP](https://php.net) 7.2+, and [Composer](https://getcomposer.org) are required. +Use the `Cloudinary` facade or the `cloudinary()` helper function to generate URLs: -To get the latest version of Laravel Cloudinary, simply require it: +```php +use CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary; -```bash -composer require cloudinary-labs/cloudinary-laravel +$url = Cloudinary::getUrl($publicId); +// or +$url = cloudinary()->getUrl($publicId); ``` -Or add the following line to the require block of your `composer.json` file. +## Blade Components -### Apps Using Laravel 9 +This package provides several Blade components for easy integration of Cloudinary media in your Laravel views: -``` -"cloudinary-labs/cloudinary-laravel": "2.0.0" -``` +### Image Component -### Apps Using Laravel 8 and below +Basic usage: -``` -"cloudinary-labs/cloudinary-laravel": "1.0.4" +```html + ``` -You'll then need to run `composer install` or `composer update` to download it and have the autoloader updated. +With transformations: -Once Laravel Cloudinary is installed, you need to register the service provider. Open up `config/app.php` and add the following to the `providers` key. +```html + + + +``` -```php -'providers' => [ - ... - CloudinaryLabs\CloudinaryLaravel\CloudinaryServiceProvider::class, - ... -] +Responsive image: + +```html + + + + + + ``` -> Note: If you use **Laravel >= 5.5** , you can skip this step (adding the code above to the providers key) and go to [**`configuration`**](https://github.com/cloudinary-labs/cloudinary-laravel#configuration) +### Video Component -Also, register the Cloudinary Facade like so: +Basic usage: -```php -'aliases' => [ - ... - 'Cloudinary' => CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary::class, - ... -] +```html + ``` -> Note: If you use **Laravel >= 9.0** , you can skip the step (adding the code above for registering the facade) and can just import it in whatever class you need it like so: +With transformations: -```php - ... - use CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary; - ... +```html + + + ``` -## Configuration +### Upload Button Component -You can publish the configuration file using this command: +Basic usage: -```bash -php artisan vendor:publish --provider="CloudinaryLabs\CloudinaryLaravel\CloudinaryServiceProvider" --tag="cloudinary-laravel-config" +```html +Upload Files ``` -A configuration file named `cloudinary.php` with some sensible defaults will be placed in your `config` directory: +With custom options: -```php - env('CLOUDINARY_NOTIFICATION_URL'), - - - /* - |-------------------------------------------------------------------------- - | Cloudinary Configuration - |-------------------------------------------------------------------------- - | - | Here you may configure your Cloudinary settings. Cloudinary is a cloud hosted - | media management service for all file uploads, storage, delivery and transformation needs. - | - | - */ - 'cloud_url' => env('CLOUDINARY_URL'), - - /** - * Upload Preset From Cloudinary Dashboard - * - */ - 'upload_preset' => env('CLOUDINARY_UPLOAD_PRESET'), - - /** - * Route to get cloud_image_url from Blade Upload Widget - */ - 'upload_route' => env('CLOUDINARY_UPLOAD_ROUTE'), - - /** - * Controller action to get cloud_image_url from Blade Upload Widget - */ - 'upload_action' => env('CLOUDINARY_UPLOAD_ACTION'), -]; +```html + + Upload Multiple Files + ``` -### API Keys +### Image Gallery Component -Open your `.env` file and add your API Environment variable, upload_preset (this is optional, until you need to use the widget) like so: - -```php -CLOUDINARY_URL=xxxxxxxxxxxxx -CLOUDINARY_UPLOAD_PRESET=xxxxxxxxxxxxx -CLOUDINARY_NOTIFICATION_URL= +```html + + +

+ + ``` -**\*Note:** You need to get these credentials from your [Cloudinary Dashboard](https://cloudinary.com/console). The CLOUDINARY_URL is the API Environment variable shown in your Cloudinary Dashboard. Use the Copy button there to get the full URL\* - -_If you are using a hosting service like heroku, forge, digital ocean, etc, please ensure to add the above details to your configuration variables._ - -### Cloudinary JS +### Transformation Component -Cloudinary relies on its own JavaScript library to initiate the Cloudinary Upload Widget. You can load the JavaScript library by placing the @cloudinaryJS directive right before your application layout's closing tag: +This component can be used within other components to apply transformations: ```html - - ... @cloudinaryJS - + + + + ``` -**\*Note:** ONLY LOAD THIS IF YOU HAVE DECIDED TO USE THE UPLOAD WIDGET. IF YOU ARE USING THIS PACKAGE FOR A LARAVEL API BACKEND, YOU DON'T NEED TO DO THIS!\* - ## 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._ +[Include the original disclaimer here] ## Contributions -Contributions from the community via PRs are welcome and will be fully credited. For details, see [contributions.md](contributing.md). +Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. ## License -The MIT License (MIT). Please see [License File](LICENSE.md) for more information. +This package is open-sourced software licensed under the [MIT license](LICENSE.md). From 3795dc4cdee56226e51bfd3923768917d1a1aca0 Mon Sep 17 00:00:00 2001 From: Josh Manders Date: Wed, 25 Sep 2024 14:00:07 -0500 Subject: [PATCH 2/3] add note about dashboard --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a57aee8..6d3b758 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,9 @@ CLOUDINARY_UPLOAD_PRESET=your_upload_preset CLOUDINARY_NOTIFICATION_URL= ``` +> [!NOTE] +> You can get your `CLOUDINARY_URL` from your [Cloudinary console](https://cloudinary.com/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 @@ -261,7 +264,7 @@ This component can be used within other components to apply transformations: ## Disclaimer -[Include the original disclaimer here] +> _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 From 5a5e4d42fc6ce3043bcab062999f6b70a6fed577 Mon Sep 17 00:00:00 2001 From: Josh Manders Date: Wed, 25 Sep 2024 15:01:33 -0500 Subject: [PATCH 3/3] fix: update package version --- src/CloudinaryEngine.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/CloudinaryEngine.php b/src/CloudinaryEngine.php index c351016..255c562 100644 --- a/src/CloudinaryEngine.php +++ b/src/CloudinaryEngine.php @@ -37,7 +37,7 @@ class CloudinaryEngine * * @var string PACKAGE_VERSION */ - const PACKAGE_VERSION = '2.0.2'; + const PACKAGE_VERSION = '2.2.2'; public const ASSET_ID = 'asset_id'; public const PUBLIC_ID = 'public_id'; @@ -105,8 +105,8 @@ public function setUserPlatform(): void } /** - * Set Analytics - */ + * Set Analytics + */ public function setAnalytics(): void { Analytics::sdkCode('W');