SDK for the latest Wunderlist API version.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
.gitignore
LICENSE
README.md
composer.json
composer.lock

README.md

Use the latest Wunderlist API version in your apps.

Latest Stable Version Total Downloads License Endpoint coverage

http://johnrivs.github.io/wunderlist

How to use?

Register your app

First of all, you need to register your app. To do that, go here, log in and click on the blue button that says 'CREATE APP'. Wunderlist will ask you about the name of the app, the description, an icon to represent the app, the URL where it is located and the callback URL for authorization.

If your app is not yet hosted on the Internet, set both the URL fields to http://localhost. You're only going to need a 'real' auth callback url when you need to set up authorization (more about this later).

Install the package

This package may be installed through Composer:

composer require johnrivs/wunderlist

If you're using a framework, everything in your vendor directory is most likely autoloaded for you. Otherwise, pull in the file yourself:

<?php

require_once __DIR__.'/path/to/vendor/autoload.php';
Build up the client

Go back to apps page and copy your app's 'CLIENT ID', 'CLIENT SECRET' and access token, which you can generate by clicking on 'CREATE ACCESS TOKEN':

<?php 

use JohnRivs\Wunderlist\Wunderlist;

$clientId     = 'THE_CLIENT_ID';
$clientSecret = 'THE_CLIENT_SECRET';
$accessToken  = 'THE_ACCESS_TOKEN';

$w = new Wunderlist($clientId, $clientSecret, $accessToken);

$w->getCurrentUser();

You can optionally pass a boolean as the 4th parameter that decides whether or not the package should throw exceptions when a required parameter is missing. By default, it does.

Authorization

For some methods (mostly the ones where you need to write, update or delete data), you're going to need a user access token. Up until this point you've only had the app access token, which you can use for yourself.

First, redirect the user to Wunderlist, where they need to grant access to your app. Wunderlist needs 2 things: a random string passed to it and the callback URL. Make sure you temporarily save said random string (in a file or session):

$state = md5(time());

// Store the $state to retrieve it later

// Redirect the user to:
$w->authUrl($state, 'http://your-domain.com/auth/callback')

Note: the URL you provide must be the same you set as your app auth callback url.

If you're working locally, I recommend using ngrok:

  • Spin up an HTTP server. In PHP via terminal php -S localhost:8000
  • Create the tunnel: ngrok http localhost:8000. It'll tell you where your website is publicly available, something like http://96d15c39.ngrok.io
  • Go to the apps page and set the auth callback url to http://96d15c39.ngrok.io/auth/callback or whatever you got.
  • Use the same URL in your code: $w->authUrl($state, 'http://96d15c39.ngrok.io/auth/callback')

Ngrok gives you a different URL everytime you create the tunnel, so you'll need to update the auth callback url for your app and the one you provide to authUrl().

Once the user grants access to your app, he's going to be redirected to the callback URL carrying a code and the state. It would look like http://96d15c39.ngrok.io/auth/callback?code=random_string&state=the_state_from_the_previous_step. Now retrieve the $state from earlier and compare it to $_GET['state']. If they're the same:

$accessToken = $w->getAuthToken($_GET['code']);

And that's the user's access token.

FAQ

What exactly is this pacakage?

This package is a wrapper for each endpoint in the Wunderlist API. To know what attributes you need to provide to each method, the data it returns or what status code is set, head over to the official Wunderlist API documentation.

How flexible is this package?

Since this package doesn't perform validation or sanitization, you can provide any attribute to (almost) every method. However, it'll check if the attributes contain the fields required by the endpoint. If you provide unrecognized attribute fields, they will be ignored. Again, to know what fields should be present in the attributes for a Wunderlist API endpoint, have a look at the official Wunderlist API documentation.

What should I expect from the Wunderlist API?

Most of the time, the methods will return an array containing the results of what you just did. For example, if you createTask(), it will return the task that was just created. Some methods (such as deleteTask()) will return a status code. You can always use getStatusCode() regardless of what the method returned.

How does it look like?

Almost each method maps to a Wunderlist API endpoint:

// Get all tasks for a given list
$wunderlist->getTasks(['list_id' => 9876]);

// Get all lists
$wunderlist->getLists();
How do I provide data?

For most methods you'll need to provide an array of attributes, however, for certain ones you'll need to supply some value(s). Check the API Docs out to know what each method expects.

Why do some methods take more time than others?

Due to the nature of the service, Wunderlist requires to keep everything in sync by providing the entity's revision. To achieve this, methods responsible for updating entities (such as tasks, lists...) will fetch the entity first and then perform a request to apply the changes.

Why does it say Forbidden during authentication?

Make sure the auth callback URL you provide to authUrl() matches the one you have for your app.

What if something goes wrong?

Well.. at the time of this writing, the Wunderlist API isn't too helpful when it comes to error messages, so make sure you stick to the docs, use getStatusCode() and ask any questions in the docs comment section.

Progress

  • Reminder
    • Get all reminders
    • Create a reminder
    • Update a reminder
    • Delete a reminder
  • Some other endpoints (not started)
  • Laravel integration
  • Silex integration

Finished:

  • Authorization
  • Avatar
  • File
  • Folder
  • Lists
  • Note
  • Subtask
  • Task
  • Comment
  • User (except restricting the list of users a user can access by list)
  • Webhook