César D. Rodas

WP-Storage is a Wordpress plug-in that will allow host files on any other hosting service. By default it had support for YouTube and Amazon S3 support.

This documentation will describe step by step how to create a new WP-Storage plug-in, in other words, add support to other hosting service.

WP-Storage automatically loads drivers, so if you want to create a new driver, simple create a php script in the WP-DRIVERS/WP-Storage/drivers, the file must have the dot php extension. You need to inherit the wp_storage_base class, and create some methods. The skeleton of the driver will look like this:

<?php
class new_plugin extends wp_storage_base
{

    function new_plugin() { }

    function test() { }

    function delete($object_id) { }

    function edit($object_id) { }

    function file_list() { }

    function step_0() { }

    function step_1() { }

    function step_X() { }
}?>

As you can see, just writing few of methods you have a complete driver. Now, I will create a foobar driver, and i will explain it step by step

The class constructor is an important part, because it send information, such as name, configuration variables needed, user fields, file type filters and could be more information in a near future, to the WP-Storage core. The class constructor may be PHP-4 or PHP-5 like, but I recommend PHP-4 like for backward compatibility.

    function foobar()
    {
        /* The Plug-in name */
        parent::wp_storage_base("Foobar Class");

        /* What information the wp-user needs to provide */
        /* to configure the plug-in */
        parent::set_config_variables( array("username","password") );

        /* What information the wp-user needs provide */
        /* in order to use the hosting service */
        parent::add_user_input("description", "File Description","textarea");
        parent::add_user_input("category", "Category","select",true,array("Cat1","Cat2") );

        /* What kind of files the plugin can host */
        /* you can use * for any kind of files */
        parent::set_file_type("jpg,png,gif");
    }

Before the plug-in be active, the user must input configuration settings (i.e username, password and more) and that information must be tested, because it is painful see that you’ve mistype information after you upload 100MB it throws an error, am I right?. For avoid those problems WP-Storage created an API to test configuration, and it must return True or False when it is called.

    function test()
    {
        $u = $_POST['username'];
        $p = $_POST['password'];
        return preform_some_test($u,$p);
    }

Remember, you’ve defined inputs entries in the constructor (parent::set_config_variables), so you can use those $_POST[name], because the WP-Storage configuration page sends the information by post.

The uploading process is handled in by WP-Storage, instead of just hook a Wordpress event, you may be wondering why?, and it is for a simple reason, at the time I start coding WP-Storage I added support for YouTube and Amazon S3, and those support large files, up to 1GB and 5GB respectively, and by default shared hosting (we want everyone uses WP-Storage, everywhere) limits the server file upload to 16MB. So there is a real bottle neck problem, because the drivers support large files but we can send only small files.

For that reason the WP-Storage manage the upload, and it is designed to-do the direct upload to the driver’s server, in other words, directly to YouTube, Amazon S3 or any other.

The upload processing is simple, and because we want to have a generic upload process and very easy to adapt, it is divided into steps. The upload must have from 1 to N steps. Into those steps, you can use a set of ajax rutines that comes within the project. The ajax API is simple but powerful, you can create and clone HTML objects (forms, inputs, etc), and you can write raw javascript code, you’ll understand better on the example, right I’ll focus on explaining the concept behind uploading files directly to the server.

Because we don’t want to send files to server, the WP-Storage upload method is designed to give you a way to create dynamically, and send that form into an special “iframe” called wps_target. If the vendor API permits do “direct” uploads (also known as browse upload), usually you need to compute some few things in the server, then render a html-FORM in the client, for that case it is perfect. Also this way, is useful to plug-in using “dirty” hacking, simulate a real user upload a file (of course it wouldn’t be possible if it has some CAPTCHA system).

Now let’s see an example:

    function step_0()
    {
        # Read the configuration
        $conf = $this->get_config();
        $u= $conf['username'];
        $p= $conf['password'];
        $login = perform_some_login();
        if ( $login===false )
        {
            ajax_exec("document.wp_storage.cancel()");
            ajax_exec("Alert('login fails');");
            return;
        }
        # Create a form, to submit.
        $form = array(
            "tag"=>"form",
            "id" => "wps_form",
            "action"=> get_some_form_url($login) ,
            "method"=>"POST",
            "target" => "wps_target", # We send
            "enctype" => "multipart/form-data"
        );
        # we create an HTML objetc
        $f = & new ohtml( $form );
        # we clone the "wp_storage_file"
        $f->ajax_object_clone("wp_storage_file","file");

        # All the extra-information required is sent by POST
        # to every step, so we catch it, and create html-input
        # objects, in order to submit to plug-in server.
        foreach($this->user_inputs() as $name)
            $f->addObject(  array("type"=>"hidden","name"=>$name, "value"=>$_POST[$name]) );
        # The samething happened with the title
        $f->addObject(  array("type"=>"hidden","name"=>"title", "value"=>$_POST["tjtle"]) );
        # Now the form is created, just send it.
        ajax_submit_form("wps_form");
    }

The WP-Storage will do execute the step_0, which will end when the form is sent and wps_target has been loaded, so it will go ahead to the step_1, if the step_1 doesn’t exist the process is ended.

The WP-Storage has an API to modify and delete object, note that when you edit you can’t change its content its self (the file), only its meta information (title, description, etc).

    function delete($object_id)
    {
        if ( try_to_delete($object_id) )
            ajax_exec("alert('file deleted')");
        else
            ajax_exec("alert('error while deleting file')");
    }

    function get_details($object_id)
    {    //this function show info in the edit form
        return get_media_information($object_id);
    }

    function edit($object_id)
    {
        if ( try_to_edit($object_id,$_POST) )
            ajax_exec("alert('file edited')");
        else
            ajax_exec("alert('error while editing file')");
    }

If the vendor doesn’t support the edit or deletion, simple don’t define one or both functions and WP-Storage will understand it.