PageRenderTime 25ms CodeModel.GetById 9ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 0ms

/external/podio-php/README.markdown

https://github.com/fabianmu/shodio
Markdown | 95 lines | 63 code | 32 blank | 0 comment | 0 complexity | c8b32ecc6c320cb142e49c53e349a5d9 MD5 | raw file
 1# About
 2This is a PHP Client for interacting with the Podio API. Almost all parts of the Podio API is covered in this client. To get started include PodioAPI.php in your script:
 3
 4    require_once('/path/to/podio-php/PodioAPI.php');
 5
 6# Dependencies
 7The Podio PHP client depends on two PEAR Packages:
 8
 9* HTTP\_Request2: [http://pear.php.net/package/HTTP_Request2/](http://pear.php.net/package/HTTP_Request2/)
10* Log: [http://pear.php.net/package/Log/](http://pear.php.net/package/Log/)
11
12Both must be present in your PHP include path. If you have PEAR installed you can install these packages using the "pear install" command.
13
14# Constructing API client instance and authentication
15You will working with three classes:
16
17* **PodioOAuth:** Handles authentication with the API server and holds your OAuth tokens.
18* **PodioAPI:** Handles all communication with the API server. This is where you will spend most of your time.
19* **PodioBaseAPI:** A base class, you need to create an instance of this to hold your API credentials.
20
21Before you can make any API calls you need to obtain an OAuth access token. You do this by creating instances of `PodioBaseAPI` and `PodioOAuth` and call the `getAccessToken` method:
22
23    require_once('/path/to/podio-php/PodioAPI.php');
24    $oauth = PodioOAuth::instance();
25    $baseAPI = PodioBaseAPI::instance($server, $client_id, $client_secret, $upload_end_point);
26    
27    // Obtain access token
28    $oauth->getAccessToken('password', array('username' => $username, 'password' => $password));
29    
30    print $oauth->access_token; // Your access token
31    
32    // Woohoo! Now it's time to make API calls!
33
34# Making API calls
35To make API calls you use the `PodioAPI` class. This is contains references to all areas of the Podio API. See each area to see individual methods and their arguments.
36
37For example: If I want to post a new status message _'Posted from the PHP Client'_ to a space I would call the `create` method in the `status` area like so:
38
39    $api = new PodioAPI();
40    
41    // $space_id is the id for the space I want to post the status message on
42    $response = $api->status->create($space_id, 'Posted from the PHP Client');
43    
44    if ($response) {
45      print 'The id for the status message is: '.$response['status_id'];
46    }
47
48The Podio API always returns data in JSON and the PHP client automatically decodes this and places responses into associative arrays for easy traversal.
49
50# Handling file uploads
51If you wish to upload a file, for example to status messages, comments, items, widgets etc., you will use the `upload` method in the `api` area:
52
53    $response = $api->api->upload($path_to_file, $filename_to_display);
54    
55    if ($response) {
56      print 'File uploaded. The file id is: '.$response['result']['file_id'];
57    }
58
59# Logging
60By default all logging happens in the PHP error log. You can overwrite this behaviour with the `setLogHandler` method on the `PodioBaseAPI` class. For example, you can log to a specific file:
61
62    $baseAPI->setLogHandler('file', '/path/to/log/file/podio_log.log');
63
64You can see which log handlers are available in the [PEAR Log documentation](http://www.indelible.org/php/Log/guide.html).
65
66# API reference
67The PHP Client is documented using Doxygen. For your convenience a Doxygen configuration file has been included in the repository. To generate an API reference:
68
69* Install Doxygen if you haven't: [http://doxygen.org/](http://doxygen.org/)
70* Navigate to the podio-php folder and run `doxygen .doxygen`
71* The API reference will now be available in the `docs` folder
72
73# Full example: Posting status message with an image
74    require_once('/path/to/podio-php/PodioAPI.php');
75    
76    $server = 'https://api.podio.com:443';
77    $client_id = 'MY_OAUTH_CLIENT_ID';
78    $client_secret = 'MY_OAUTH_CLIENT_SECRET';
79    $upload_end_point = 'https://upload.podio.com/upload.php';
80
81    $oauth = PodioOAuth::instance();
82    $baseAPI = PodioBaseAPI::instance($server, $client_id, $client_secret, $upload_end_point);
83    
84    // Obtain access token
85    $username = 'MY_USERNAME';
86    $password = 'MY_PASSWORD';
87    $oauth->getAccessToken('password', array('username' => $username, 'password' => $password));
88    
89    // Upload file
90    $file = $api->api->upload('/path/to/myimage.png', 'myimage.png');
91    
92    // Post status message
93    $space_id = MY_SPACE_ID;
94    $api->status->create($space_id, 'This has an image attached', array((int)$file['result']['file_id']));
95