All Products
Search
Document Center

PHP upload SDK

Last Updated: Aug 13, 2019

SDK introduction

Overview

ApsaraVideo for VOD is built based on OSS. After you activate ApsaraVideo for VOD, ApsaraVideo for VOD automatically allocates a dedicated bucket for you. The bucket stores various media files, including the video, audio, and image mezzanine files as well as the transcoded files, snapshots, and thumbnails. The bucket also serves as the CDN’s origin for ApsaraVideo for VOD. You can use the upload SDKs of ApsaraVideo for VOD to quickly upload media files. For more information about supported file formats, see Supported file formats for upload.

Features

PHP upload SDK has the following features.

Main features

  1. Supports uploading various media files, including videos, audio files, images, and attached media assets (such as watermark and subtitle files), to ApsaraVideo for VOD.
  2. Supports uploading local media files to ApsaraVideo for VOD. By default, multipart upload is used. The maximum size of a single file that can be uploaded is 48.8 TB. Resumable upload is not currently supported.
  3. Supports uploading online media files stored on the Internet to ApsaraVideo for VOD. The maximum size of a single file that can be uploaded is 5 GB. An online media file is downloaded to a local temporary directory before being uploaded. Resumable upload is not currently supported.
  4. Supports uploading M3U8 videos and provides a method for parsing the .m3u8 playlist to obtain the URL list of parts. You can also specify the URLs of parts.

Other features

  1. Provides an upload progress bar and supports the default and custom progress callbacks.
  2. Supports specifying the region of the ECS instance on which the upload script is deployed. If the region of the ECS instance is the same as the storage region in ApsaraVideo for VOD, the file is automatically uploaded through the intranet to accelerate the upload speed and save the public network traffic.
  3. Supports specifying the ApsaraVideo for VOD center and storage region to facilitate upload in regions outside China. The default ApsaraVideo for VOD center is located in Shanghai.
  4. Supports setting the metadata (such as the title), StorageLocation, UserData, and transcoding templates for the upload.

SDK installation

Environment requirements

  • Ensure that you have installed PHP 5.3 or later. You can run the php -v command to view the current PHP version. If PHP is not installed, you can visit the PHP official website to download and install an appropriate version.
  • Ensure that you have installed and enabled php-mbstring and php_curl.
  • Linux, UNIX, Mac, and Windows are supported.

Install the SDK

On the SDK download page, click the download address for PHP upload SDK and download it. Decompress the package and copy voduploadsdk in the VodUploadSDK-PHP directory to your project. Then, you can use the SDK. The samples directory provides the sample code.

Upgrade the SDK

If certain new APIs or new features of existing APIs are unavailable in the current SDK, upgrade the SDK to the latest version.Download the latest version of PHP upload SDK. Extract files and save them by replacing existing ones.

After decompression, theChangeLog.txtfile generated in the voduploadsdk directory provides version history. You can obtain the version number and release date of the current SDK in the first line.

How to use the SDK

SDK structure

Structure

The structure of the VodUploadSDK-PHP directory in the upload SDK is as follows:

  1. VodUploadSDK-PHP
  2. └───voduploadsdk
  3. ChangeLog.txt
  4. Autoloader.php
  5. └───uploader
  6. UploadVideoRequest.php
  7. UploadImageRequest.php
  8. UploadAttachedMediaRequest.php
  9. AliyunVodUploader.php
  10. AliyunVodUtils.php
  11. └───aliyun-php-sdk-core
  12. └───aliyun-php-sdk-oss
  13. └───aliyun-php-sdk-vod
  14. └───samples
  15. uploadVideo.php
  16. uploadImage.php
  17. uploadAttachedMedia.php

Auxiliary files

  • ChangeLog.txt: provides version history. You can obtain the version number and release date of the current SDK in the first line.
  • Autoloader.php: is the class file loader. Require this file when you use the SDK.

Structure files

  • UploadVideoRequest.php

    • The request class for uploading videos. For more information about its fields, see CreateUploadVideo.
  • UploadImageRequest.php

    • The request class for uploading images. For more information about its fields, see CreateUploadImage.
  • UploadAttachedMediaRequest.php

    • The request class for uploading attached media assets. For more information about its fields, see CreateUploadAttachedMedia.
  • AliyunVodUploader.php, which mainly includes methods of the AliyunVodUploader class.

    • __construct: a constructor used to set the AccessKey and ApsaraVideo for VOD access region for the upload.
    • uploadLocalVideo: a method for uploading local videos.
    • uploadWebVideo: a method for uploading online videos.
    • uploadLocalImage: a method for uploading local images.
    • uploadWebImage: a method for uploading online images.
    • uploadLocalAttachedMedia: a method for uploading local attached media assets.
    • uploadWebAttachedMedia: a method for uploading online attached media assets.
    • uploadLocalM3u8: a method for uploading local M3U8 videos.
    • uploadWebM3u8: a method for uploading online M3U8 videos.
    • parseM3u8File: a method for parsing the .m3u8 playlist to obtain the URL list of parts.
    • setEcsRegionId: a method for specifying the region of the ECS instance (if any) on which the upload script is deployed. If the region of the ECS instance is the same as the storage region in ApsaraVideo for VOD, the file is automatically uploaded through the intranet.
    • setEnableSSL: a method for specifying whether to enable Secure Sockets Layer (SSL) for HTTPS requests. By default, SSL is disabled to prevent the failure to use the SDK when related extensions are not installed or a configuration exception occurs.
    • uploadProgressCallback: a method for specifying the callback for upload progress. This method can be overridden.
  • AliyunVodUtils.php

    • AliyunVodUtils: is the utility class. It provides static functions for truncating strings and obtaining extensions and file names.
    • AliyunVodLog: is the log class. It provides the simple logging service. You can set $logSwitch to determine whether to enable the logging service.
    • AliyunVodDownloader: downloads online files.
    • AliyunVodReportUpload: reports the upload progress.
    • AliyunVodError: defines the error code.

Dependency packages

  • aliyun-php-sdk-core: provides the base class on which the upload SDK depends. This package encapsulates Alibaba Cloud API signatures and HTTP requests.
  • aliyun-php-sdk-vod: provides the server SDK of ApsaraVideo for VOD. This package encapsulates ApsaraVideo for VOD API requests.
  • aliyun-php-sdk-oss: provides the OSS class on which the upload SDK depends. This package encapsulates operations such as OSS upload.

samples directory

  • uploadVideo.php: provides the sample code for uploading videos.
  • uploadImage.php: provides the sample code for uploading images.
  • uploadAttachedMedia.php: provides the sample code for uploading attached media assets.

Example

