LibertyMime

The next generation of file management

Created by: Will, Last modification: 29 Aug 2008 (20:47 UTC) by xing

LibertyMime? LibertyAttachabe? What the heck?

LibertyMime is the evolution of file management in bitweaver. Introduced in R2.1.0, LibertyMime replaces LibertyAttachable (also known as LibertyAttachments). LibertyMime is the base class for managing file attachments, and basically behaves like LibertyAttachable, but with far more flexible and robust features for file types.

Where LibertyMime departs from LibertyAttachable is in its handling of files; as its name suggests LibertyMime keys on mime type, where as LibertyAttachable handled files generically. LibertyMime's key feature is that is has a plugin system that lets each mime type be handled uniquely. Via the plugin system, each mime type has its own storage routine, loading routine, preferences and meta data, and methods of being displayed.

We love Mimes, who would a' thunk?

Because LibertyMime lets us tailor file management to the mime, we can do elegant things like, with audio extract, store and even update meta data from various audio file formats including mp3, m4a or flac. For flash files we can set display size preferences for different kinds of display, like lists or full page. PDFs can be displayed as downloads, and images as slideshows. If you are using a quality digital camera the image plugin can extract store and display meta data the camera embeds in the photo.

LibertyMime Plugins

LibertyMime plugins reside in liberty/plugins/ with the mime. prefix. you can activate selected plugins by visiting your liberty plugins administration screen. in the mime tab, you'll find said plugins. Please be sure to read the notes on the plugin administration screen (if there is one - depicted by icon). Some plugins require server-side software to be installed.

With version 2.1 of bitweaver you can place your own plugins in your own package:

<?php
<package>/liberty_plugins/
?>
These plugins will be picked up by liberty and you can activate them in your liberty plugins administration screen as you would any other plugin. This way you can easily add your own plugins without messing with files in the core packages of bitweaver.

Create a Custom Plugin

Let's set up a custom plugin that uses all the features of the default plugin but does some extra stuff. This custom plugin will extract EXIF data from uploaded image files (taken from liberty/plugins/mime.image.php).

Initiate the plugin and define the basics. Most of this should be self explanatory and inline comments explain things that might not be clear.

Plugin setup


<?php
/**
 * setup
 */
global $gLibertySystem;

/**
 *  This is the name of the plugin - max char length is 16
 * As a naming convention, the liberty mime handler definition should start with:
 * PLUGIN_MIME_GUID_
 */
define'PLUGIN_MIME_GUID_IMAGE''mimeimage' );

$pluginParams = array (
    
// Set of functions and what they are called in this paricular plugin
    // Use the GUID as your namespace
    // in some of these function calls, we directly call the default functions if there's nothing special for us to do
    
'verify_function'     => 'mime_default_verify',
    
'store_function'      => 'mime_image_store',
    
'update_function'     => 'mime_image_update',
    
'load_function'       => 'mime_image_load',
    
'download_function'   => 'mime_default_download',
    
'expunge_function'    => 'mime_default_expunge',

    
// Brief description of what the plugin does
    
'title'               => 'Extract image meta data',
    
'description'         => 'Extract image meta data and display relevant information to the user.',

    
// Templates to display the files
    //'view_tpl'            => 'bitpackage:liberty/mime_image_view_inc.tpl',
    //'inline_tpl'          => 'bitpackage:liberty/mime_image_inline_inc.tpl',
    //'edit_tpl'            => 'bitpackage:liberty/mime_image_edit_inc.tpl',

    // URL to page with options for this plugin
    //'plugin_settings_url' => LIBERTY_PKG_URL.'admin/mime_image.php',

    // This should be the same for all mime plugins
    
'plugin_type'         => MIME_PLUGIN,

    
// Set this to TRUE if you want the plugin active right after installation
    
'auto_activate'       => FALSE,

    
// Help page on bitweaver.org
    //'help_page'           => 'LibertyMime+Image+Plugin',

    // here we can enter an array of perl regular expression patters that will
    // be used to find out what plugin will be used on upload. this should pick
    // up all images
    
'mimetypes'           => array(
        
'#image/.*#i',
    ),
);
$gLibertySystem->registerPluginPLUGIN_MIME_GUID_IMAGE$pluginParams );

