PHPackages                             danilowa/laravel-easy-cloud-storage - 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. danilowa/laravel-easy-cloud-storage

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

danilowa/laravel-easy-cloud-storage
===================================

A robust and flexible Laravel package for managing files in various cloud storage providers.

1.0.3(1y ago)014MITPHPPHP ^8.1|^8.2

Since Sep 24Pushed 1y ago1 watchersCompare

[ Source](https://github.com/DaniloWA/laravel-easy-cloud-storage)[ Packagist](https://packagist.org/packages/danilowa/laravel-easy-cloud-storage)[ Docs](https://github.com/DaniloWA/laravel-easy-cloud-storage)[ RSS](/packages/danilowa-laravel-easy-cloud-storage/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (1)Versions (5)Used By (0)

Laravel EasyCloudStorage
========================

[](#laravel-easycloudstorage)

Laravel EasyCloudStorage is a flexible and intuitive package designed to simplify cloud storage management within Laravel applications. It provides a clean interface for interacting with various storage providers, including local disks, Amazon S3, and Google Cloud Storage.

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Initial Example](#initial-example)
    - [File Operations](#file-operations)
        - [Uploading Files](#uploading-files)
        - [Downloading Files](#downloading-files)
        - [Getting File URL](#getting-file-url)
        - [Deleting Files](#deleting-files)
        - [Checking File Existence](#checking-file-existence)
        - [Copying Files](#copying-files)
        - [Moving Files](#moving-files)
        - [Getting File Size](#getting-file-size)
        - [Getting Last Modified Time](#getting-last-modified-time)
        - [Getting Metadata](#getting-metadata)
        - [Setting Metadata](#setting-metadata)
        - [Listing Files](#listing-files)
        - [Prepending and Appending Data](#prepending-and-appending-data)
        - [Creating and Deleting Directories](#creating-and-deleting-directories)
    - [Error Handling](#error-handling)
    - [Driver-Specific Method Availability](#driver-specific-method-availability)
    - [Design Patterns: Facade and Contracts](#design-patterns-facade-and-contracts)
- [License](#license)

Installation
------------

[](#installation)

To install the package, run the following command via Composer:

```
composer require danilowa/laravel-easy-cloud-storage
```

After installation, the service provider will be automatically registered. To customize the configuration, publish the package's config file:

```
php artisan vendor:publish --provider="Danilowa\LaravelEasyCloudStorage\EasyCloudStorageServiceProvider"
```

Configuration
-------------

[](#configuration)

The configuration file is located at `config/easycloudstorage.php`. The main settings include:

```
return [
    'default' => 'local', // Default disk for storage operations.
    'log_errors' => false, // Enable error logging.
    'throw_errors' => false, // Enable exception throwing for errors.
    'disks' => [
        'local' => [
            'driver' => 'local',
            'root' => storage_path('app'), // Root path for local storage.
        ],
        's3' => [
            'driver' => 's3',
            'key' => env('AWS_ACCESS_KEY_ID'),
            'secret' => env('AWS_SECRET_ACCESS_KEY'),
            'region' => env('AWS_DEFAULT_REGION'),
            'bucket' => env('AWS_BUCKET'),
            'url' => env('AWS_URL'),
        ],
        'google' => [
            'driver' => 'gcs',
            'project_id' => env('GOOGLE_CLOUD_PROJECT_ID'),
            'key_file' => env('GOOGLE_CLOUD_KEY_FILE'),
            'bucket' => env('GOOGLE_CLOUD_STORAGE_BUCKET'),
            'url' => env('GOOGLE_CLOUD_URL'),
        ],
        // Additional providers can be added as needed.
    ],
];
```

Usage
-----

[](#usage)

After configuration, you can use the EasyCloudStorage package for various operations.

### Initial Example

[](#initial-example)

This section demonstrates how to perform a file upload using the EasyCloudStorage package. The example illustrates the process of uploading a file to a specified directory, along with optional logging and error handling configurations.

```
use Danilowa\LaravelEasyCloudStorage\Facades\EasyStorage;

// Assume $uploadedFile is an instance of UploadedFile, obtained from an HTTP request.
$filePath = EasyStorage::upload($uploadedFile, 'uploads/myfile.txt')
    ->withLog(true)  // Set error logging behavior. Defaults to true if not specified.
    ->withError(false) // Set error handling behavior. Defaults to true if not specified.
    ->setDisk('s3'); // Specify the disk manually instead of using the default.

// Check if the upload was successful
if($filePath === false) {
    return echo "Error uploading the file.";
}

echo "File uploaded successfully: $filePath";
```

### Explanation of the Code:

[](#explanation-of-the-code)

1. **Use Statement:**

    - The `use` statement imports the `EasyStorage` facade, which allows you to access storage functionalities easily.
2. **Uploading a File:**

    - The `upload` method is called on the `EasyStorage` facade, taking in:
        - `$uploadedFile`: An instance of `UploadedFile`, typically obtained from a file upload in an HTTP request.
        - `'uploads/myfile.txt'`: The destination path where the file will be stored on the disk.
3. **Error Logging Configuration:**

    - The `withLog` method allows you to control error logging during the upload process:
        - **Enabled (true):** Error logging is activated for the upload operation.
        - **Disabled (false):** Turns off error logging.
        - **Default Behavior:** If called without parameters, it assumes `true`, enabling error logging by default.
        - **Configuration Fallback:** If not used, the package utilizes the error logging setting specified in the configuration file.
4. **Error Handling Configuration:**

    - The `withError` method configures whether to throw exceptions when errors occur during the upload process:
        - **Throw Exceptions (true):** System will throw exceptions for any encountered errors.
        - **Do Not Throw Exceptions (false):** Prevents exceptions from being thrown.
        - **Default Behavior:** If called without parameters, it defaults to `true`.
        - **Configuration Fallback:** Follows the error handling configuration specified in the configuration file.
5. **Setting the Disk:**

    - The `setDisk` method allows you to manually specify the storage disk to be used, overriding the default disk configuration.
6. **Success Check:**

    - After attempting the upload, the result is stored in `$filePath`. This variable will either contain a string representing the path to the uploaded file or `false` if the upload failed.
    - The `if` statement checks the value of `$filePath` to determine the success of the upload:
        - **Successful Upload:** If `$filePath` is of type `string`, it prints a message displaying the path of the uploaded file.
        - **Unsuccessful Upload:** If `$filePath` is `false`, it indicates that the upload failed, and an error message is displayed.

### File Operations

[](#file-operations)

#### Uploading Files

[](#uploading-files)

Upload a file to the specified path on the storage disk.

```
$filePath = EasyStorage::upload($uploadedFile, 'uploads/myfile.txt', 'banana.txt');

// Upload to a specific disk (S3)
$filePathS3 = EasyStorage::upload($uploadedFile, 'uploads/myfile.txt')->setDisk('s3');
```

- **Parameters:**

    - `UploadedFile $file`: The file to upload.
    - `string $path`: The destination path for the upload.
    - `string|null $newName`: Optional. The new name for the file; the original name is used if not provided.
- **Returns:** `string|false` - The file path if successful; `false` otherwise.

#### Downloading Files

[](#downloading-files)

Download a file from the specified path on the storage disk.

```
return EasyStorage::download('uploads/myfile.txt', 'name.txt')->withLog();
```

- **Parameters:**

    - `string $path`: The path of the file to download.
    - `string|null $newName`: Optional. The new name for the downloaded file; the original name is used if not provided.
- **Returns:** `BinaryFileResponse`
- **Throws:** `NotFoundHttpException` if the file does not exist.

#### Getting File URL

[](#getting-file-url)

Retrieve the URL of the stored file.

```
$fileUrl = EasyStorage::url('uploads/myfile.txt');
```

- **Parameters:**

    - `string $path`: The path of the file.
- **Returns:** `string` - The URL of the file.

#### Deleting Files

[](#deleting-files)

Delete a file at the specified path.

```
$deleted = EasyStorage::delete('uploads/myfile.txt');
```

- **Parameters:**

    - `string $path`: The path of the file to be deleted.
- **Returns:** `bool` - Returns `true` on success, `false` otherwise.

#### Checking File Existence

[](#checking-file-existence)

Check if a file exists at the specified path.

```
$exists = EasyStorage::exists('uploads/myfile.txt');
```

- **Parameters:**

    - `string $path`: The path of the file.
- **Returns:** `bool` - Returns `true` if it exists, `false` otherwise.

#### Copying Files

[](#copying-files)

Copy a file from a source path to a destination path.

```
$copied = EasyStorage::copy('uploads/myfile.txt', 'uploads/myfile_copy.txt');
```

- **Parameters:**

    - `string $from`: The path of the source file.
    - `string $to`: The destination path.
- **Returns:** `bool` - Returns `true` on success, `false` otherwise.

#### Moving Files

[](#moving-files)

Move or rename a file.

```
$success = EasyStorage::move('uploads/myfile.txt', 'uploads/newfile.txt');
```

- **Parameters:**
    - `string $from`: The old path of the file.
    - `string

$to`: The new path.

- **Returns:** `bool` - Returns `true` on success, `false` otherwise.

#### Getting File Size

[](#getting-file-size)

Retrieve the size of a file in bytes.

```
$size = EasyStorage::size('uploads/myfile.txt');
```

- **Parameters:**

    - `string $path`: The path of the file.
- **Returns:** `int|null` - Returns the file size in bytes or `null` if the file does not exist.

#### Getting Last Modified Time

[](#getting-last-modified-time)

Get the last modified timestamp of a file.

```
$lastModified = EasyStorage::lastModified('uploads/myfile.txt');
```

- **Parameters:**

    - `string $path`: The path of the file.
- **Returns:** `int|null` - Returns the timestamp or `null` if the file does not exist.

#### Getting Metadata

[](#getting-metadata)

Retrieve metadata for a file.

```
$metadata = EasyStorage::metadata('uploads/myfile.txt');
```

- **Parameters:**

    - `string $path`: The path of the file.
- **Returns:** `array|null` - Returns metadata or `null` if the file does not exist.

#### Setting Metadata

[](#setting-metadata)

Set metadata for a file.

```
$success = EasyStorage::setMetadata('uploads/myfile.txt', [
    'Content-Type' => 'application/pdf',
]);
```

- **Parameters:**

    - `string $path`: The path of the file.
    - `array $metadata`: The metadata to set.
- **Returns:** `bool` - Returns `true` on success, `false` otherwise.

#### Listing Files

[](#listing-files)

List files in a specified directory.

```
$files = EasyStorage::list('uploads');
```

- **Parameters:**

    - `string $directory`: The directory path.
- **Returns:** `array` - An array of file names.

#### Prepending and Appending Data

[](#prepending-and-appending-data)

Prepend or append data to a file.

```
$successPrepend = EasyStorage::prepend('uploads/myfile.txt', 'Header data');
$successAppend = EasyStorage::append('uploads/myfile.txt', 'Footer data');
```

- **Parameters:**

    - `string $path`: The path of the file.
    - `string $data`: The data to prepend or append.
- **Returns:** `bool` - Returns `true` on success, `false` otherwise.

#### Creating and Deleting Directories

[](#creating-and-deleting-directories)

Create or delete a directory.

```
EasyStorage::createDirectory('uploads/new_directory');
EasyStorage::deleteDirectory('uploads/old_directory');
```

- **Parameters:**

    - `string $directory`: The directory path.
- **Returns:** `bool` - Returns `true` on success, `false` otherwise.

### Error Handling

[](#error-handling)

You can enable error logging and exception throwing through the configuration or method chaining. Use the `withLog()` and `withError()` methods to customize error handling per operation.

### Driver-Specific Method Availability

[](#driver-specific-method-availability)

It's important to note that not all storage drivers will support every method available in the EasyCloudStorage package. The functionality provided depends exclusively on the capabilities of each specific driver, such as Google Cloud Storage, Amazon S3, and others.

For example, while uploading and deleting files are common operations across most drivers, certain methods like managing metadata or creating directories may not be supported by all drivers.

Rest assured, the EasyCloudStorage package has built-in logic to handle these discrepancies gracefully. If a method is not available for a specific driver, an informative error will be returned, ensuring that you are promptly notified of the limitation. This design allows you to implement your logic without the worry of unexpected failures, promoting a smooth development experience.

### Design Patterns: Facade and Contracts

[](#design-patterns-facade-and-contracts)

**Facade**

The Facade pattern in Laravel offers a simple and intuitive interface to access classes within the application’s service container. By utilizing the EasyStorage facade, you can invoke methods directly without having to resolve the underlying service each time. This approach not only streamlines your code but also improves readability, allowing you to concentrate on building features rather than managing complex dependencies. The result is a cleaner and more efficient API that enhances your development experience.

**Contracts**

Contracts in Laravel define the expected behaviors of services, providing a clear guideline for how they should operate. By utilizing contracts, you ensure that your application can easily switch between different implementations of a service without affecting the code that interacts with it. This flexibility is beneficial for developers, as it allows for easier updates or changes to the underlying logic without requiring significant code alterations.

For users, this means a more reliable and maintainable application. You can confidently integrate new features or optimize existing ones while ensuring that the core functionality remains intact. By adhering to this practice, you also promote a clean architecture that is easier to understand and extend, ultimately enhancing the long-term sustainability of your codebase.

License
-------

[](#license)

This package is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance36

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~0 days

Total

4

Last Release

594d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e4f30ad7f9d8c8922f3fcdc779352947b73b74edbb0f9397801658f1f7e7ce74?d=identicon)[DaniloWA](/maintainers/DaniloWA)

---

Top Contributors

[![DaniloWA](https://avatars.githubusercontent.com/u/41596835?v=4)](https://github.com/DaniloWA "DaniloWA (8 commits)")

---

Tags

cloudcloud-storagedanilodanilo-oliveiradanilowaeasy-storagefile-downloadfile-managementfile-uploadgoogle-cloudlaraveloliveiraphp-packages3storagestorage-abstractionapilaravelfilestoragecloud-storagefile storageimage storagedanilooliveiraDaniloWAlaravel-easy-cloud-storageeasy-cloud-storageeasy-cloudeasy-storage

### Embed Badge

![Health badge](/badges/danilowa-laravel-easy-cloud-storage/health.svg)

```
[![Health](https://phpackages.com/badges/danilowa-laravel-easy-cloud-storage/health.svg)](https://phpackages.com/packages/danilowa-laravel-easy-cloud-storage)
```

###  Alternatives

[unisharp/laravel-fileapi

Laravel File API - Handle Files with Laravel Storage

5345.3k](/packages/unisharp-laravel-fileapi)[zgldh/laravel-upload-manager

Upload, validate, storage, manage by API for Laravel 5/6/7/8/9

795.5k2](/packages/zgldh-laravel-upload-manager)[gliterd/laravel-backblaze-b2

Backblaze B2 Cloud Storage for Laravel 5

5341.6k](/packages/gliterd-laravel-backblaze-b2)[zing/laravel-flysystem-obs

Flysystem Adapter for OBS

1211.2k](/packages/zing-laravel-flysystem-obs)

PHPackages © 2026

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