Download the PHP package popphp/pop-storage without Composer

pop-storage

• Overview
• Install
• Upgrading to 3.0
• Quickstart
• Adapters
  • AWS S3
  • Microsoft Azure
  • Local Disk
• Error Handling
• Working with Files
• Directories
• Helper Methods
• Accessing the Adapter Directly

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.

Top

Install

Install pop-storage using Composer.

composer require popphp/pop-storage

Or, require it in your composer.json file

"require": {
    "popphp/pop-storage" : "^3.0.0"
}

Top

Upgrading to 3.0

Version 3.0 is a deliberate breaking release that removes silent failures from the storage API. If you are upgrading from 2.x, three changes need attention. See Error Handling below for the full exception model this introduces; this section covers only what to change in existing code.

1. Failures throw exceptions instead of returning false or doing nothing.

Previously, a failed write could silently do nothing and a missing file could quietly return false. Now every operation either succeeds or throws a typed exception. The old per-layer Pop\Storage\Adapter\Exception and Pop\Storage\Adapter\Azure\Exception classes have been removed; catch the new Pop\Storage\Exception\* types instead (or Pop\Storage\Exception itself as a catch-all).

2. getFileSize(), getFileType(), getFileMTime() and md5File() no longer return false.

They now return int, string, int|string and string respectively. Code that tested the return value for false needs to catch an exception instead:

3. Path traversal is rejected.

Any path containing a .. segment now throws PathTraversalException rather than being resolved. This applies to every path-taking method, including the name value of an uploaded file array — which comes directly from $_FILES and is attacker-controlled. If any existing code relied on a .. segment being silently resolved, it will now throw instead.

Top

Quickstart

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

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

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

Top

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

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)

Microsoft Azure

The Microsoft Azure adapter interfaces with Microsoft Azure Storage and requires the following credentials and access information to be obtained from the Azure 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.

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:

Top

Error Handling

An operation on pop-storage either succeeds or throws a typed exception — there are no false return values or silent no-ops to check for. Every exception lives under Pop\Storage\Exception\* and extends Pop\Storage\Exception, so a single catch-all always works, with specific types available when you need to branch on the failure:

The available exception types are FileNotFoundException, DirectoryNotFoundException, UnableToWriteFileException, UnableToReadFileException, UnableToDeleteFileException, UnableToCopyFileException, UnableToMoveFileException, UnableToCreateDirectoryException, UnableToDeleteDirectoryException, UnableToGenerateTemporaryUrlException, UnsupportedOperationException and PathTraversalException.

A few methods are deliberate exceptions to the "always throw" rule:

• fileExists(), isDir() and isFile() always return bool. They're questions, not operations, so a path that simply isn't there is a normal false, not an error. (They can still throw PathTraversalException — see below — since that signals invalid input, not a negative answer.)
• getFileSize(), getFileType(), getFileMTime() and md5File() never return false. They return int, string, int|string and string respectively. A missing file throws FileNotFoundException; metadata that can't be read from an otherwise successful response throws UnableToReadFileException.

Path traversal is rejected. Any path containing a .. segment throws PathTraversalException rather than being resolved, on every path-taking method across every adapter — including the name value of an uploaded file array, which comes directly from $_FILES and is attacker-controlled. A single leading /, \, ./ or .\ is normalized away rather than rejected, so ordinary paths are unaffected.

Top

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

Use a file on disk:

Use a stream of file contents:

putFileContents() writes the file whether or not it already existed. If you specifically want to replace the contents of a file that must already be there — and get a FileNotFoundException if it isn't — use replaceFileContents() instead:

Fetch file contents

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

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:

Streaming files

For large files, the streaming methods move contents through a PHP stream resource instead of buffering the whole file in memory. putFileStream() writes from a readable resource:

And fetchFileStream() returns a readable resource, which the caller is responsible for closing:

Temporary (presigned) URLs

This method returns a time-limited URL that grants read access to a file without exposing your credentials or making the file public — an S3 presigned URL, or an Azure SAS-token URL:

The local disk adapter has no equivalent concept and throws Pop\Storage\Exception\UnsupportedOperationException.

Upload files from a server request ($_FILES format)

List Files

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

List all or search all directories and files together:

All three listing methods accept a second $recursive parameter (default false, which lists only the current location, one level deep). Passing true walks every level below the current location:

Recursive results are paths relative to the current location, including their intermediate directories, so each one can be passed straight back into fetchFile(), deleteFile(), and friends:

Copy or move file from one remote location to another

Copy of move file from/to 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

From External

Delete file

Top

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.

Base directory vs. current directory

setBaseDir()/getBaseDir() control the fixed root the storage object operates against (the bucket or container itself); getCurrentDir() reports wherever chdir() last pointed it:

chdir() always resolves from the base directory, not from wherever you last chdir'd — so it is not cumulative. Calling chdir('foo') and then chdir('bar') points at foo's sibling bar, not at foo/bar. Call chdir() with no argument to return to the base directory.

List Directories

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

List all or search all directories and files together:

And, as with the file listings, a second $recursive parameter walks every level below the current location:

Top

Helper Methods

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

fileExists(), isDir() and isFile() always return a bool. The four metadata methods below them never return false — if the file isn't there they throw Pop\Storage\Exception\FileNotFoundException, and if the metadata can't be read they throw Pop\Storage\Exception\UnableToReadFileException.

Top

Accessing the Adapter Directly

Storage delegates every method it exposes to whichever adapter it was created with, always matching the shared Pop\Storage\StorageInterface contract. A handful of capabilities are specific to one storage platform and only exist on that adapter's own class, not on the shared interface — reach them with getAdapter() (or its shorter alias, adapter()):

The Microsoft Azure adapter is currently the only one with extras beyond the interface, all related to Azure-specific blob behavior:

Top