1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94: 95: 96: 97: 98: 99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 279: 280: 281: 282: 283: 284: 285: 286: 287: 288: 289: 290: 291: 292: 293: 294: 295: 296: 297: 298: 299: 300: 301: 302: 303: 304: 305: 306: 307: 308: 309: 310: 311: 312: 313: 314: 315: 316: 317: 318: 319: 320: 321: 322: 323: 324: 325: 326: 327: 328: 329: 330: 331: 332: 333: 334: 335: 336: 337: 338: 339: 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: 350: 351: 352: 353: 354: 355: 356: 357: 358: 359: 360: 361: 362: 363: 364: 365: 366: 367: 368: 369: 370: 371: 372: 373: 374: 375: 376: 377: 378: 379: 380: 381: 382: 383: 384: 385: 386: 387: 388: 389: 390: 391: 392: 393: 394: 395: 396: 397: 398: 399: 400: 401: 402: 403: 404: 405: 406: 407: 408: 409: 410: 411: 412: 413: 414: 415: 416: 417: 418: 419: 420: 421: 422: 423: 424: 425: 426: 427: 428: 429: 430: 431: 432: 433: 434: 435: 436: 437: 438: 439: 440: 441: 442: 443: 444: 445: 446: 447: 448: 449: 450: 451: 452: 453: 454: 455: 456: 457: 458: 459: 460: 461: 462: 463: 464: 465: 466: 467: 468: 469: 470: 471: 472: 473: 474: 475: 476: 477: 478: 479: 480: 481: 482: 483: 484: 485: 486: 487: 488: 489: 490: 491: 492: 493: 494: 495: 496: 497: 498: 499: 500: 501: 502: 503: 504: 505: 506: 507: 508: 509: 510: 511: 512: 513: 514: 515: 516: 517: 518: 519: 520: 521: 522: 523: 524: 525: 526: 527: 528: 529: 530: 531: 532: 533: 534: 535: 536: 537: 538: 539: 540: 541: 542: 543: 544: 545: 546: 547: 548: 549: 550: 551: 552: 553: 554: 555: 556: 557: 558: 559: 560: 561: 562: 563: 564: 565: 566: 567: 568: 569: 570: 571: 572: 573: 574: 575: 576: 577: 578: 579: 580: 581: 582: 583: 584: 585: 586: 587: 588: 589: 590: 591: 592: 593: 594: 595: 596: 597: 598: 599: 600: 601: 602: 603: 604: 605: 606: 607: 608: 609: 610: 611: 612: 613: 614: 615: 616: 617: 618: 619: 620: 621: 622: 623: 624: 625: 626: 627: 628: 629: 630: 631: 632: 633: 634: 635: 636: 637: 638: 639: 640: 641: 642: 643: 644: 645: 646: 647: 648: 649: 650: 651: 652: 653: 654: 655: 656: 657: 658: 659: 660: 661: 662: 663: 664: 665: 666: 667: 668: 669: 670: 671: 672: 673: 674: 675: 676: 677: 678: 679: 680: 681: 682: 683: 684: 685: 686: 687: 688: 689: 690: 691: 692: 693: 694: 695: 696: 697: 698: 699: 700: 701: 702: 703: 704: 705: 706: 707: 708: 709: 710: 711: 712: 713: 714: 715: 716: 717: 718: 719: 720: 721: 722: 723: 724: 725: 726: 727: 728: 729: 730: 731: 732: 733: 734: 735: 736: 737: 738: 739: 740: 741: 742: 743: 744: 745: 746: 747: 748: 749: 750: 751: 752: 753: 754: 755: 756: 757: 758: 759: 760: 761: 762: 763: 764: 765: 766: 767: 768: 769: 770: 771: 772: 773: 774: 775: 776: 777: 778: 779: 780: 781: 782: 783: 784: 785: 786: 787: 788: 789: 790: 791: 792: 793: 794: 795: 796: 797: 798: 799: 800: 801: 802: 803: 804: 805: 806: 807: 808: 809: 810: 811: 812: 813: 814: 815: 816: 817: 818: 819: 820: 821: 822: 823: 824: 825: 826: 827: 828: 829: 830: 831: 832: 833: 834: 835: 836: 837: 838: 839: 840: 841: 842: 843: 844: 845: 846: 847: 848: 849: 850: 851: 852: 853: 854: 855: 856: 857: 858: 859: 860: 861: 862: 863: 864: 865: 866: 867: 868: 869: 870: 871: 872: 873: 874: 875: 876: 877: 878: 879: 880: 881: 882: 883: 884: 885: 886: 887: 888: 889: 890: 891: 892: 893: 894: 895: 896: 897: 898: 899: 900: 901: 902: 903: 904: 905: 906: 907: 908: 909: 910: 911: 912: 913: 914: 915: 916: 917: 918: 919: 920: 921: 922: 923: 924: 925: 926: 927: 928: 929: 930: 931: 932: 933: 934: 935: 936: 937: 938: 939: 940: 941: 942: 943: 944: 945: 946: 947: 948: 949: 950: 951: 952: 953: 954: 955: 956: 957: 958: 959: 960: 961: 962: 963: 964: 965: 966: 967: 968: 969: 970: 971: 972: 973: 974: 975: 976: 977: 978: 979: 980: 981: 982: 983: 984: 985: 986: 987: 988: 989: 990: 991: 992: 993: 994: 995: 996: 997: 998: 999: 1000: 1001: 1002: 1003: 1004: 1005: 1006: 1007: 1008: 1009: 1010: 1011: 1012: 1013: 1014: 1015: 1016: 1017: 1018: 1019: 1020: 1021: 1022: 1023: 1024: 1025: 1026: 1027: 1028: 1029: 1030: 1031: 1032: 1033: 1034: 1035: 1036: 1037: 1038: 1039: 1040: 1041: 1042: 1043: 1044: 1045: 1046: 1047: 1048: 1049: 1050: 1051: 1052: 1053: 1054: 1055: 1056: 1057: 1058: 1059: 1060: 1061: 1062: 1063: 1064: 1065: 1066: 1067: 1068: 1069: 1070: 1071: 1072: 1073: 1074: 1075: 1076: 1077: 1078: 1079: 1080: 1081: 1082: 1083: 1084: 1085: 1086: 1087: 1088: 1089: 1090: 1091: 1092: 1093: 1094: 1095: 1096: 1097: 1098: 1099: 1100: 1101: 1102: 1103: 1104: 1105: 1106: 1107: 1108: 1109: 1110: 1111: 1112: 1113: 1114: 1115: 1116: 1117: 1118: 1119: 1120: 1121: 1122: 1123: 1124: 1125: 1126: 1127: 1128: 1129: 1130: 1131: 1132: 1133: 1134: 1135: 1136: 1137: 1138: 1139: 1140: 1141: 1142: 1143: 1144: 1145: 1146: 1147: 1148: 1149: 1150: 1151: 1152: 1153: 1154: 1155: 1156: 1157: 1158: 1159: 1160: 1161: 1162: 1163: 1164: 1165: 1166: 1167: 1168: 1169: 1170: 1171: 1172: 1173: 1174: 1175: 1176: 1177: 1178: 1179: 1180: 1181: 1182: 1183: 1184: 1185: 1186: 1187: 1188: 1189: 1190: 1191: 1192: 1193: 1194: 1195: 1196: 1197: 1198: 1199: 1200: 1201: 1202: 1203: 1204: 1205: 1206: 1207: 1208: 1209: 1210: 1211: 1212: 1213: 1214: 1215: 1216: 1217: 1218: 1219: 1220: 1221: 1222: 1223: 1224: 1225: 1226: 1227: 1228: 1229: 1230: 1231: 1232: 1233: 1234: 1235: 1236: 1237: 1238: 1239: 1240: 1241: 1242: 1243: 1244: 1245: 1246: 1247: 1248: 1249: 1250: 1251: 1252: 1253: 1254: 1255: 1256: 1257: 1258: 1259: 1260: 1261: 1262: 1263: 1264: 1265: 1266: 1267: 1268: 1269: 1270: 1271: 1272: 1273: 1274: 1275: 1276: 1277: 1278: 1279: 1280: 1281: 1282: 1283: 1284: 1285: 1286: 1287: 1288: 1289: 1290: 1291: 1292: 1293: 1294: 1295: 1296: 1297: 1298: 1299: 1300: 1301: 1302: 1303: 1304: 1305: 1306: 1307: 1308: 1309: 1310: 1311: 1312: 1313: 1314: 1315: 1316: 1317: 1318: 1319: 1320: 1321: 1322: 1323: 1324: 1325: 1326: 1327: 1328: 1329: 1330: 1331: 1332: 1333: 1334: 1335: 1336: 1337: 1338: 1339: 1340: 1341: 1342: 1343: 1344: 1345: 1346: 1347: 1348: 1349: 1350: 1351: 1352: 1353: 1354: 1355: 1356: 1357: 1358: 1359: 1360: 1361: 1362: 1363: 1364: 1365: 1366: 1367: 1368: 1369: 1370: 1371: 1372: 1373: 1374: 1375: 1376: 1377: 1378: 1379: 1380: 1381: 1382: 1383: 1384: 1385: 1386: 1387: 1388: 1389: 1390: 1391: 1392: 1393: 1394: 1395: 1396: 1397: 1398: 1399: 1400: 1401: 1402: 1403: 1404: 1405: 1406: 1407: 1408: 1409: 1410: 1411: 1412: 1413: 1414: 1415: 1416: 1417: 1418: 1419: 1420: 1421: 1422: 1423: 1424: 1425: 1426: 1427: 1428: 1429: 1430: 1431: 1432: 1433: 1434: 1435: 1436: 1437: 1438: 1439: 1440: 1441: 1442: 1443: 1444: 1445: 1446: 1447: 1448: 1449: 1450: 1451: 1452: 1453: 1454: 1455: 1456: 1457: 1458: 1459: 1460: 1461: 1462: 1463: 1464: 1465: 1466: 1467: 1468: 1469: 1470: 1471: 1472: 1473: 1474: 1475: 1476: 1477: 1478: 1479: 1480: 1481: 1482: 1483: 1484: 1485: 1486: 1487: 1488: 1489: 1490: 1491: 1492: 1493: 1494: 1495: 1496: <?php
namespace Dropbox;
/**
* The class used to make most Dropbox API calls. You can use this once you've gotten an
* {@link AccessToken} via {@link WebAuth}.
*
* This class is stateless so it can be shared/reused.
*/
class Client
{
/**
* The access token used by this client to make authenticated API calls. You can get an
* access token via {@link WebAuth}.
*
* @return AccessToken
*/
function getAccessToken() { return $this->accessToken; }
/** @var AccessToken */
private $accessToken;
/**
* An identifier for the API client, typically of the form "Name/Version".
* This is used to set the HTTP `User-Agent` header when making API requests.
* Example: `"PhotoEditServer/1.3"`
*
* If you're the author a higher-level library on top of the basic SDK, and the
* "Photo Edit" app's server code is using your library to access Dropbox, you should append
* your library's name and version to form the full identifier. For example,
* if your library is called "File Picker", you might set this field to:
* `"PhotoEditServer/1.3 FilePicker/0.1-beta"`
*
* The exact format of the `User-Agent` header is described in
* <a href="http://tools.ietf.org/html/rfc2616#section-3.8">section 3.8 of the HTTP specification</a>.
*
* Note that underlying HTTP client may append other things to the `User-Agent`, such as
* the name of the library being used to actually make the HTTP request (such as cURL).
*
* @return string
*/
function getClientIdentifier() { return $this->clientIdentifier; }
/** @var string */
private $clientIdentifier;
/**
* The locale of the user of your application. Some API calls return localized
* data and error messages; this "user locale" setting determines which locale
* the server should use to localize those strings.
*
* @return null|string
*/
function getUserLocale() { return $this->userLocale; }
/** @var null|string */
private $userLocale;
/**
* The {@link Host} object that determines the hostnames we make requests to.
*
* @return Host
*/
function getHost() { return $this->host; }
/**
* Constructor.
*
* @param string $accessToken
* See {@link getAccessToken()}
* @param string $clientIdentifier
* See {@link getClientIdentifier()}
* @param null|string $userLocale
* See {@link getUserLocale()}
*/
function __construct($accessToken, $clientIdentifier, $userLocale = null)
{
self::checkAccessTokenArg("accessToken", $accessToken);
self::checkClientIdentifierArg("clientIdentifier", $clientIdentifier);
Checker::argStringNonEmptyOrNull("userLocale", $userLocale);
$this->accessToken = $accessToken;
$this->clientIdentifier = $clientIdentifier;
$this->userLocale = $userLocale;
// The $host parameter is sort of internal. We don't include it in the param list because
// we don't want it to be included in the documentation. Use PHP arg list hacks to get at
// it.
$host = null;
if (\func_num_args() == 4) {
$host = \func_get_arg(3);
Host::checkArgOrNull("host", $host);
}
if ($host === null) {
$host = Host::getDefault();
}
$this->host = $host;
// These fields are redundant, but it makes these values a little more convenient
// to access.
$this->apiHost = $host->getApi();
$this->contentHost = $host->getContent();
}
/** @var string */
private $apiHost;
/** @var string */
private $contentHost;
/**
* Given a `$base` path for an API endpoint (for example, "/files"), append
* a Dropbox API file path to the end of that URL. Special characters in the file will
* be encoded properly.
*
* This is for endpoints like "/files" takes the path on the URL and not as a separate
* query or POST parameter.
*
* @param string $base
* @param string $path
* @return string
*/
function appendFilePath($base, $path)
{
return $base . "/auto/" . rawurlencode(substr($path, 1));
}
/**
* Make an API call to disable the access token that you constructed this `Client`
* with. After calling this, API calls made with this `Client` will fail.
*
* See <a href="https://www.dropbox.com/developers/core/docs#disable-token">/disable_access_token</a>.
*
* @throws Exception
*/
function disableAccessToken()
{
$response = $this->doPost($this->apiHost, "1/disable_access_token");
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
}
/**
* Make an API call to get basic account and quota information.
*
* <code>
* $client = ...
* $accountInfo = $client->getAccountInfo();
* print_r($accountInfo);
* </code>
*
* @return array
* See <a href="https://www.dropbox.com/developers/core/docs#account-info">/account/info</a>.
*
* @throws Exception
*/
function getAccountInfo()
{
$response = $this->doGet($this->apiHost, "1/account/info");
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Downloads a file from Dropbox. The file's contents are written to the
* given `$outStream` and the file's metadata is returned.
*
* <code>
* $client = ...;
* $fd = fopen("./Frog.jpeg", "wb");
* $metadata = $client->getFile("/Photos/Frog.jpeg", $fd);
* fclose($fd);
* print_r($metadata);
* </code>
*
* @param string $path
* The path to the file on Dropbox (UTF-8).
*
* @param resource $outStream
* If the file exists, the file contents will be written to this stream.
*
* @param string|null $rev
* If you want the latest revision of the file at the given path, pass in `null`.
* If you want a specific version of a file, pass in value of the file metadata's "rev" field.
*
* @return null|array
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata
* object</a> for the file at the given $path and $rev, or `null` if the file
* doesn't exist,
*
* @throws Exception
*/
function getFile($path, $outStream, $rev = null)
{
Path::checkArgNonRoot("path", $path);
Checker::argResource("outStream", $outStream);
Checker::argStringNonEmptyOrNull("rev", $rev);
$url = $this->buildUrlForGetOrPut(
$this->contentHost,
$this->appendFilePath("1/files", $path),
array("rev" => $rev));
$curl = $this->mkCurl($url);
$metadataCatcher = new DropboxMetadataHeaderCatcher($curl->handle);
$streamRelay = new CurlStreamRelay($curl->handle, $outStream);
$response = $curl->exec();
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) {
$response->body = $streamRelay->getErrorBody();
throw RequestUtil::unexpectedStatus($response);
}
return $metadataCatcher->getMetadata();
}
/**
* Calling 'uploadFile' with `$numBytes` less than this value, will cause this SDK
* to use the standard /files_put endpoint. When `$numBytes` is greater than this
* value, we'll use the /chunked_upload endpoint.
*
* @var int
*/
private static $AUTO_CHUNKED_UPLOAD_THRESHOLD = 9863168; // 8 MB
/**
* @var int
*/
private static $DEFAULT_CHUNK_SIZE = 4194304; // 4 MB
/**
* Creates a file on Dropbox, using the data from `$inStream` for the file contents.
*
* <code>
* use \Dropbox as dbx;
* $client = ...;
* $fd = fopen("./frog.jpeg", "rb");
* $md1 = $client->uploadFile("/Photos/Frog.jpeg",
* dbx\WriteMode::add(), $fd);
* fclose($fd);
* print_r($md1);
* $rev = $md1["rev"];
*
* // Re-upload with WriteMode::update(...), which will overwrite the
* // file if it hasn't been modified from our original upload.
* $fd = fopen("./frog-new.jpeg", "rb");
* $md2 = $client->uploadFile("/Photos/Frog.jpeg",
* dbx\WriteMode::update($rev), $fd);
* fclose($fd);
* print_r($md2);
* </code>
*
* @param string $path
* The Dropbox path to save the file to (UTF-8).
*
* @param WriteMode $writeMode
* What to do if there's already a file at the given path.
*
* @param resource $inStream
* The data to use for the file contents.
*
* @param int|null $numBytes
* You can pass in `null` if you don't know. If you do provide the size, we can
* perform a slightly more efficient upload (fewer network round-trips) for files smaller
* than 8 MB.
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
* object</a> for the newly-added file.
*
* @throws Exception
*/
function uploadFile($path, $writeMode, $inStream, $numBytes = null)
{
Path::checkArgNonRoot("path", $path);
WriteMode::checkArg("writeMode", $writeMode);
Checker::argResource("inStream", $inStream);
Checker::argNatOrNull("numBytes", $numBytes);
// If we don't know how many bytes are coming, we have to use chunked upload.
// If $numBytes is large, we elect to use chunked upload.
// In all other cases, use regular upload.
if ($numBytes === null || $numBytes > self::$AUTO_CHUNKED_UPLOAD_THRESHOLD) {
$metadata = $this->_uploadFileChunked($path, $writeMode, $inStream, $numBytes,
self::$DEFAULT_CHUNK_SIZE);
} else {
$metadata = $this->_uploadFile($path, $writeMode,
function(Curl $curl) use ($inStream, $numBytes) {
$curl->set(CURLOPT_PUT, true);
$curl->set(CURLOPT_INFILE, $inStream);
$curl->set(CURLOPT_INFILESIZE, $numBytes);
});
}
return $metadata;
}
/**
* Creates a file on Dropbox, using the given $data string as the file contents.
*
* <code>
* use \Dropbox as dbx;
* $client = ...;
* $md = $client->uploadFileFromString("/Grocery List.txt",
* dbx\WriteMode::add(),
* "1. Coke\n2. Popcorn\n3. Toothpaste\n");
* print_r($md);
* </code>
*
* @param string $path
* The Dropbox path to save the file to (UTF-8).
*
* @param WriteMode $writeMode
* What to do if there's already a file at the given path.
*
* @param string $data
* The data to use for the contents of the file.
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
* object</a> for the newly-added file.
*
* @throws Exception
*/
function uploadFileFromString($path, $writeMode, $data)
{
Path::checkArgNonRoot("path", $path);
WriteMode::checkArg("writeMode", $writeMode);
Checker::argString("data", $data);
return $this->_uploadFile($path, $writeMode, function(Curl $curl) use ($data) {
$curl->set(CURLOPT_CUSTOMREQUEST, "PUT");
$curl->set(CURLOPT_POSTFIELDS, $data);
$curl->addHeader("Content-Type: application/octet-stream");
});
}
/**
* Creates a file on Dropbox, using the data from `$inStream` as the file contents.
*
* This version of `uploadFile` splits uploads the file ~4MB chunks at a time and
* will retry a few times if one chunk fails to upload. Uses {@link chunkedUploadStart()},
* {@link chunkedUploadContinue()}, and {@link chunkedUploadFinish()}.
*
* @param string $path
* The Dropbox path to save the file to (UTF-8).
*
* @param WriteMode $writeMode
* What to do if there's already a file at the given path.
*
* @param resource $inStream
* The data to use for the file contents.
*
* @param int|null $numBytes
* The number of bytes available from $inStream.
* You can pass in `null` if you don't know.
*
* @param int|null $chunkSize
* The number of bytes to upload in each chunk. You can omit this (or pass in
* `null` and the library will use a reasonable default.
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
* object</a> for the newly-added file.
*
* @throws Exception
*/
function uploadFileChunked($path, $writeMode, $inStream, $numBytes = null, $chunkSize = null)
{
if ($chunkSize === null) {
$chunkSize = self::$DEFAULT_CHUNK_SIZE;
}
Path::checkArgNonRoot("path", $path);
WriteMode::checkArg("writeMode", $writeMode);
Checker::argResource("inStream", $inStream);
Checker::argNatOrNull("numBytes", $numBytes);
Checker::argIntPositive("chunkSize", $chunkSize);
return $this->_uploadFileChunked($path, $writeMode, $inStream, $numBytes, $chunkSize);
}
/**
* @param string $path
*
* @param WriteMode $writeMode
* What to do if there's already a file at the given path (UTF-8).
*
* @param resource $inStream
* The source of data to upload.
*
* @param int|null $numBytes
* You can pass in `null`. But if you know how many bytes you expect, pass in
* that value and this function will do a sanity check at the end to make sure the number of
* bytes read from `$inStream` matches up.
*
* @param int $chunkSize
*
* @return array
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
* object</a> for the newly-added file.
*/
private function _uploadFileChunked($path, $writeMode, $inStream, $numBytes, $chunkSize)
{
Path::checkArg("path", $path);
WriteMode::checkArg("writeMode", $writeMode);
Checker::argResource("inStream", $inStream);
Checker::argNatOrNull("numBytes", $numBytes);
Checker::argNat("chunkSize", $chunkSize);
// NOTE: This function performs 3 retries on every call. This is maybe not the right
// layer to make retry decisions. It's also awkward because none of the other calls
// perform retries.
assert($chunkSize > 0);
$data = self::readFully($inStream, $chunkSize);
$len = strlen($data);
$client = $this;
$uploadId = RequestUtil::runWithRetry(3, function() use ($data, $client) {
return $client->chunkedUploadStart($data);
});
$byteOffset = $len;
while (!feof($inStream)) {
$data = self::readFully($inStream, $chunkSize);
$len = strlen($data);
while (true) {
$r = RequestUtil::runWithRetry(3,
function() use ($client, $uploadId, $byteOffset, $data) {
return $client->chunkedUploadContinue($uploadId, $byteOffset, $data);
});
if ($r === true) { // Chunk got uploaded!
$byteOffset += $len;
break;
}
if ($r === false) { // Server didn't recognize our upload ID
// This is very unlikely since we're uploading all the chunks in sequence.
throw new Exception_BadResponse("Server forgot our uploadId");
}
// Otherwise, the server is at a different byte offset from us.
$serverByteOffset = $r;
assert($serverByteOffset !== $byteOffset); // chunkedUploadContinue ensures this.
// An earlier byte offset means the server has lost data we sent earlier.
if ($serverByteOffset < $byteOffset) throw new Exception_BadResponse(
"Server is at an ealier byte offset: us=$byteOffset, server=$serverByteOffset");
$diff = $serverByteOffset - $byteOffset;
// If the server is past where we think it could possibly be, something went wrong.
if ($diff > $len) throw new Exception_BadResponse(
"Server is more than a chunk ahead: us=$byteOffset, server=$serverByteOffset");
// The normal case is that the server is a bit further along than us because of a
// partially-uploaded chunk. Finish it off.
$byteOffset += $diff;
if ($diff === $len) break; // If the server is at the end, we're done.
$data = substr($data, $diff);
}
}
if ($numBytes !== null && $byteOffset !== $numBytes) throw new \InvalidArgumentException(
"You passed numBytes=$numBytes but the stream had $byteOffset bytes.");
$metadata = RequestUtil::runWithRetry(3,
function() use ($client, $uploadId, $path, $writeMode) {
return $client->chunkedUploadFinish($uploadId, $path, $writeMode);
});
return $metadata;
}
/**
* Sometimes fread() returns less than the request number of bytes (for example, when reading
* from network streams). This function repeatedly calls fread until the requested number of
* bytes have been read or we've reached EOF.
*
* @param resource $inStream
* @param int $numBytes
* @throws StreamReadException
* @return string
*/
private static function readFully($inStream, $numBytes)
{
Checker::argNat("numBytes", $numBytes);
$full = '';
$bytesRemaining = $numBytes;
while (!feof($inStream) && $bytesRemaining > 0) {
$part = fread($inStream, $bytesRemaining);
if ($part === false) throw new StreamReadException("Error reading from \$inStream.");
$full .= $part;
$bytesRemaining -= strlen($part);
}
return $full;
}
/**
* @param string $path
* @param WriteMode $writeMode
* @param callable $curlConfigClosure
* @return array
*/
private function _uploadFile($path, $writeMode, $curlConfigClosure)
{
Path::checkArg("path", $path);
WriteMode::checkArg("writeMode", $writeMode);
Checker::argCallable("curlConfigClosure", $curlConfigClosure);
$url = $this->buildUrlForGetOrPut(
$this->contentHost,
$this->appendFilePath("1/files_put", $path),
$writeMode->getExtraParams());
$curl = $this->mkCurl($url);
$curlConfigClosure($curl);
$curl->set(CURLOPT_RETURNTRANSFER, true);
$response = $curl->exec();
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Start a new chunked upload session and upload the first chunk of data.
*
* @param string $data
* The data to start off the chunked upload session.
*
* @return array
* A pair of `(string $uploadId, int $byteOffset)`. `$uploadId`
* is a unique identifier for this chunked upload session. You pass this in to
* {@link chunkedUploadContinue} and {@link chuunkedUploadFinish}. `$byteOffset`
* is the number of bytes that were successfully uploaded.
*
* @throws Exception
*/
function chunkedUploadStart($data)
{
Checker::argString("data", $data);
$response = $this->_chunkedUpload(array(), $data);
if ($response->statusCode === 404) {
throw new Exception_BadResponse("Got a 404, but we didn't send up an 'upload_id'");
}
$correction = self::_chunkedUploadCheckForOffsetCorrection($response);
if ($correction !== null) throw new Exception_BadResponse(
"Got an offset-correcting 400 response, but we didn't send an offset");
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
list($uploadId, $byteOffset) = self::_chunkedUploadParse200Response($response->body);
$len = strlen($data);
if ($byteOffset !== $len) throw new Exception_BadResponse(
"We sent $len bytes, but server returned an offset of $byteOffset");
return $uploadId;
}
/**
* Append another chunk data to a previously-started chunked upload session.
*
* @param string $uploadId
* The unique identifier for the chunked upload session. This is obtained via
* {@link chunkedUploadStart}.
*
* @param int $byteOffset
* The number of bytes you think you've already uploaded to the given chunked upload
* session. The server will append the new chunk of data after that point.
*
* @param string $data
* The data to append to the existing chunked upload session.
*
* @return int|bool
* If `false`, it means the server didn't know about the given
* `$uploadId`. This may be because the chunked upload session has expired
* (they last around 24 hours).
* If `true`, the chunk was successfully uploaded. If an integer, it means
* you and the server don't agree on the current `$byteOffset`. The returned
* integer is the server's internal byte offset for the chunked upload session. You need
* to adjust your input to match.
*
* @throws Exception
*/
function chunkedUploadContinue($uploadId, $byteOffset, $data)
{
Checker::argStringNonEmpty("uploadId", $uploadId);
Checker::argNat("byteOffset", $byteOffset);
Checker::argString("data", $data);
$response = $this->_chunkedUpload(
array("upload_id" => $uploadId, "offset" => $byteOffset), $data);
if ($response->statusCode === 404) {
// The server doesn't know our upload ID. Maybe it expired?
return false;
}
$correction = self::_chunkedUploadCheckForOffsetCorrection($response);
if ($correction !== null) {
list($correctedUploadId, $correctedByteOffset) = $correction;
if ($correctedUploadId !== $uploadId) throw new Exception_BadResponse(
"Corrective 400 upload_id mismatch: us=".
Util::q($uploadId)." server=".Util::q($correctedUploadId));
if ($correctedByteOffset === $byteOffset) throw new Exception_BadResponse(
"Corrective 400 offset is the same as ours: $byteOffset");
return $correctedByteOffset;
}
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
list($retUploadId, $retByteOffset) = self::_chunkedUploadParse200Response($response->body);
$nextByteOffset = $byteOffset + strlen($data);
if ($uploadId !== $retUploadId) throw new Exception_BadResponse(
"upload_id mismatch: us=".Util::q($uploadId) .", server=".Util::q($uploadId));
if ($nextByteOffset !== $retByteOffset) throw new Exception_BadResponse(
"next-offset mismatch: us=$nextByteOffset, server=$retByteOffset");
return true;
}
/**
* @param string $body
* @return array
*/
private static function _chunkedUploadParse200Response($body)
{
$j = RequestUtil::parseResponseJson($body);
$uploadId = self::getField($j, "upload_id");
$byteOffset = self::getField($j, "offset");
return array($uploadId, $byteOffset);
}
/**
* @param HttpResponse $response
* @return array|null
*/
private static function _chunkedUploadCheckForOffsetCorrection($response)
{
if ($response->statusCode !== 400) return null;
$j = json_decode($response->body, true, 10);
if ($j === null) return null;
if (!array_key_exists("upload_id", $j) || !array_key_exists("offset", $j)) return null;
$uploadId = $j["upload_id"];
$byteOffset = $j["offset"];
return array($uploadId, $byteOffset);
}
/**
* Creates a file on Dropbox using the accumulated contents of the given chunked upload session.
*
* See <a href="https://www.dropbox.com/developers/core/docs#commit-chunked-upload">/commit_chunked_upload</a>.
*
* @param string $uploadId
* The unique identifier for the chunked upload session. This is obtained via
* {@link chunkedUploadStart}.
*
* @param string $path
* The Dropbox path to save the file to.
*
* @param WriteMode $writeMode
* What to do if there's already a file at the given path.
*
* @return array|null
* If `null`, it means the Dropbox server wasn't aware of the
* `$uploadId` you gave it.
* Otherwise, you get back the
* <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>
* for the newly-created file.
*
* @throws Exception
*/
function chunkedUploadFinish($uploadId, $path, $writeMode)
{
Checker::argStringNonEmpty("uploadId", $uploadId);
Path::checkArgNonRoot("path", $path);
WriteMode::checkArg("writeMode", $writeMode);
$params = array_merge(array("upload_id" => $uploadId), $writeMode->getExtraParams());
$response = $this->doPost(
$this->contentHost,
$this->appendFilePath("1/commit_chunked_upload", $path),
$params);
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* @param array $params
* @param string $data
* @return HttpResponse
*/
protected function _chunkedUpload($params, $data)
// Marked 'protected' so I can override it in testing.
{
$url = $this->buildUrlForGetOrPut(
$this->contentHost, "1/chunked_upload", $params);
$curl = $this->mkCurl($url);
// We can't use CURLOPT_PUT because it wants a stream, but we already have $data in memory.
$curl->set(CURLOPT_CUSTOMREQUEST, "PUT");
$curl->set(CURLOPT_POSTFIELDS, $data);
$curl->addHeader("Content-Type: application/octet-stream");
$curl->set(CURLOPT_RETURNTRANSFER, true);
return $curl->exec();
}
/**
* Returns the metadata for whatever file or folder is at the given path.
*
* <code>
* $client = ...;
* $md = $client->getMetadata("/Photos/Frog.jpeg");
* print_r($md);
* </code>
*
* @param string $path
* The Dropbox path to a file or folder (UTF-8).
*
* @return array|null
* If there is a file or folder at the given path, you'll get back the
* <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>
* for that file or folder. If not, you'll get back `null`.
*
* @throws Exception
*/
function getMetadata($path)
{
Path::checkArg("path", $path);
return $this->_getMetadata($path, array("list" => "false"));
}
/**
* Returns the metadata for whatever file or folder is at the given path and, if it's a folder,
* also include the metadata for all the immediate children of that folder.
*
* <code>
* $client = ...;
* $md = $client->getMetadataWithChildren("/Photos");
* print_r($md);
* </code>
*
* @param string $path
* The Dropbox path to a file or folder (UTF-8).
*
* @return array|null
* If there is a file or folder at the given path, you'll get back the
* <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>
* for that file or folder, along with all immediate children if it's a folder. If not,
* you'll get back `null`.
*
* @throws Exception
*/
function getMetadataWithChildren($path)
{
Path::checkArg("path", $path);
return $this->_getMetadata($path, array("list" => "true", "file_limit" => "25000"));
}
/**
* @param string $path
* @param array $params
* @return array
*/
private function _getMetadata($path, $params)
{
$response = $this->doGet(
$this->apiHost,
$this->appendFilePath("1/metadata", $path),
$params);
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
$metadata = RequestUtil::parseResponseJson($response->body);
if (array_key_exists("is_deleted", $metadata) && $metadata["is_deleted"]) return null;
return $metadata;
}
/**
* If you've previously retrieved the metadata for a folder and its children, this method will
* retrieve updated metadata only if something has changed. This is more efficient than
* calling {@link getMetadataWithChildren} if you have a cache of previous results.
*
* <code>
* $client = ...;
* $md = $client->getMetadataWithChildren("/Photos");
* print_r($md);
* assert($md["is_dir"], "expecting \"/Photos\" to be a folder");
*
* sleep(10);
*
* // Now see if anything changed...
* list($changed, $new_md) = $client->getMetadataWithChildrenIfChanged(
* "/Photos", $md["hash"]);
* if ($changed) {
* echo "Folder changed.\n";
* print_r($new_md);
* } else {
* echo "Folder didn't change.\n";
* }
* </code>
*
* @param string $path
* The Dropbox path to a folder (UTF-8).
*
* @param string $previousFolderHash
* The "hash" field from the previously retrieved folder metadata.
*
* @return array
* A `list(boolean $changed, array $metadata)`. If the metadata hasn't changed,
* you'll get `list(false, null)`. If the metadata of the folder or any of its
* children has changed, you'll get `list(true, $newMetadata)`. $metadata is a
* <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>.
*
* @throws Exception
*/
function getMetadataWithChildrenIfChanged($path, $previousFolderHash)
{
Path::checkArg("path", $path);
Checker::argStringNonEmpty("previousFolderHash", $previousFolderHash);
$params = array("list" => "true", "file_limit" => "25000", "hash" => $previousFolderHash);
$response = $this->doGet(
$this->apiHost,
$this->appendFilePath("1/metadata", $path),
$params);
if ($response->statusCode === 304) return array(false, null);
if ($response->statusCode === 404) return array(true, null);
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
$metadata = RequestUtil::parseResponseJson($response->body);
if (array_key_exists("is_deleted", $metadata) && $metadata["is_deleted"]) {
return array(true, null);
}
return array(true, $metadata);
}
/**
* A way of letting you keep up with changes to files and folders in a user's Dropbox.
*
* @param string|null $cursor
* If this is the first time you're calling this, pass in `null`. Otherwise,
* pass in whatever cursor was returned by the previous call.
*
* @param string|null $pathPrefix
* If `null`, you'll get results for the entire folder (either the user's
* entire Dropbox or your App Folder). If you set `$path_prefix` to
* "/Photos/Vacation", you'll only get results for that path and any files and folders
* under it.
*
* @return array
* A <a href="https://www.dropbox.com/developers/core/docs#delta">delta page</a>, which
* contains a list of changes to apply along with a new "cursor" that should be passed into
* future `getDelta` calls. If the "reset" field is `true`, you
* should clear your local state before applying the changes. If the "has_more" field is
* `true`, call `getDelta` immediately to get more results, otherwise
* wait a while (at least 5 minutes) before calling `getDelta` again.
*
* @throws Exception
*/
function getDelta($cursor = null, $pathPrefix = null)
{
Checker::argStringNonEmptyOrNull("cursor", $cursor);
Path::checkArgOrNull("pathPrefix", $pathPrefix);
$response = $this->doPost($this->apiHost, "1/delta", array(
"cursor" => $cursor,
"path_prefix" => $pathPrefix));
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Gets the metadata for all the file revisions (up to a limit) for a given path.
*
* See <a href="https://www.dropbox.com/developers/core/docs#revisions">/revisions</a>.
*
* @param string path
* The Dropbox path that you want file revision metadata for (UTF-8).
*
* @param int|null limit
* The maximum number of revisions to return.
*
* @return array|null
* A list of <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
* objects</a>, one for each file revision. The later revisions appear first in the list.
* If `null`, then there were too many revisions at that path.
*
* @throws Exception
*/
function getRevisions($path, $limit = null)
{
Path::checkArgNonRoot("path", $path);
Checker::argIntPositiveOrNull("limit", $limit);
$response = $this->doGet(
$this->apiHost,
$this->appendFilePath("1/revisions", $path),
array("rev_limit" => $limit));
if ($response->statusCode === 406) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Takes a copy of the file at the given revision and saves it over the current copy. This
* will create a new revision, but the file contents will match the revision you specified.
*
* See <a href="https://www.dropbox.com/developers/core/docs#restore">/restore</a>.
*
* @param string $path
* The Dropbox path of the file to restore (UTF-8).
*
* @param string $rev
* The revision to restore the contents to.
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata
* object</a>
*
* @throws Exception
*/
function restoreFile($path, $rev)
{
Path::checkArgNonRoot("path", $path);
Checker::argStringNonEmpty("rev", $rev);
$response = $this->doPost(
$this->apiHost,
$this->appendFilePath("1/restore", $path),
array("rev" => $rev));
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Returns metadata for all files and folders whose filename matches the query string.
*
* See <a href="https://www.dropbox.com/developers/core/docs#search">/search</a>.
*
* @param string $basePath
* The path to limit the search to (UTF-8). Pass in "/" to search everything.
*
* @param string $query
* A space-separated list of substrings to search for. A file matches only if it contains
* all the substrings.
*
* @param int|null $limit
* The maximum number of results to return.
*
* @param bool $includeDeleted
* Whether to include deleted files in the results.
*
* @return mixed
* A list of <a href="https://www.dropbox.com/developers/core/docs#metadata-details>metadata
* objects</a> of files that match the search query.
*
* @throws Exception
*/
function searchFileNames($basePath, $query, $limit = null, $includeDeleted = false)
{
Path::checkArg("basePath", $basePath);
Checker::argStringNonEmpty("query", $query);
Checker::argNatOrNull("limit", $limit);
Checker::argBool("includeDeleted", $includeDeleted);
$response = $this->doPost(
$this->apiHost,
$this->appendFilePath("1/search", $basePath),
array(
"query" => $query,
"file_limit" => $limit,
"include_deleted" => $includeDeleted,
));
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Creates and returns a public link to a file or folder's "preview page". This link can be
* used without authentication. The preview page may contain a thumbnail or some other
* preview of the file, along with a download link to download the actual file.
*
* See <a href="https://www.dropbox.com/developers/core/docs#shares">/shares</a>.
*
* @param string $path
* The Dropbox path to the file or folder you want to create a shareable link to (UTF-8).
*
* @return string
* The URL of the preview page.
*
* @throws Exception
*/
function createShareableLink($path)
{
Path::checkArg("path", $path);
$response = $this->doPost(
$this->apiHost,
$this->appendFilePath("1/shares", $path),
array(
"short_url" => "false",
));
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
$j = RequestUtil::parseResponseJson($response->body);
return self::getField($j, "url");
}
/**
* Creates and returns a direct link to a file. This link can be used without authentication.
* This link will expire in a few hours.
*
* See <a href="https://www.dropbox.com/developers/core/docs#media">/media</a>.
*
* @param string $path
* The Dropbox path to a file or folder (UTF-8).
*
* @return array
* A `list(string $url, \DateTime $expires)` where `$url` is a direct
* link to the requested file and `$expires` is a standard PHP
* `\DateTime` representing when `$url` will stop working.
*
* @throws Exception
*/
function createTemporaryDirectLink($path)
{
Path::checkArgNonRoot("path", $path);
$response = $this->doPost(
$this->apiHost,
$this->appendFilePath("1/media", $path));
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
$j = RequestUtil::parseResponseJson($response->body);
$url = self::getField($j, "url");
$expires = self::parseDateTime(self::getField($j, "expires"));
return array($url, $expires);
}
/**
* Creates and returns a "copy ref" to a file. A copy ref can be used to copy a file across
* different Dropbox accounts without downloading and re-uploading.
*
* For example: Create a `Client` using the access token from one account and call
* `createCopyRef`. Then, create a `Client` using the access token for
* another account and call `copyFromCopyRef` using the copy ref. (You need to use
* the same app key both times.)
*
* See <a href="https://www.dropbox.com/developers/core/docs#copy_ref">/copy_ref</a>.
*
* @param string path
* The Dropbox path of the file or folder you want to create a copy ref for (UTF-8).
*
* @return string
* The copy ref (just a string that you keep track of).
*
* @throws Exception
*/
function createCopyRef($path)
{
Path::checkArg("path", $path);
$response = $this->doGet(
$this->apiHost,
$this->appendFilePath("1/copy_ref", $path));
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
$j = RequestUtil::parseResponseJson($response->body);
return self::getField($j, "copy_ref");
}
/**
* Gets a thumbnail image representation of the file at the given path.
*
* See <a href="https://www.dropbox.com/developers/core/docs#thumbnails">/thumbnails</a>.
*
* @param string $path
* The path to the file you want a thumbnail for (UTF-8).
*
* @param string $format
* One of the two image formats: "jpeg" or "png".
*
* @param string $size
* One of the predefined image size names, as a string:
* <ul>
* <li>"xs" - 32x32</li>
* <li>"s" - 64x64</li>
* <li>"m" - 128x128</li>
* <li>"l" - 640x480</li>
* <li>"xl" - 1024x768</li>
* </ul>
*
* @return array|null
* If the file exists, you'll get `list(array $metadata, string $data)` where
* `$metadata` is the file's
* <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>
* and $data is the raw data for the thumbnail image. If the file doesn't exist, you'll
* get `null`.
*
* @throws Exception
*/
function getThumbnail($path, $format, $size)
{
Path::checkArgNonRoot("path", $path);
Checker::argString("format", $format);
Checker::argString("size", $size);
if (!in_array($format, array("jpeg", "png"))) {
throw new \InvalidArgumentException("Invalid 'format': ".Util::q($format));
}
if (!in_array($size, array("xs", "s", "m", "l", "xl"))) {
throw new \InvalidArgumentException("Invalid 'size': ".Util::q($size));
}
$url = $this->buildUrlForGetOrPut(
$this->contentHost,
$this->appendFilePath("1/thumbnails", $path),
array("size" => $size, "format" => $format));
$curl = $this->mkCurl($url);
$metadataCatcher = new DropboxMetadataHeaderCatcher($curl->handle);
$curl->set(CURLOPT_RETURNTRANSFER, true);
$response = $curl->exec();
if ($response->statusCode === 404) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
$metadata = $metadataCatcher->getMetadata();
return array($metadata, $response->body);
}
/**
* Copies a file or folder to a new location
*
* See <a href="https://www.dropbox.com/developers/core/docs#fileops-copy">/fileops/copy</a>.
*
* @param string $fromPath
* The Dropbox path of the file or folder you want to copy (UTF-8).
*
* @param string $toPath
* The destination Dropbox path (UTF-8).
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata
* object</a> for the new file or folder.
*
* @throws Exception
*/
function copy($fromPath, $toPath)
{
Path::checkArg("fromPath", $fromPath);
Path::checkArgNonRoot("toPath", $toPath);
$response = $this->doPost(
$this->apiHost,
"1/fileops/copy",
array(
"root" => "auto",
"from_path" => $fromPath,
"to_path" => $toPath,
));
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Creates a file or folder based on an existing copy ref (possibly from a different Dropbox
* account).
*
* See <a href="https://www.dropbox.com/developers/core/docs#fileops-copy">/fileops/copy</a>.
*
* @param string $copyRef
* A copy ref obtained via the {@link createCopyRef()} call.
*
* @param string $toPath
* The Dropbox path you want to copy the file or folder to (UTF-8).
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata
* object</a> for the new file or folder.
*
* @throws Exception
*/
function copyFromCopyRef($copyRef, $toPath)
{
Checker::argStringNonEmpty("copyRef", $copyRef);
Path::checkArgNonRoot("toPath", $toPath);
$response = $this->doPost(
$this->apiHost,
"1/fileops/copy",
array(
"root" => "auto",
"from_copy_ref" => $copyRef,
"to_path" => $toPath,
)
);
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Creates a folder.
*
* See <a href="https://www.dropbox.com/developers/core/docs#fileops-create-folder">/fileops/create_folder</a>.
*
* @param string $path
* The Dropbox path at which to create the folder (UTF-8).
*
* @return array|null
* If successful, you'll get back the
* <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata object</a>
* for the newly-created folder. If not successful, you'll get `null`.
*
* @throws Exception
*/
function createFolder($path)
{
Path::checkArgNonRoot("path", $path);
$response = $this->doPost(
$this->apiHost,
"1/fileops/create_folder",
array(
"root" => "auto",
"path" => $path,
));
if ($response->statusCode === 403) return null;
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Deletes a file or folder
*
* See <a href="https://www.dropbox.com/developers/core/docs#fileops-delete">/fileops/delete</a>.
*
* @param string $path
* The Dropbox path of the file or folder to delete (UTF-8).
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata
* object</a> for the deleted file or folder.
*
* @throws Exception
*/
function delete($path)
{
Path::checkArgNonRoot("path", $path);
$response = $this->doPost(
$this->apiHost,
"1/fileops/delete",
array(
"root" => "auto",
"path" => $path,
));
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Moves a file or folder to a new location.
*
* See <a href="https://www.dropbox.com/developers/core/docs#fileops-move">/fileops/move</a>.
*
* @param string $fromPath
* The source Dropbox path (UTF-8).
*
* @param string $toPath
* The destination Dropbox path (UTF-8).
*
* @return mixed
* The <a href="https://www.dropbox.com/developers/core/docs#metadata-details">metadata
* object</a> for the destination file or folder.
*
* @throws Exception
*/
function move($fromPath, $toPath)
{
Path::checkArgNonRoot("fromPath", $fromPath);
Path::checkArgNonRoot("toPath", $toPath);
$response = $this->doPost(
$this->apiHost,
"1/fileops/move",
array(
"root" => "auto",
"from_path" => $fromPath,
"to_path" => $toPath,
));
if ($response->statusCode !== 200) throw RequestUtil::unexpectedStatus($response);
return RequestUtil::parseResponseJson($response->body);
}
/**
* Build a URL for making a GET or PUT request. Will add the "locale"
* parameter.
*
* @param string $host
* Either the "API" or "API content" hostname from {@link getHost()}.
* @param string $path
* The "path" part of the URL. For example, "/account/info".
* @param array|null $params
* URL parameters. For POST requests, do not put the parameters here.
* Include them in the request body instead.
*
* @return string
*/
function buildUrlForGetOrPut($host, $path, $params = null)
{
return RequestUtil::buildUrlForGetOrPut($this->userLocale, $host, $path, $params);
}
/**
* Perform an OAuth-2-authorized GET request to the Dropbox API. Will automatically
* fill in "User-Agent" and "locale" as well.
*
* @param string $host
* Either the "API" or "API content" hostname from {@link getHost()}.
* @param string $path
* The "path" part of the URL. For example, "/account/info".
* @param array|null $params
* GET parameters.
* @return HttpResponse
*
* @throws Exception
*/
function doGet($host, $path, $params = null)
{
Checker::argString("host", $host);
Checker::argString("path", $path);
return RequestUtil::doGet($this->clientIdentifier, $this->accessToken, $this->userLocale,
$host, $path, $params);
}
/**
* Perform an OAuth-2-authorized POST request to the Dropbox API. Will automatically
* fill in "User-Agent" and "locale" as well.
*
* @param string $host
* Either the "API" or "API content" hostname from {@link getHost()}.
* @param string $path
* The "path" part of the URL. For example, "/commit_chunked_upload".
* @param array|null $params
* POST parameters.
* @return HttpResponse
*
* @throws Exception
*/
function doPost($host, $path, $params = null)
{
Checker::argString("host", $host);
Checker::argString("path", $path);
return RequestUtil::doPost($this->clientIdentifier, $this->accessToken, $this->userLocale,
$host, $path, $params);
}
/**
* Create a {@link Curl} object that is pre-configured with {@link getClientIdentifier()},
* and the proper OAuth 2 "Authorization" header.
*
* @param string $url
* Generate this URL using {@link buildUrl()}.
*
* @return Curl
*/
function mkCurl($url)
{
return RequestUtil::mkCurlWithOAuth($this->clientIdentifier, $url, $this->accessToken);
}
/**
* Parses date/time strings returned by the Dropbox API. The Dropbox API returns date/times
* formatted like: `"Sat, 21 Aug 2010 22:31:20 +0000"`.
*
* @param string $apiDateTimeString
* A date/time string returned by the API.
*
* @return \DateTime
* A standard PHP `\DateTime` instance.
*
* @throws Exception_BadResponse
* Thrown if `$apiDateTimeString` isn't correctly formatted.
*/
static function parseDateTime($apiDateTimeString)
{
$dt = \DateTime::createFromFormat(self::$dateTimeFormat, $apiDateTimeString);
if ($dt === false) throw new Exception_BadResponse(
"Bad date/time from server: ".Util::q($apiDateTimeString));
return $dt;
}
private static $dateTimeFormat = "D, d M Y H:i:s T";
/**
* @internal
*/
static function getField($j, $fieldName)
{
if (!array_key_exists($fieldName, $j)) throw new Exception_BadResponse(
"missing field \"$fieldName\" in ".Util::q($j));
return $j[$fieldName];
}
/**
* Given an OAuth 2 access token, returns `null` if it is well-formed (though
* not necessarily valid). Otherwise, returns a string describing what's wrong with it.
*
* @param string $s
*
* @return string
*/
static function getAccessTokenError($s)
{
if ($s === null) return "can't be null";
if (strlen($s) === 0) return "can't be empty";
if (preg_match('@[^-=_~/A-Za-z0-9\.\+]@', $s) === 1) return "contains invalid character";
return null;
}
/**
* @internal
*/
static function checkAccessTokenArg($argName, $accessToken)
{
$error = self::getAccessTokenError($accessToken);
if ($error !== null) throw new \InvalidArgumentException("'$argName' invalid: $error");
}
/**
* @internal
*/
static function getClientIdentifierError($s)
{
if ($s === null) return "can't be null";
if (strlen($s) === 0) return "can't be empty";
if (preg_match('@[\x00-\x1f\x7f]@', $s) === 1) return "contains control character";
return null;
}
/**
* @internal
*/
static function checkClientIdentifierArg($argName, $accessToken)
{
$error = self::getClientIdentifierError($accessToken);
if ($error !== null) throw new \InvalidArgumentException("'$argName' invalid: $error");
}
}