The following section provides the sample code for uploading local videos and online videos:

  1. <? php
  2. /**
  3. * Created by ApsaraVideo for VOD.
  4. * User: https://www.aliyun.com/product/vod
  5. * API document: https://www.alibabacloud.com/help/zh/doc-detail/55407.htm
  6. */
  7. require_once dirname(__DIR__) . DIRECTORY_SEPARATOR . 'voduploadsdk' . DIRECTORY_SEPARATOR . 'Autoloader.php';
  8. date_default_timezone_set('PRC');
  9. // Tests the upload of a local video.
  10. function testUploadLocalVideo($accessKeyId, $accessKeySecret, $filePath)
  11. {
  12. try {
  13. $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
  14. $uploadVideoRequest = new UploadVideoRequest($filePath, 'testUploadLocalVideo via PHP-SDK');
  15. //$uploadVideoRequest->setCateId(1);
  16. //$uploadVideoRequest->setCoverURL("http://xxxx.jpg");
  17. //$uploadVideoRequest->setTags('test1,test2');
  18. //$uploadVideoRequest->setStorageLocation('outin-xx.oss-cn-beijing.aliyuncs.com');
  19. //$uploadVideoRequest->setTemplateGroupId('6ae347b0140181ad371d197ebe289326');
  20. $userData = array(
  21. "MessageCallback"=>array("CallbackURL"=>"https://demo.sample.com/ProcessMessageCallback"),
  22. "Extend"=>array("localId"=>"xxx", "test"=>"www")
  23. );
  24. $uploadVideoRequest->setUserData(json_encode($userData));
  25. $res = $uploader->uploadLocalVideo($uploadVideoRequest);
  26. print_r($res);
  27. } catch (Exception $e) {
  28. printf("testUploadLocalVideo Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
  29. $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
  30. }
  31. }
  32. // Tests the upload of an online video.
  33. function testUploadWebVideo($accessKeyId, $accessKeySecret, $fileURL)
  34. {
  35. try {
  36. $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
  37. $uploadVideoRequest = new UploadVideoRequest($fileURL, 'testUploadWebVideo via PHP-SDK');
  38. $res = $uploader->uploadWebVideo($uploadVideoRequest);
  39. print_r($res);
  40. } catch (Exception $e) {
  41. printf("testUploadWebVideo Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
  42. $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
  43. }
  44. }
  45. // Tests the upload of a local M3U8 video.
  46. function testUploadLocalM3u8($accessKeyId, $accessKeySecret, $m3u8FilePath)
  47. {
  48. try {
  49. $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
  50. $uploadVideoRequest = new UploadVideoRequest($m3u8FilePath, 'testUploadLocalM3u8 via PHP-SDK');
  51. // Calls the method for parsing the .m3u8 playlist to obtain the URL list of parts. If the parsing result is incorrect, manually assemble the URL list of parts. By default, the part files and .m3u8 files are stored in the same directory.
  52. $sliceFiles = $uploader->parseM3u8File($m3u8FilePath);
  53. //print_r($sliceFiles);
  54. $res = $uploader->uploadLocalM3u8($uploadVideoRequest, $sliceFiles);
  55. print_r($res);
  56. } catch (Exception $e) {
  57. printf("testUploadLocalM3u8 Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
  58. $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
  59. }
  60. }
  61. // Tests the upload of an online M3U8 video.
  62. function testUploadWebM3u8($accessKeyId, $accessKeySecret, $m3u8FileUrl)
  63. {
  64. try {
  65. $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
  66. $uploadVideoRequest = new UploadVideoRequest($m3u8FileUrl, 'testUploadWebM3u8 via PHP-SDK');
  67. // Calls the method for parsing the .m3u8 playlist to obtain the URL list of parts. If the parsing result is incorrect, manually assemble the URL list of parts. By default, the part files and .m3u8 files are stored in the same directory.
  68. $sliceFileUrls = $uploader->parseM3u8File($m3u8FileUrl);
  69. //print_r($sliceFileUrls);
  70. $res = $uploader->uploadWebM3u8($uploadVideoRequest, $sliceFileUrls);
  71. print_r($res);
  72. } catch (Exception $e) {
  73. printf("testUploadWebM3u8 Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
  74. $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
  75. }
  76. }
  77. #### Runs the test code. ####
  78. $accessKeyId = '<AccessKeyId>';
  79. $accessKeySecret = '<AccessKeySecret>';
  80. //$localFilePath = 'C:\test\sample.mp4';
  81. $localFilePath = '/opt/video/sample.mp4';
  82. //testUploadLocalVideo($accessKeyId, $accessKeySecret, $localFilePath);
  83. $webFileURL = 'http://vod-test1.cn-shanghai.aliyuncs.com/b55b904bc612463b812990b7c8cc95c8/daa30814c0c340cf8199926f78aa5c0e-a0bc05ba62c3e95cc672e88b828148c9-ld.mp4?auth_key=1608774986-0-0-c56acd302bea0c331370d8ed686502fe';
  84. testUploadWebVideo($accessKeyId, $accessKeySecret, $webFileURL);
  85. $localM3u8FilePath = '/opt/video/m3u8/sample.m3u8';
  86. //testUploadLocalM3u8($accessKeyId, $accessKeySecret, $localM3u8FilePath);
  87. $webM3u8FileURL = 'http://vod-test1.cn-shanghai.aliyuncs.com/b55b904bc612463b812990b7c8cc95c8/daa30814c0c340cf8199926f78aa5c0e-195a25af366b5edae324c47e99a03f04-ld.m3u8?auth_key=1608775606-0-0-9fb038deaecd009dadd86721c5855629';
  88. //testUploadWebM3u8($accessKeyId, $accessKeySecret, $webM3u8FileURL);

For more sample code, see the samples directory in the decompressed VodUploadSDK-PHP directory.

FAQ

  • How can I upload media files to ApsaraVideo for VOD through the intranet?
    In the ApsaraVideo for VOD console, click Storage in the left-side navigation pane and view the storage region of your media assets. Deploy the upload script on the ECS instance in that region. After initializing the AliyunVodUploader class instance, call the setEcsRegionId method to set the region ID to that of the ECS region, such as cn-shanghai.

  • How can I obtain the upload progress?
    The uploadProgressCallback method that belongs to the AliyunVodUploader class is used to receive the callback for upload progress. You can obtain the ID of the uploaded media (video ID), size of uploaded parts, and total file size. You can override this method to customize the callback for upload progress.

  • How do I disable the logging service?
    The AliyunVodLog class in the AliyunVodUtils.php file provides the logging service. You can set $logSwitch to determine whether to enable the logging service. To disable the logging service, set $logSwitch to false.

  • Is the upload synchronous or asynchronous?
    PHP upload SDK supports synchronous upload only, which may block the corresponding process or thread. If you need asynchronous upload, we recommend that you use a separate thread to upload files.

  • Is resumable upload supported?
    Currently, PHP upload SDK does not support resumable upload. When you resume the upload of a video or an image, the downloaded parts of the video or image will be downloaded again. Resumable upload will be supported in the future.

  • Is PHP upload SDK supported on Windows?
    PHP upload SDK is supported on Linux, UNIX, Mac, and Windows. To use PHP upload SDK on these operating systems, you need to install PHP and required extensions, such as php-mbstring.

  • How can I handle disconnections?
    First, check whether you can connect to the Internet. You can ping vod.cn-shanghai.aliyuncs.com to check whether you can connect to the ApsaraVideo for VOD server. If the connection fails, check your network settings, such as whether you have the permission to access the Internet. Then, check whether SSL is enabled. If HTTPS requests are used, check whether required extensions, such as php_openssl, are properly installed, or whether the configuration is correct.