PHPackages                             popphp/pop-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. popphp/pop-storage

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

popphp/pop-storage
==================

Pop Storage Component for Pop PHP Framework

2.1.3(6mo ago)11.8k1[1 issues](https://github.com/popphp/pop-storage/issues)1BSD-3-ClausePHPPHP >=8.3.0CI passing

Since Nov 18Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/popphp/pop-storage)[ Packagist](https://packagist.org/packages/popphp/pop-storage)[ Docs](https://github.com/popphp/pop-storage)[ RSS](/packages/popphp-pop-storage/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (9)Dependencies (5)Versions (15)Used By (1)

pop-storage
===========

[](#pop-storage)

[![Build Status](https://github.com/popphp/pop-storage/workflows/phpunit/badge.svg)](https://github.com/popphp/pop-storage/actions)[![Coverage Status](https://camo.githubusercontent.com/4cbac7785e11ff38d1682ded09f2a3dc028dd48dfdff9f637163b2a5b28a9a7a/687474703a2f2f63632e706f707068702e6f72672f636f7665726167652e7068703f636f6d703d706f702d73746f72616765)](http://cc.popphp.org/pop-storage/)

[![Join the chat at https://discord.gg/TZjgT74U7E](https://camo.githubusercontent.com/acad7b0eeb78b78d08ffd2b85681ab243436388b5f86f8bcb956a69246e53739/68747470733a2f2f6d656469612e706f707068702e6f72672f696d672f646973636f72642e737667)](https://discord.gg/TZjgT74U7E)

- [Overview](#overview)
- [Install](#install)
- [Quickstart](#quickstart)
- [Adapters](#adapters)
    - [AWS S3](#aws-s3)
    - [Microsoft Azure](#microsoft-azure)
    - [Local Disk](#local-disk)
- [Working with Files](#working-with-files)
- [Directories](#directories)
- [Helper Methods](#helper-methods)

Overview
--------

[](#overview)

`pop-storage` is a storage component that provides interchangeable adapters to easily manage and switch between different storage resources. Supported storage adapters are:

- AWS S3
- Microsoft Azure
- Local Disk

**NOTE:** The use of enterprise storage solutions like AWS S3 and Microsoft Azure require credentials and permissions to be created in their respective administration portals. Please refer to the online documentation, guidelines and polices for whichever storage platform to which you are attempting to connect your application using this component. Please take care in granting access and assigning permissions to your application instance. Always follow the recommended security policies and guidelines of your chosen storage platform.

`pop-storage` is a component of the [Pop PHP Framework](https://www.popphp.org/).

[Top](#pop-storage)

Install
-------

[](#install)

Install `pop-storage` using Composer.

```
composer require popphp/pop-storage

```

Or, require it in your composer.json file

```
"require": {
    "popphp/pop-storage" : "^2.1.3"
}

```

[Top](#pop-storage)

Quickstart
----------

[](#quickstart)

A storage object can be created using one of the factories:

```
use Pop\Storage\Storage;

$storage = Storage::createAzure('ACCOUNT_NAME', 'ACCOUNT_KEY', 'CONTAINER');
```

Then a local file can be uploaded to the storage platform:

```
$storage->putFile('test.pdf');
```

Or, a remote file can be downloaded from the storage platform, which will return the file contents to be utilized within the application:

```
$fileContents = $storage->fetchFile('test.pdf');
```

[Top](#pop-storage)

Adapters
--------

[](#adapters)

By default, there are 3 available adapters. All of the adapters share the same interface and are interchangeable. Other adapters can be created, as long as they implement the same `Pop\Storage\StorageInterface`.

### AWS S3

[](#aws-s3)

The Amazon AWS S3 adapter interfaces with AWS S3 and requires the following credentials and access information to be obtained from the AWS administration console:

- AWS Key
- AWS Secret
- AWS Region
- AWS Version (usually `latest`)
- The AWS S3 bucket to access (in the format `s3://bucket`)

```
use Pop\Storage\Storage;

$storage = Storage::createS3('AWS_BUCKET', new S3\S3Client([
    'credentials' => [
        'key'    => 'AWS_KEY',
        'secret' => 'AWS_SECRET',
    ],
    'region'  => 'AWS_REGION',
    'version' => 'AWS_VERSION'
]));
```

### Microsoft Azure

[](#microsoft-azure)

The Microsoft Azure adapter interfaces with Microsoft Azure Storage and requires the following credentials and access information to be obtained from the AWS administration console:

- Account Name
- Account Key
- The Azure container to access (in the format `container`)

**Note:** The container should be configured to have "hierarchical namespace" support turned on for better support with filenames and folders.

```
use Pop\Storage\Storage;

$storage = Storage::createAzure('ACCOUNT_NAME', 'ACCOUNT_KEY', 'CONTAINER');
```

### Local Disk

[](#local-disk)

The local disk adapter allows simple management of files and folders on the local disk of the application using the same interface as the other adapters. This can be useful for local development and testing, before switching to one of the enterprise adapters for production.

It only needs the main directory to serve as the base location:

```
use Pop\Storage\Storage;

$storage = Storage::createLocal(__DIR__ . '/tmp/');
```

[Top](#pop-storage)

Working with Files
------------------

[](#working-with-files)

There are a number of available methods to assist in the uploading and downloading of files to and from the storage platform, as well as obtaining general data and information about them.

### Put a local file on the remote location

[](#put-a-local-file-on-the-remote-location)

Use a file on disk:

```
$storage->putFile('test.pdf');
```

Use a stream of file contents:

```
$storage->putFileContents('test.pdf', $fileContents);
```

### Fetch file contents

[](#fetch-file-contents)

This method returns the file contents to be utilized within the application:

```
$fileContents = $storage->fetchFile('test.pdf');
```

### Fetch file info

[](#fetch-file-info)

This method uses a custom request (i.e, a `HEAD` request) to return general information about a file without downloading the file's contents:

```
// Returns an array of file info:
$info = $storage->fetchFileInfo('test.pdf');
```

### Upload files from a server request ($\_FILES format)

[](#upload-files-from-a-server-request-_files-format)

```
$storage->uploadFiles($_FILES);
```

```
// Where $file follows the $_FILES array format specified in PHP:
// $file = ['tmp_name' => '/tmp/Hs87jdk', 'name' => 'test.pdf', 'size' => 8574, 'error' => 0]
$storage->uploadFile($file);
```

### List Files

[](#list-files)

You can list or search the files in the current location:

```
$files = $storage->listFiles();
```

```
$files = $storage->listFiles('test*');
```

```
$files = $storage->listFiles('*.pdf');
```

List all or search all directories and files together:

```
$all = $storage->listAll();
```

### Copy or move file from one remote location to another

[](#copy-or-move-file-from-one-remote-location-to-another)

```
// The source file remains
$storage->copyFile('test.pdf', 'foo/test2.pdf');
```

```
// The source file no longer exists
$storage->renameFile('test.pdf', 'foo/test2.pdf');
```

### Copy of move file from/to an external location on the same remote storage resource

[](#copy-of-move-file-fromto-an-external-location-on-the-same-remote-storage-resource)

This allows you to copy or move files between different AWS buckets or Azure containers that are outside the currently referenced bucket or container.

**To External**

```
// AWS example. The source file remains
$storage->copyFileToExternal('test.pdf', 's3://other-bucket/test.pdf');

// Azure example. The source file remains
$storage->copyFileToExternal('test.pdf', '/other-container/test.pdf');
```

```
// AWS example. The source file no longer exists
$storage->moveFileToExternal('test.pdf', 's3://other-bucket/test.pdf');

// Azure example. The source file no longer exists
$storage->moveFileToExternal('test.pdf', '/other-container/test.pdf');
```

**From External**

```
// AWS example. The source file remains
$storage->copyFileFromExternal('s3://other-bucket/test.pdf', 'test.pdf');

// Azure example. The source file remains
$storage->copyFileFromExternal('/other-container/test.pdf', 'test.pdf');
```

```
// AWS example. The source file no longer exists
$storage->moveFileToExternal('s3://other-bucket/test.pdf', 'test.pdf');

// Azure example. The source file no longer exists
$storage->moveFileToExternal('/other-container/test.pdf', 'test.pdf');
```

### Delete file

[](#delete-file)

```
$storage->deleteFile('test.pdf');
```

[Top](#pop-storage)

Directories
-----------

[](#directories)

The AWS and Azure storage resources don't explicitly support "directories" or "folders." However, they do still allow for a "directory-like" structure in the form of "prefixes." The `pop-storage` component normalizes that functionality into a more "directory-like" interface that allows the ability to change directories, make directories and remove directories.

**NOTE:** The creation or removal of empty directories is only allowed with the S3 and local adapters. The Azure storage resource doesn't allow the explicit creation or removal of empty directories. Instead, a new "directory" (prefix) is created automatically created with an uploaded file that utilizes a prefix. Conversely, a "directory" (prefix) is automatically removed when the last file that utilizes the prefix is deleted.

```
$storage = Storage::createS3('s3://my-bucket', new S3\S3Client([
    'credentials' => [
        'key'    => 'AWS_KEY',
        'secret' => 'AWS_SECRET',
    ],
    'region'  => 'AWS_REGION',
    'version' => 'AWS_VERSION'
]));

// Create the bucket 's3://my-bucket/foo'
$storage->mkdir('foo');

// Point the adapter at 's3://my-bucket/foo'
// Any files pushed will store here
// Any delete calls will delete files from here
$storage->chdir('foo');

// Removes the bucket and its content
$storage->rmdir('foo');
```

### List Directories

[](#list-directories)

You can list or search the directories in the current location:

```
$dirs = $storage->listDirs();
```

```
$dirs = $storage->listDirs('foo*');
```

```
$dirs = $storage->listDirs('*foo/');
```

List all or search all directories and files together:

```
$all = $storage->listAll();
```

[Top](#pop-storage)

Helper Methods
--------------

[](#helper-methods)

There are a number of helper methods to provide information on file status or things like whether or not the file exists.

```
var_dump($storage->fileExists('test.pdf'))    // Returns bool
var_dump($storage->isDir('foo'));             // Returns bool
var_dump($storage->isFile('test.pdf'));       // Returns bool
var_dump($storage->getFileSize('test.pdf'));  // Returns filesize value as an integer
var_dump($storage->getFileType('test.pdf'));  // Return either 'file' or 'dir'
var_dump($storage->getFileMTime('test.pdf')); // Returns date/time value
var_dump($storage->md5File('test.pdf'));      // Returns MD5 hash of file
```

[Top](#pop-storage)

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance47

Moderate activity, may be stable

Popularity22

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity69

Established project with proven stability

 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 ~135 days

Recently: every ~145 days

Total

9

Last Release

196d ago

Major Versions

1.0.1 → 2.0.02023-11-09

PHP version history (4 changes)1.0.0PHP >=7.4.0

2.0.0PHP >=8.1.0

2.1.0PHP >=8.2.0

2.1.3PHP >=8.3.0

### Community

Maintainers

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

---

Top Contributors

[![nicksagona](https://avatars.githubusercontent.com/u/898670?v=4)](https://github.com/nicksagona "nicksagona (77 commits)")

---

Tags

phpstorageaws-s3file storagepoppop phpazure blob

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/popphp-pop-storage/health.svg)

```
[![Health](https://phpackages.com/badges/popphp-pop-storage/health.svg)](https://phpackages.com/packages/popphp-pop-storage)
```

###  Alternatives

[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.6k263.6M790](/packages/league-flysystem-aws-s3-v3)[popphp/pop-db

Pop Db Component for Pop PHP Framework

1814.6k11](/packages/popphp-pop-db)[popphp/pop-http

Pop Http Component for Pop PHP Framework

1018.5k13](/packages/popphp-pop-http)

PHPackages © 2026

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