Overview
While the File Manager provides a nice, powerful interface for working with files graphically, there are times when developers will want to set attributes on files, update their names, modify where they are stored and more. This can all be done easily through the Concrete CMS API.
Setting Attributes on an Existing File
Let's say we've created a file attribute of the checkbox type with the "is_featured" handle. Setting this on a particular File object is easy.
$file = \File::getByID(3);
$file->setAttribute('is_featured', true);
That's it! More complex attribute types may take more complex values in the second argument. For example, if you have a select attribute with the handle "selected_color" for a particular file and you want to set it programmatically, the Select attribute type expects its value to be an array of values that match the available options stored in the particular attribute. If we have a select attribute for colors that contains "Red," "Yellow," and "Green", selecting Red and Green for a particular file can be done like this:
$file = \File::getByID(3);
$values = array('Red', 'Green');
$page->setAttribute('selected_color', $values);
Updating a File's Name or Description
The File Version class contains a numbmer of helpful, easy-to-use API methods to modify that version's properties. Whenever working with this class, make sure to start by calling getVersionToModify() on the relevant File object. This will return a new Version of the File object (if necessary), so that you can rollback to a previous version if necessary.
$file = \File::getByID(3);
$version = $file->getVersionToModify();
$version->updateTitle('New Title');
$version->updateDescription('New Description');
Setting a new Storage Location
Concrete version 7 introduces a new object for storage locations. Storage locations can be defined in the Dashboard. Most of the time a storage location will be a particular directory on your web server (in or out of the web root) – but additional storage locations like Amazon S3 or Dropbox are also possible. Let's say we have a file in the default storage location, and we want to move it to Amazon S3. Our Amazon S3 storage location has the ID of 2.
$amazon = \Concrete\Core\File\StorageLocation\StorageLocation::getByID(2); // This is the ID of Amazon S3
$file = \File::getByID(3);
$file->setFileStorageLocation($amazon);
We can alternately retrieve the storage location by its name.
$app = \Concrete\Core\Support\Facade\Application::getFacadeApplication();
$amazon = $app[FileStorageLocationFactory::class]->fetchByName('Amazon S3')[0];
Setting a password on a File
$file = \File::getByID(3);
$file->setPassword('supers3cret');
Add a File to a File Set
$file = \File::getByID(3);
$fs = \Concrete\Core\File\Set\Set::createAndGetSet('Name of a File Set', \Concrete\Core\File\Set\Set::TYPE_PUBLIC, 1);
$fs->addFileToSet($file);
Retrieve File Sets a particular File is in
$file = \File::getByID(3);
$file->getFileSets();
This returns an array of \Concrete\Core\File\Set\Set objects.
Deleting a File Version
$file = \File::getByID(3);
$version = $file->getVersion(1); // Gets the first version – make sure this isn't approved!
$version->delete();
Deleting a File
$file = \File::getByID(3);
$file->delete();
API
These are just a few examples of what can be done with the Concrete File API. Get more from the Page API docs: