File Attributes & Inspectors

Custom File Type Inspectors in Concrete CMS

Concrete CMS uses attributes extensively. For files, custom file type inspectors can automatically set attributes based on the file's content, bypassing manual admin input. This is especially useful for files that inherently contain useful metadata.

Understanding File Type Inspectors

A File Type Inspector in Concrete CMS is custom code triggered when a specific file type is uploaded or rescanned in the Dashboard File Manager. It can manipulate attributes and execute various actions. Concrete includes a couple of inspectors by default, like for images and FLV files. An example is the Image inspector (ImageInspector.php) that extracts and sets image dimensions as attributes.

namespace Concrete\Core\File\Type\Inspector;
use Concrete\Core\File\Version;
use Image;
use FileAttributeKey;
use Core;

class ImageInspector extends Inspector {

    public function inspect(Version $fv) {

        $fr = $fv->getFileResource();
        $image = Image::load($fr->read());
        $data = $image->getSize();

        $at1 = FileAttributeKey::getByHandle('width');
        $at2 = FileAttributeKey::getByHandle('height');
        $fv->setAttribute($at1, $data->getWidth());
        $fv->setAttribute($at2, $data->getHeight());
    }
}

Creating a Custom File Type Inspector

Building a custom inspector is straightforward. For instance, to read ID3 tags from MP3 files and store them as attributes, you can create a package named "id3_reader".

1. Create Required Attributes: Make attributes for data you want to store, like "audio_artist" and "audio_title".

   

2. Initialize the Package: Name your package (e.g., "id3_reader") and set it up in the packages directory.

3. Integrate ID3 Reader Library: Use PHP-ID3 and Composer for managing dependencies.

   

4. Develop Package Controller: Create a standard package controller.

namespace Concrete\Package\Id3Reader;

defined('C5_EXECUTE') or die(_("Access Denied."));

use \Concrete\Core\Package\Package;

class Controller extends Package
{
    protected $pkgHandle = 'id3_reader';
    protected $appVersionRequired = '5.7.5RC1';
    protected $pkgVersion = '1.0';

    public function getPackageDescription()
    {
        return t('Adds the ability to store ID3 Data in File Attributes.');
    }

    public function getPackageName()
    {
        return t('ID3 Reader');
    }
}

5. Register Custom Inspector: Add an on_start method to your package for the custom inspector setup.

6. Implement the Custom Inspector Class: Create AudioInspector.php in the appropriate directory with the necessary logic to read and set attributes from ID3 tags.

namespace Concrete\Package\Id3Reader\File\Type\Inspector;

use Concrete\Core\Attribute\Key\FileKey;
use Concrete\Core\File\Type\Inspector\Inspector;
use Concrete\Core\File\Version;
use PhpId3\Id3TagsReader;

class AudioInspector extends Inspector
{
    public function inspect(Version $fv)
    {
        $fr = $fv->getFileResource();
        $fs = $fv->getFile()->getFileStorageLocationObject()->getFileSystemObject();
        $stream = $fs->readStream($fr->getPath());

        $id3 = new Id3TagsReader($stream);
        $id3->readAllTags();

        $artist = FileKey::getByHandle('audio_artist');
        $title = FileKey::getByHandle('audio_title');
        $data = $id3->getId3Array();
        if (isset($data['TIT2']) && is_array($data['TIT2'])) {
            $fv->setAttribute($title, $data['TIT2']['body']);
        }
        if (isset($data['TPE1']) && is_array($data['TPE1'])) {
            $fv->setAttribute($artist, $data['TPE1']['body']);
        }
    }
}

This custom inspector enables automatic extraction and storage of ID3 metadata from MP3 files upon upload or rescan, enhancing data management efficiency in Concrete CMS.