1: <?php
  2: namespace Dropbox;
  3: 
  4: /**
  5:  * Describes how a file should be saved when it is written to Dropbox.
  6:  */
  7: final class WriteMode
  8: {
  9:     /**
 10:      * The URL parameters to pass to the file uploading endpoint to achieve the
 11:      * desired write mode.
 12:      *
 13:      * @var array
 14:      */
 15:     private $extraParams;
 16: 
 17:     /**
 18:      * @internal
 19:      */
 20:     private function __construct($extraParams)
 21:     {
 22:         $this->extraParams = $extraParams;
 23:     }
 24: 
 25:     /**
 26:      * @internal
 27:      */
 28:     function getExtraParams()
 29:     {
 30:         return $this->extraParams;
 31:     }
 32: 
 33:     /**
 34:      * Returns a {@link WriteMode} for adding a new file.  If a file at the specified path already
 35:      * exists, the new file will be renamed automatically.
 36:      *
 37:      * For example, if you're trying to upload a file to "/Notes/Groceries.txt", but there's
 38:      * already a file there, your file will be written to "/Notes/Groceries (1).txt".
 39:      *
 40:      * You can determine whether your file was renamed by checking the "path" field of the
 41:      * metadata object returned by the API call.
 42:      *
 43:      * @return WriteMode
 44:      */
 45:     static function add()
 46:     {
 47:         if (self::$addInstance === null) {
 48:             self::$addInstance = new WriteMode(array("overwrite" => "false"));
 49:         }
 50:         return self::$addInstance;
 51:     }
 52:     private static $addInstance = null;
 53: 
 54:     /**
 55:      * Returns a {@link WriteMode} for forcing a file to be at a certain path.  If there's already
 56:      * a file at that path, the existing file will be overwritten.  If there's a folder at that
 57:      * path, however, it will not be overwritten and the API call will fail.
 58:      *
 59:      * @return WriteMode
 60:      */
 61:     static function force()
 62:     {
 63:         if (self::$forceInstance === null) {
 64:             self::$forceInstance = new WriteMode(array("overwrite" => "true"));
 65:         }
 66:         return self::$forceInstance;
 67:     }
 68:     private static $forceInstance = null;
 69: 
 70:     /**
 71:      * Returns a {@link WriteMode} for updating an existing file.  This is useful for when you
 72:      * have downloaded a file, made modifications, and want to save your modifications back to
 73:      * Dropbox.  You need to specify the revision of the copy of the file you downloaded (it's
 74:      * the "rev" parameter of the file's metadata object).
 75:      *
 76:      * If, when you attempt to save, the revision of the file currently on Dropbox matches
 77:      * $revToReplace, the file on Dropbox will be overwritten with the new contents you provide.
 78:      *
 79:      * If the revision of the file currently on Dropbox doesn't match $revToReplace, Dropbox will
 80:      * create a new file and save your contents to that file.  For example, if the original file
 81:      * path is "/Notes/Groceries.txt", the new file's path might be
 82:      * "/Notes/Groceries (conflicted copy).txt".
 83:      *
 84:      * You can determine whether your file was renamed by checking the "path" field of the
 85:      * metadata object returned by the API call.
 86:      *
 87:      * @param string $revToReplace
 88:      * @return WriteMode
 89:      */
 90:     static function update($revToReplace)
 91:     {
 92:         return new WriteMode(array("parent_rev" => $revToReplace));
 93:     }
 94: 
 95:     /**
 96:      * Check that a function argument is of type <code>WriteMode</code>.
 97:      *
 98:      * @internal
 99:      */
100:     static function checkArg($argName, $argValue)
101:     {
102:         if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
103:     }
104: 
105:     /**
106:      * Check that a function argument is either <code>null</code> or of type
107:      * <code>WriteMode</code>.
108:      *
109:      * @internal
110:      */
111:     static function checkArgOrNull($argName, $argValue)
112:     {
113:         if ($argValue === null) return;
114:         if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
115:     }
116: }
117: