root/plugins/sfPropelFileStoragePlugin/README

= sfPropelFileStorage plugin =

The `sfPropelFileStoragePlugin` provides functionality for storing files in a database using Symfony.  The plugin also caches files as they are retrieved from the database if they are not already cached.

== Installation ==

  * Copy the files into the plugin directory
  
  * Rebuild your model

  {{{
    symfony propel-build-all
  }}}

  * Activate one or more modules in your `settings.yml` 
    * For your backend application: sfPropelFileStorageAdmin (optional)
    * For your frontend application: sfPropelFileStorage (required for applications that will serve files)

  {{{
    all:
      .settings:
        enabled_modules: [default, sfPropelFileStorageAdmin, sfPropelFileStorage]
  }}}

  * Clear your cache
  
  {{{
    symfony cc
  }}}

  * Update your routing configuration

  {{{
    # sfPropelFileStorage frontend routing
    download_by_file_name:
      url:  /download/:name
      param: { module: sfPropelFileStorage, action: download }

    download_image_by_file_name:
      url:  /images/:name
      param: { module: sfPropelFileStorage, action: download }
  }}}

  * Update your .htaccess file, commenting out or eliminating the first three lines and adding a new rule to check if the URL points to a real file or not.

  {{{
    # we skip all files with .something
    # RewriteCond %{REQUEST_URI} \..+$
    # RewriteCond %{REQUEST_URI} !\.html$
    # RewriteRule .* - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
  }}}

  * optionally override the default file chunk size of 65k in app.yml.

  {{{
    all:
      file_data_chunk_size: 130370
  }}}

  * For IIS with ISAPIRewrite you'll need to add some rules, such as:

  {{{
    RewriteRule /(images|download)(.*) /index.php/$1$2 [L]
  }}}
  
  * Choose optional user manager system to use with sfPropelFileStorage plugin (defaults to none)
   
    * Execute the pake task file-storage-set-user-manager [sfGuard, none]
  
    {{{
      symfony file-storage-set-user-manager <manager_option>
    }}}
    
    * Rebuild your models
   
    {{{
      symfony propel-build-model
    }}}
    
    * Clear cache

== Server Configuration ==
This plugin is limited by upload_max_filesize (and potentially post_max_size and max_input_time as well). For post_max_size and max_input_time you'll need to modify your php.ini file explicitly. However, for max_upload_size, you can override the default settings in your app.yml file, e.g.:

{{{
all:
  sf_propel_file_storage_upload_max_filesize: 2M
}}}

Note that you can use either a number of bytes or the shorthand notation described here: http://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes

There is a validator file provided with the admin module of this plugin that illustrates how to validate filesize. If no validation occurs and the file couldn't be sent, an exception is thrown, so if you're using this in your own module and NOT using validation, you should at least enclose your call to
{{{
sfPropelFileStorageUtil::generateFileInfoFromRequest()
}}}

in a try/catch block.

If you do not specify a value for sf_propel_file_storage_upload_max_filesize, the value from php.ini will be used. Please note that sf_propel_file_storage_upload_max_filesize ''only'' applies to saving files with this plugin and no were else.

== A Usage Example: Integrating sfPropelFileStorage with Existing Modules ==
  
  The sfPropelFileStoragePlugin is desingned to easily cooperate with other modules.  A basic administration module is provided as part of the plugin.  However, use of this module is optional.  Follow the steps below to allow other modules in your application to accept files into the sfPropelFileStorage tables.
  
  * Add one or more foreign keys in the schema of the object to which you are attaching files.
  * Modify your templates as appropriate.
  * In your Update command, generate an sfPropelFileStorageInfo object and attach it to it's parent object.  Saving the parent object will save the file_info and file_data in one transaction.

  {{{
    $fileInfo = sfPropelFileStorageUtil::generateFileInfoFromRequest($this->getRequest(), 'uploaded_file');
    $object->setsfPropelFileStorageInfo($fileInfo);
    $object->save();
  }}}

== Customize sfPropelFileStorage module actions ==

To customize or add methods to the sfPropelFileStorage actions class:

* Create a module in your application named sfPropelFileStorage.

* Create an actions.class.php file in that modules Actions directory:
  
  {{{
    <?php
      require_once sfConfig::get('sf_plugins_dir').'/sfPropelFileStoragePlugin/modules/sfPropelFileStorage/lib/BasesfPropelFileStorageActions.class.php';
      class sfPropelFileStorageActions extends BasesfPropelFileStorageActions
      {
        // add or override methods.
      }
    ?>
  }}}