Merge pull request #42 from ivkos/v3

Version 3.0.0

Author: ivkos

.gitignore

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Ivaylo Stoyanov
+Copyright (c) 2013-2015 Ivaylo Stoyanov <[email protected]> - https://github.com/ivkos
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -1,13 +1,8 @@
-Pushbullet
-==========
+Pushbullet for PHP
+================
 
 ## Description
-Using this class, you can send push notifications to mobile and desktop devices running **Pushbullet**. The following types of push notifications can be sent:
-* notes
-* links
-* addresses
-* checklists
-* files (smaller than 25 MB)
+A PHP library for the **[Pushbullet](https://www.pushbullet.com)** API allowing you to send all supported push notification types, manage contacts, send SMS messages, create/delete channels, and manage channel subscriptions.
 
 For more information, you can refer to these links:
 * **Official website**: https://www.pushbullet.com
@@ -17,113 +12,222 @@ For more information, you can refer to these links:
 
 ## Requirements
 * PHP 5.4.0 or newer
+* Composer
 * cURL library for PHP
-* Your Pushbullet API key (get it here: https://www.pushbullet.com/account)
+* Your Pushbullet access token: https://www.pushbullet.com/account
 
 ## Install
-
-Via Composer:
+Create a `composer.json` file in your project root:
 
 ```json
 {
     "require": {
-        "ivkos/pushbullet": "2.*"
+        "ivkos/pushbullet": "3.*"
     }
 }
 ```
 
-## Examples
+## Quick Documentation
 
-For more detailed usage information, consult the PHPDoc of the methods.
+Add this line to include Composer packages:
 
 ```php
 <?php
+require 'vendor/autoload.php';
+```
 
-require __DIR__ . '/vendor/autoload.php';
-
-// If you don't use Composer, include the class like so:
-// require 'src/Pushbullet.php';
-
-try {
-  #### AUTHENTICATION ####
-  // Get your API key here: https://www.pushbullet.com/account
-  $p = new Pushbullet('YOUR_API_KEY');
+Initialize Pushbullet with your API key:
+```php
+// Get your access token here: https://www.pushbullet.com/account
+$pb = new Pushbullet\Pushbullet('YOUR_ACCESS_TOKEN');
+```
 
-  // If you get SSL errors while using the library, you may need to point cURL to a CA certificate bundle
-  $p->addCurlCallback(function ($curl) {
-    // Get a CA certificate bundle here:
+If you use PHP for Windows it *may* be necessary to point cURL to a CA certificate bundle, or disable SSL certificate verification altogether:
+```php
+Pushbullet\Connection::setCurlCallback(function ($curl) {
+	// Get a CA certificate bundle here:
     // https://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crt
-
     curl_setopt($curl, CURLOPT_CAINFO, 'C:/path/to/ca-bundle.crt');
 
-    // Alternatively, you can disable SSL certificate verification.
-    // However, this is a bad idea since it makes communication vulnerable to MITM attacks.
+	// Not recommended! Makes communication vulnerable to MITM attacks:
     // curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
-  });
-
-
-  #### Get methods
-
-  // Print the definitions for your own devices. Useful for getting the 'iden' for using with the push methods.
-  print_r($p->getDevices());
-
-  // Print the definitions for contacts/devices shared with you. Useful for getting 'iden', too.
-  print_r($p->getContacts());
-
-  // Print information about your Pushbullet account
-  print_r($p->getUserInformation());
-  
-  // Print a list of sent push notifications, modified after 1400441645 unix time
-  print_r($p->getPushHistory(1400441645));
-
-
-
-  #### Push methods
-  
-  // Push to email [email protected] a note with a title 'Hey!' and a body 'It works!'
-  $p->pushNote('[email protected]', 'Hey!', 'It works!');
-  
-  // Push to device s2GBpJqaq9IY5nx a note with a title 'Hey!' and a body 'It works!'
-  $p->pushNote('s2GBpJqaq9IY5nx', 'Hey!', 'It works!');
-  
-  // Push to device gXVZDd2hLY6TOB1 a link with a title 'ivkos at GitHub', a URL 'https://github.com/ivkos' and body 'Pretty useful.'
-  $p->pushLink('gXVZDd2hLY6TOB1', 'ivkos at GitHub', 'https://github.com/ivkos', 'Pretty useful.');
-
-  // Push to device a91kkT2jIICD4JH a Google Maps address with a name 'Google HQ' and an address '1600 Amphitheatre Parkway'
-  $p->pushAddress('a91kkT2jIICD4JH', 'Google HQ', '1600 Amphitheatre Parkway');
-
-  // Push to device qVNRhnXxZzJ95zz a to-do list with a title 'Shopping List' and items 'Milk' and 'Butter'
-  $p->pushList('qVNRhnXxZzJ95zz', 'Shopping List', array('Milk', 'Butter'));
-  
-  // Push to device 0PpyWzARDK0w6et the file '../pic.jpg' of MIME type image/jpeg
-  // Method accepts absolute and relative paths.
-  $p->pushFile('0PpyWzARDK0w6et', '../pic.jpg', 'image/jpeg');
-  // If the MIME type argument is omitted, an attempt to guess it will be made.
-  $p->pushFile('0PpyWzARDK0w6et', '../pic.jpg');
-  
-  
-  #### Pushing to multiple devices
-  
-  // Push to all of your own devices, if you set the first argument to NULL or an empty string
-  $p->pushNote(NULL, 'Some title', 'Some text');
-  $p->pushNote('', 'Some title', 'Some text');
-  
-  
-  
-  #### Delete methods
-  
-  // Delete the push notification with the 'iden' specified
-  $p->deletePush('a91kkT2jIICD4JH');
-  
-  // Delete the device with the 'iden' specified
-  $p->deleteDevice('s2GBpJqaq9IY5nx');
-  
-  // Delete the contact with the 'iden' specified
-  $p->deleteContact('0PpyWzARDK0w6et');
-} catch (PushbulletException $e) {
-  // Exception handling
-  die($e->getMessage());
+});
+```
+
+### Devices
+To list all active devices on your account:
+```php
+$pb->getDevices();
+```
+Returns an array of `Device` objects.
+
+----------
+
+You can target a particular device by using its `iden` or `nickname`:
+```php
+$pb->device("Galaxy S4")->getPhonebook();
+```
+Returns an array of `PhonebookEntry` objects with names and phone numbers.
+
+### Push Notifications
+You can use `push*` methods for `Contact`, `Channel` and `Device` objects. Every `push*` method returns a `Push` object. If an object cannot be pushed to, a `NotPushableException` will be thrown.
+
+#### Note
+Arguments:
+
+ - Title
+ - Body
+
+```php
+$pb->device("Galaxy S4")->pushNote("Hello world!", "Lorem ipsum...");
+```
+
+#### Link
+Arguments:
+
+- Title
+- URL
+- Body
+
+```php
+$pb->device("Galaxy S4")->pushLink("ivkos on GitHub", "https://github.com/ivkos", "Look at my page!");
+```
+
+#### Address
+Arguments:
+
+- Name - the place's name.
+- Address - the place's address or a map search query.
+
+```php
+$pb->device("Galaxy S4")->pushAddress("Google HQ", "1600 Amphitheatre Parkway");
+```
+
+#### List
+Arguments:
+
+- Title
+- Array of items in the list
+
+```php
+$pb->device("Galaxy S4")->pushList("Shopping List", [
+	"Milk",
+	"Butter",
+	"Eggs"
+]);
+```
+
+#### File
+Arguments:
+
+- File path
+- MIME type (optional) - if `null`, MIME type will be magically guessed
+- Title (optional)
+- Body (optional)
+- Alternative file name (optional) - push the file as if it had this file name
+
+```php
+$pb->device("Galaxy S4")->pushFile(
+	"/home/ivkos/photos/20150314_092653.jpg",
+	"image/jpeg",
+	"Look at this photo!",
+	"I think it's pretty cool",
+	"coolphoto.jpg"
+);
+```
+
+### SMS Messaging
+You can send SMS messages only from supported devices. If an attempt is made to send an SMS message from a device doesn't support it, a `NoSmsException` will be thrown.
+
+```php
+$pb->device("Galaxy S4")->sendSms("+359123", "Hello there!");
+```
+
+Send an SMS text to all people in a device's phonebook:
+```php
+$people = $pb->device("Galaxy S4")->getPhonebook();
+
+foreach ($people as $person) {
+	$person->sendSms("Happy New Year!");
 }
+```
+
+### Channel Management
+Get a list of channel subscriptions:
+```php
+$pb->getChannelSubscriptions();
+```
+Returns an array of `Channel` objects with subscription information.
+
+----------
+
+To subscribe or unsubscribe from channels:
+```php
+$pb->channel("greatchannel")->subscribe();
+$pb->channel("mehchannel")->unsubscribe();
+```
+Subscribing to a channel will return a `Channel` object with subscription information.
+
+----------
+
+Get a list of channels created by the current user:
+```php
+$pb->getMyChannels();
+```
+Returns an array of `Channel` objects.
+
+----------
+
+Create a channel named `mychannel`. If this channel tag is already registered, a `ChannelException` will be thrown.
+```php
+$pb->channel("mychannel")->create("My Channel", "This channel will only push awesome stuff!");
+```
+Returns a `Channel` object for the newly created channel.
+
+----------
+
+Delete a channel if you are its creator:
+```php
+$pb->channel("mychannel")->delete();
+```
+
+### Contact Management
+Contacts are people you can send push notification to. They are not to be confused with entries in a device's phonebook.
+
+To list contacts on your account:
+```php
+$pb->getContacts();
+```
+Returns an array of `Contact` objects.
+
+---
+
+To create a contact:
+```php
+$pb->createContact("John Doe", "[email protected]");
+```
+Returns a `Contact` object for the newly created contact.
+
+---
 
-?>
+You can target a particular contact by its email or name:
+```php
+$pb->contact("[email protected]")->pushNote("Hey John!", "Where are you?");
+```
+
+To delete a contact:
+```php
+$pb->contact("Caroline")->delete();
 ```
+
+To change a contact's name:
+```php
+$pb->contact("William")->changeName("Bill");
+```
+Returns a `Contact` object with an updated name.
+
+
+----------
+
+
+***For more detailed documentation, please refer to the PHPDoc in the source files.***

README.md

@@ -26,7 +26,7 @@
     },
     "autoload": {
         "psr-4": {
-            "": "src/"
+            "Pushbullet\\": "src/Pushbullet"
         }
     }
-}
+}