/**
  * Get framework/project/application file
  *
  * @param Charcoal_String $virtual_path          virtual path including macro key like '%BASE_DIR%', '%WEBAPP_DIR%', etc.
  * @param Charcoal_Object $value                 cache data to save
  *
  * @return Charcoal_File        file object
  *
  * [macro keyword sample]
  *
  *      macro keyword        |                return value(real path)
  * ---------------------|------------------------------------------------
  *   %APPLICATION_DIR%    | (web_app_root)/webapp/(project_name)/app/(application name)/
  *   %PROJECT_DIR%        | (web_app_root)/webapp/(project_name)/
  *   %WEBAPP_DIR%        | (web_app_root)/webapp/
  *
  *
  * @see Charcoal_ResourceLocator
  *
  */
 public function getFile($virtual_path, $filename = NULL)
 {
     //        Charcoal_ParamTrait::validateString( 1, $virtual_path );
     //        Charcoal_ParamTrait::validateString( 2, $filename, TRUE );
     return Charcoal_ResourceLocator::getFile($this->getSandbox()->getEnvironment(), $virtual_path, $filename);
 }
 /**
  * create file
  *
  * @param string|Charcoal_String $contents
  * @param Charcoal_File $dir
  * @param string|Charcoal_String $file_name
  *
  * @return Charcoal_File
  */
 public function create($contents, $dir = null, $file_name = null)
 {
     if ($file_name === null) {
         $tmp_filename = Charcoal_System::hash() . '.tmp';
     }
     if ($dir === null) {
         $dir = Charcoal_ResourceLocator::getFile($this->getSandbox()->getEnvironment(), "%TMP_DIR%");
     }
     $tmp_file = new Charcoal_File($file_name, $dir);
     if ($tmp_file->isDirectory()) {
         _throw(new Charcoal_FileSystemComponentException('specified path is directory.'));
     }
     if ($tmp_file->exists()) {
         _throw(new Charcoal_FileSystemComponentException('specified file is already exists.'));
     }
     if ($this->overwrite) {
         if ($tmp_file->exists() && !$tmp_file->canWrite()) {
             _throw(new Charcoal_FileSystemComponentException('specified file is not writeable.'));
         }
     }
     try {
         // create file
         $tmp_file->makeFile($this->mode, $contents, TRUE);
         $this->file = $tmp_file;
         return $tmp_file;
     } catch (Exception $e) {
         _catch($e);
         _throw(new Charcoal_TempFileComponentException(s('creating file failed.'), $e));
     }
     return null;
 }