GFA_File

The GFA_File class provides an API that allows to work with files handled and protected by the Groups File Access extension. It provides methods to create, read, update and delete file entries and maintain the files in the protected native storage.

The class allows to transfer files to the protected native storage and maintain the records that contain the information that is related to those files. It also allows to enter records for files stored on Amazon S3.

The methods provided by the class include essential CRUD operations that persist file data and files in the protected native storage. It also provides getters and setters that give access to relevant properties:

allow_source_url
bucket
description
file_id
filename
group_ids
key
max_count
name
path
region
source
type

The set_data() method can be used to set several properties at once by providing an array indexed by property keys with related values.

__construct( $file_id = null, $data = array() )

The constructor allows to create a new GFA_File object. It accepts two optional parameters that allow to populate the instance data from existing file data and to set or override properties when creating the instance.

Parameters

$file_id int|null optional file ID to read instance parameters related to an existing file
$data array optional sets instance properties, overrides data from an existing file entry for keys present

Returns

a new GFA_File object

Examples

Create a new file object:

$file = new GFA_File();

Create a new file object and read file info for file ID 1 into the new object:

$file = new GFA_File( 1 );

As above but determine the name and description:

$file = new GFA_File( 1, array( 'name' => 'Example', 'description' => 'This is an example' ) );

Note that in this last example, the name and the description of the object are set after the file data for file ID 1 has been read into the object. This does not persist the properties. To persist the changes to the name and description the update() method would have to be called on the object.

create()

This method persists the file entry record based on the object properties.

To add a file to the protected native storage, the source property must be set and point to a valid uploaded file (via $_FILES) or point to an accessible existing file on the filesystem.

When using the source property to store a file, the filename property should be set to determine the filename to use in the protected native storage. If no filename property is provided, the filename used for the file added to the protected native storage is derived from the source. This is especially important for temporary files that have been uploaded via $_FILES, as the arbitrary temporary filename would be used if no filename is given.

The source property may point to a URL if the allow_source_url property is set to true explicitly, to allow to obtain the file based on the URL provided. This allows to add files to the protected native storage from remote locations. For example, you might use a temporary URL to add sensitive files to the protected native storage.

Parameters

The method does not accept any parameters.

Returns

int|null The method returns the file ID on success, null otherwise

Exceptions

The method throws an Exception if something went wrong while trying to create the persistent file entry.

Examples

The following examples all create file entries that are accessible to registered users, by assigning the group ID 1 in each case. You must change that and indicate the appropriate group ID(s) that limit access to the files to the desired authorized group members only. If you assign the ID of the Registered group, anyone with a user account on your site can access those files, and that is most likely not what you want.

For example, to limit access to members of the Premium group only, you would want to obtain the group ID of the group and use the resulting $group_ids as the value passed to the 'group_ids' parameter used in the examples:

$group = Groups_Group::read_by_name( 'Premium' );
if ( $group ) {
    $group_ids = array( $group->group_id );
}

Uploaded Files

To add a file that was uploaded via $_FILES:

$file = new GFA_File( null, array(
    'source' => $_FILES['file']['tmp_name'],
    'filename' => $_FILES['file']['name'],
    'name' => 'Example PDF File',
    'description' => 'An example PDF file',
    'group_ids' => array( 1 )
);
try {
    $file->create();
} catch ( Exception $e ) {
    // what to do if it went wrong ...
}

Note that instead of providing the filename property as is from $_FILES['file']['name'], you might want to run it through some checks:

require_once GFA_FILE_LIB . '/class-gfa-file-upload.php';
$filename = GFA_File_Upload::filename_filter( $_FILES['file']['name'] );

Files on the Filesystem

To add a file that is accessible on the filesystem:

$file = new GFA_File( null, array(
    'source' => '/var/tmp/protect/example-123456789-abc.pdf',
    'filename' => 'example.pdf',
    'name' => 'Example PDF File',
    'description' => 'An example PDF file',
    'group_ids' => array( 1 )
);
try {
    $file->create();
} catch ( Exception $e ) {
    // what to do if it went wrong ...
}

Remote Files via URL

To add a file that is available via URL:

$file = new GFA_File( null, array(
    'source' => 'https://example.com/example.pdf?auth_token=dab488hdmba092dbasdb3',
    'allow_source_url' => true,
    'filename' => 'example.pdf',
    'name' => 'Example PDF File',
    'description' => 'An example PDF file',
    'group_ids' => array( 1 )
);
try {
    $file->create();
} catch ( Exception $e ) {
    // what to do if it went wrong ...
}

As is evident from these examples, it is very easy to add files to the protected native storage from a variety of sources that cover an ample set of use cases. We can also add files that reside on Amazon S3 in this manner by providing the appropriate properties. Note that if we add files from Amazon S3 as shown below, these are not added to the native protected storage.

Files on Amazon S3

To add a file entry for a file that resides on Amazon S3:

$key = 'Example.jpg';
$region = 'us-east-2';
$bucket = 'mybucket';
$file = new GFA_File( null, array(
    'type' => 'amazon-s3',
    'name' => 'Example Picture',
    'description' => 'An example picture stored on Amazon S3.',
    'filename' => $key,
    'region' => $region,
    'bucket' => $bucket,
    'key' => $key,
    'group_ids' => array( 1 )
);
try {
    $file->create();
} catch ( Exception $e ) {
    // what to do if it went wrong ...
}

Note that the access key and secret key must be set (see File Access) for this operation to succeed. To avoid any confusion, this example does not copy the file from Amazon S3 to the protected native storage. It creates an entry that makes the file on Amazon S3 accessible to authorized members.

read( $file_id )

This method reads stored file data and sets the properties of the object accordingly. Note that this does not read the contents of the stored file.

Parameters

$file_id int the ID of the file to read

Returns

int|null the file ID if successful, otherwise null

update()

This method updates the persistent file data based on the object properties. It can also update the file stored in the protected native storage, if the source property is provided. Also see the notes on the source, filename and allow_source_url properties provided for the create() method. Using the method with those properties, an existing file in protected native storage can be replaced by a new file.

Parameters

This method accepts no parameters.

Returns

int|null This method returns the file ID on success or null otherwise

Exceptions

The method throws an Exception if something went wrong while trying to update the persistent file entry.

Examples

$file = new GFA_File( 1 );
$file->set_name( 'A different name' );
try {
    $file->update();
} catch ( Exception $e ) {
    // something went wrong ... handle it
}

delete()

This method deletes the persistent file entry and the related file from the protected native storage if applicable. The file_id property must be set for the object for this to succeed.

Parameters

The method does not accept any parameters.

Returns

int|null the file ID or null

Examples

$file = new GFA_File( 1 );
$file->delete();

Primary

Navigation

GFA_File

__construct( $file_id = null, $data = array() )

Examples

create()

Examples

Uploaded Files

Files on the Filesystem

Remote Files via URL

Files on Amazon S3

read( $file_id )

update()

Examples

delete()

Examples