README

PHP版本的Soundcloud.com API包装器

实现的功能

• 用户授权/认证
• 用户凭证流认证
• 访问所有GET、PUT、POST和DELETE资源
• 媒体文件下载/上传

需求

PHP 5.6或更高版本。

安装

推荐通过composer进行安装。在您的composer.json文件中包含njasm\soundcloud。

{
    "require": {
        "njasm/soundcloud": "dev-master"
    }
}

如果您不使用composer来管理项目依赖项，此库提供了一个autoload.php。您只需将autoload.php包含到您的项目中，就可以像通过composer安装一样使用此库。

使用方法

在打算使用SoundcloudFacade或Soundcloud类的脚本中包含Njasm\Soundcloud\命名空间。

use Njasm\Soundcloud\SoundcloudFacade;
// or soundcloud if you don't need a facade for specific tasks
use Njasm\Soundcloud\Soundcloud;

SoundcloudFacade.php提供了一组模板代码，用于获取授权URL、将代码更改为令牌等。

示例

获取授权URL。

$facade = new SoundcloudFacade($clientID, $clientSecret, $callbackUri);
$url = $facade->getAuthUrl();

// or inject your specific request params
$url = $facade->getAuthUrl(
    [
        'response_type' => 'code',
        'scope' => '*',
        'state' => 'my_app_state_code'
    ]
);

认证

$facade = new SoundcloudFacade($clientID, $clientSecret, $callbackUri);
// this is your callbackUri script that will receive the $_GET['code']
$code = $_GET['code'];
$facade->codeForToken($code); 

使用用户凭证流进行认证。

如果从Soundcloud返回访问令牌，它将自动设置为未来请求。响应对象将始终返回给客户端。

$facade = new SoundcloudFacade($clientID, $clientSecret);
$facade->userCredentials($username, $password); // on success, access_token is set by default for next requests.
$response = $facade->get('/me')->request();
// raw/string body response
echo $response->bodyRaw();
// as object
echo $response->bodyObject()->id;
// as array
$array = $response->bodyArray();

接受json或xml格式的响应

注意：Soundcloud.com已停止发送xml格式的响应，这些方法保留在2.x.x版本中，但调用它们不会对请求产生影响，所有请求都将包含一个接受头部为application/json。

...
$response  = $facade->get('/tracks')->asJson()->request();
// or
$response = $facade->get('/tracks')->asXml()->request();

向资源添加参数。

// argument array style
$facade->get('/resolve', ['url' => 'http://www.soundcloud.com/hybrid-species']);

// chaining-methods
$response = $facade
    ->get('/resolve')
    ->setParams(['url' => 'http://www.soundcloud.com/hybrid-species']);

// or not
$facade->get('/resolve');
$facade->setParams(['url' => 'http://www.soundcloud.com/hybrid-species']);

发送请求

允许通过提交数组或使用setParams()方法注入设置要访问的资源参数的不同方式。只有在调用request()方法时，请求才会发送到Soundcloud。请考虑特定操作（如userCredentials()、download()等）将自动调用request()。

$soundcloud = new Soundcloud($clientID, $clientSecret);
$soundcloud->get('/resolve', ['url' => 'http://www.soundcloud.com/hybrid-species']);
// only this invocation will send the request
$response = $soundcloud->request();

获取原始响应体

...
$theBodyString = $facade->request()->bodyRaw();

创建播放列表/设置并更新曲目

// after having the access token
// build the playlist data array
$playlistData = ['playlist' => ['title' => 'Great Playlist!', 'sharing' => 'public']];
$response = $soundcloud->post('/playlists', $playlistData)->request();

// now add tracks, get playlist id from response
// build tracks array
$tracks = [
    'playlist' => [
        'tracks' => [
            ['id' => 29720509], // track id
            ['id' => 26057359]  // other track id
        ]
    ]
];

// put tracks into playlist
$response = $soundcloud->put('/playlists/' . $response->bodyObject()->id, $tracks)->request();

获取CURL最后一次响应对象

// if you want the CURL response object from last CURL request.
$response = $facade->getCurlResponse();

文件下载

// this will redirect user, sending a header Location to the track.
$response = $facade->download($trackID);
// redirect user to download URL suplied by soundcloud.
header('Loacation: ' . $response->getHeader('Location'));

// CAUTION: this will get the track into an in-memory variable in your server.
$response = $facade->download($trackID, true);
// save it to a file.
file_put_contents("great_track.mp3", $response->bodyRaw());

文件上传

$trackPath = '/home/njasm/great.mp3';
$trackData = [
    'title' => 'Cool track title',
    'downloadable' => true,
    'artwork_data' => new \CURLFile('artwork.jpg'),
    // .... more metadata maybe?
];

$response = $facade->upload($trackPath, $trackData);

// or old-school trackdata array declaration also work, example.
$trackData = [
    'track[title]' => 'Cool track title',
    'track[downloadable]' => true,
    'track[artwork_data]' => new \CURLFile('artwork.jpg'),
    // .... more metadata maybe?
];

$response = $facade->upload($trackPath, $trackData);