// depending on the scan the default file might not be included yet. we need to get it manually - simply use the relative path
require_once( 'mime.default.php' );
?>


Here we get to the actual file handling. The function names should be an indication of when particular functions are called. Inline comments should explain what roughly is going on.

File processing functions


<?php
/**
 * Store the data in the database
 *
 * @param array $pStoreRow File data needed to store details in the database - sanitised and generated in the verify function
 * @access public
 * @return TRUE on success, FALSE on failure - $pStoreRow['errors'] will contain reason
 */
function mime_image_store( &$pStoreRow ) {
    
// this will set the correct pluign guid, even if we let default handle the store process
    
$pStoreRow['attachment_plugin_guid'] = PLUGIN_MIME_GUID_IMAGE;
    
$pStoreRow['log'] = array();

    
// if storing works, we process the image
    
if( $ret mime_default_store$pStoreRow )) {
        if( !
mime_image_store_exif_data$pStoreRow )) {
            
// if it all goes tits up, we'll know why
            
$pStoreRow['errors'] = $pStoreRow['log'];
            
$ret FALSE;
        }
    }
    return 
$ret;
}

/**
 * mime_image_update update file information in the database if there were changes.
 *
 * @param array $pStoreRow File data
 * @param array $pParams This is additional data passed back from the update form
 * @access public
 * @return TRUE on success, FALSE on failure - $pStoreHash[errors] will contain reason for failure
 */
function mime_image_update( &$pStoreRow$pParams NULL ) {
    
$ret FALSE;

    
// this will set the correct pluign guid, even if we let default handle the store process
    
$pStoreRow['attachment_plugin_guid'] = PLUGIN_MIME_GUID_IMAGE;

    
// if storing works, we process the image
    
if( !empty( $pStoreRow['upload'] ) && $ret mime_default_update$pStoreRow )) {
        if( !
mime_image_store_exif_data$pStoreRow )) {
            
// if it all goes tits up, we'll know why
            
$pStoreRow['errors'] = $pStoreRow['log'];
            
$ret FALSE;
        }
    }
    return 
$ret;
}

/**
 * Load file data from the database
 *
 * @param array $pFileHash Contains all file information
 * @param array $pPrefs Attachment preferences taken liberty_attachment_prefs
 * @param array $pParams Parameters for loading the plugin - e.g.: might contain values such as thumbnail size from the view page
 * @access public
 * @return TRUE on success, FALSE on failure - $pStoreHash[errors] will contain reason for failure
 */
function mime_image_load( &$pFileHash, &$pPrefs$pParams NULL ) {
    global 
$gLibertySystem$gBitThemes;

    
// don't load a mime image if we don't have an image for this file
    
if( $ret mime_default_load$pFileHash$pPrefs$pParams )) {
        
// fetch meta data from the db
        
$ret['meta'] = LibertyMime::getMetaData$pFileHash['attachment_id'], "EXIF" );
    }
    return 
$ret;
}

/**
 * mime_image_store_exif_data Process a JPEG and store its EXIF data as meta data.
 *
 * @param array $pFileHash file details.
 * @param array $pFileHash[upload] should contain a complete hash from $_FILES
 * @access public
 * @return TRUE on success, FALSE on failure
 */
function mime_image_store_exif_data$pFileHash ) {
    if( !empty( 
$pFileHash['upload'] )) {
        
$upload = &$pFileHash['upload'];
    }

    if( @
BitBase::verifyId$pFileHash['attachment_id'] ) && function_exists'exif_read_data' ) && !empty( $upload['source_file'] ) && is_file$upload['source_file'] ) && preg_match"#/(jpeg|tiff)#i"$upload['type'] )) {
        
$exifHash exif_read_data$upload['source_file'], 0TRUE );
        
LibertyMime::storeMetaData$pFileHash['attachment_id'], 'EXIF'$exifHash['EXIF'] );
    }

    return 
TRUE;
}
?>

Related Items

Packages » Required Packages

Packages that are required for bitweaver to work.

  •    •    •    •    •    •    •    •    •    •    •    •  Anonymous  •  

Documentation » Technical Documentation

Documentation geared towards developers and people who want to learn about the core processes of bitweaver

  •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •  

Online Help

These pages are linked from within bitweaver's administration

  •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •    •  Anonymous  •  Anonymous  •  Anonymous  •  Array  •  Array