New Version Of The Ning API PHP Library Now Live

[Ben Plowman]

I’ve just finished pushing some exciting changes to our PHP client over at our github project. Below are some of the highlights.

Simplified Tokens

In the previous version of the PHP client, you were forced to generate your own tokens and then pass in 4 tokens and a subdomain the the NingApi() constructor. This was cumbersome and unintuitive, so the constructor has been simplified.

Now, you can define only the default attributes in the NingApi.php file like this:

// Ning network subdomain (ie. 'apiexample' in apiexample.ning.com)
public $subdomain = '';
// Ning user email address
protected $email = '';
// Ning user password
protected $password = '';
// Consumer key found at [subdomain].ning.com/main/extend/keys
protected $consumerKey = '';
// Consumer secret found at [subdomain].ning.com/main/extend/keys
protected $consumerSecret = '';


After filling out those values, you can create a NingAPI object like this:

$ningApi = new NingApi();

And that’s it! Nothing else to pass in (unless you want to). All the request tokens are generated behind the scenes.

If you want to change consumer tokens, user information, or subdomain during execution, you can leave the NingApi.php file alone and just use one of these methods:

$ningApi->setSubdomain(‘apiexample’);
$ningApi->login(‘email’,’password’);
$ningApi->setConsumerTokens(‘consumerKey’,’consumerSecret’);

Expanded, Content-Aware Functionality

Another weakness of the previous version of the API was that it was hard to discover what was possible to do with the API. This has been bulked up so that there are content types within the NingApi object which have a set of actions you can perform for that content type.

Here is a screenshot from my IDE:

Here are all the content types available:

$ningApi->activityItem
$ningApi->blogPost
$ningApi->broadcastMessage
$ningApi->comment
$ningApi->network
$ningApi->photo
$ningApi->user
$ningApi->video

The argument array structure is the same as in the previous version. For example, to create a new Blog Post on the network, you would do this:

$args['description'] = "Test blog post description.";
$args['title'] = "Test blog post title.";
$ningApi->blogPost->create($args);


And you’re done! All the functionality is there. You can use fetch() to get a content object, delete() to delete one, update(), create(), etc., are all there.

Singleton Access

If you so choose, you can save yourself having to create the NingApi() object, by using it as a singleton. To create that blog post above, all you would need to call is this:

NingApi::instance()->blogPost->create($args);


This method works easiest if you declare everything in the NingApi.php file, otherwise you will have to initialize your access credentials in the same request using things like this:

NingApi::instance()->setSubdomain(‘subdomain’);

Backwards Compatibility Note

In order to move forward with abstracting tokens, the constructor does not allow the same arguments as it did previously, breaking its backwards compatibility.

Where before the NingApi() constructor looked like this: __construct($subdomain, $consumerKey, $consumerSecret, $accessToken = NULL, $accessTokenSecret = NULL)


It now looks like this:

__construct($subdomain=null, $consumerKey=null, $consumerSecret=null, $email=null, $password=null)


All other methods, e.g. $ningApi->post(), are the same as before and should still work.

Let me know if you see bugs

Everything is pretty well unit-tested, but let me know if you see stuff that does not work or is not backwards compatible as expected.

If you have ideas for further enhancements, I’d love to hear those as well!

-Ben

[Pierre Lannoy]

Hi Ben !

 

Thanks for this update. It's more powerfull like that.

Just a (potential) issue that frightens me : how can i get "author" field (screen name) now?

 

Pierre

[Pierre Lannoy]

Oh, please Ben, tell me it's me who does not understand anything and that I can still request screen name ...

[Ben Plowman]

Hi Pierre,

 

You are still able to get the author field from from all content. For fetching users, the call looks like this: NingApi::instance()->user->fetch($args);

 

You still have to specify a selection criteria, e.g. $args['id'] = '1234:User:678', but then by default the author field should be returned.

 

All of the methods still allow you to pass an arguments array that is identical to what you would pass to the NingApi in the previous version. If you'd like only a subset of possible fields, then you can set $args['fields'] to be the comma-separated list like you would in the previous api library version.

 

Sorry to scare you like that! There shouldn't be anything you cannot do with this new library version that you could with the previous, but let me know if you find otherwise.

 

-Ben

[Pierre Lannoy]

Hi ben.

 

And thanks for this precision. I confess I am a bit lost in the reingeniering of my code.

If I do that, it throw an exception (Missing one or more of the following required constants in /xxx/NingApi.php: subdomain, email, password, consumerKey, consumerSecret) on the second line :

$ningApi = new NingApi($subdomain, $ckey, $csecret, $name, $pass);

 $ningApi->user->fetch($args);

What am I doing wrong ?

 

Pierre

[Ben Plowman]

Hi Pierre,

 

Sorry about that - that's definitely a bug. Thanks for pointing it out. I just pushed a fix for this to github, but please let me know if you see any more problems.

 

-Ben

[Chris]

This is great, thank you! Is this likely to be updated at any point? What are all the extra fields in the user, and how do I populate them?

 

Thanks :)

[Vincent]

H,

 

The curl connection is returning the #7 error number.

I think its because my offices use a proxy so it might be blocking the connection somehow.

do you have any idea how i can fix this.

 

I did try adding this code below the $ch = curl_init(); line of the call method.

 

curl_setopt($ch, CURLOPT_TIMEOUT, self::CURL_TIMEOUT);

curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, TRUE);

curl_setopt($ch, CURLOPT_PROXY, "proxy_address");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

curl_setopt($ch, CURLOPT_URL, "my network address");

 

Any help is appreciated thanks in advance.