Loads of new files added

Author: Swader

01-diffbot.rst

@@ -0,0 +1,68 @@
+.. API Abstract class
+   Added: September 8th, 2015
+   Author: Bruno Skvorc <[email protected]>
+
+============
+API Abstract
+============
+
+This page will describe the API Abstract class - the one which all the API classes extend to get some common functionality. Use this to build your own API class for custom APIs you defined in the Diffbot UI.
+
+.. php:namespace:: Swader\Diffbot\Abstracts
+
+.. php:class:: Api
+
+:hidden:`__construct`
+"""""""""""""""""""""""
+
+    .. php:method:: __construct($url)
+
+        This class takes a single argument during construction, the URL of the page to process. Alternatively, the argument can be "crawl", if the API is to be used in conjunction with the :php:class:`Swader\\Diffbot\\Api\\Crawl` API.
+
+        :param string $url: The URL of the page to process
+        :throws: InvalidArgumentException if the URL is invalid AND not the word "crawl"
+
+:hidden:`setTimeout`
+""""""""""""""""""""
+
+    .. php:method:: setTimeout($timeout = 30000)
+
+        Setting the timeout will define how long Diffbot will keep trying to fetch the API results. A timeout can happen for various reasons, from Diffbot's failure, to the site being crawled being exceptionally slow, and more.
+
+        :param int $timeout: Optional. The timeout, in milliseconds. Defaults to 30,000, a.k.a. 30 seconds
+        :returns: $this
+        :throws: InvalidArgumentException if the timeout value is invalid (negative or not an integer)
+
+        Usage::
+
+            $api->setTimeout(40000);
+
+:hidden:`call`
+""""""""""""""
+
+    .. php:method:: call()
+
+        When the API instance has been fully configured, this method executes the call.
+
+        :returns: \\Swader\\Diffbot\\Entity\\EntityIterator The return value will be an iterable collection of appropriate entities. Refer to each API's documentation for details on entites returned from each API call.
+
+        Usage::
+
+            $result = $api->call();
+            foreach ($result as $entity) { /* ... */ }
+
+
+:hidden:`buildUrl`
+""""""""""""""""""
+
+    .. php:method:: buildUrl()
+
+    This method is called automatically when :php:meth:`Swader\\Diffbot\\Abstracts\\Api::call` is called. It builds the URL which is to be called by the HTTPClient in :php:meth:`Swader\\Diffbot\\Diffbot::setHttpClient`, and returns it. This method can be used to get the URL for the purposes of testing in third party API clients like `Postman <https://www.getpostman.com/>`_.
+
+    :returns: string
+
+    Usage::
+
+        $api-> // ... set up API
+        $myUrl = $api->buildUrl();
+

_build/doctrees/01-diffbot.doctree

@@ -0,0 +1,69 @@
+.. Entity Abstract class
+   Added: September 20th, 2015
+   Author: Bruno Skvorc <[email protected]>
+
+===============
+Entity Abstract
+===============
+
+This page will describe the Entity Abstract class. This class is the root of all Entity classes. Entity classes are used as containers for return values from various API endpoints. For example, the Article API will return an Article Entity, the Discussion API will return a Discussion Entity, and so on.
+
+It is important to note that an API class will *never* return an Entity class directly. Rather, it will return an :php:class:`Swader\\Diffbot\\Entity\\EntityIterator`, an iterable container with all the Entities inside. The container, however, is configured in such a way that executing *get* methods on it directly will forward those calls to the first Entity in its dataset. Thus, in instances where
+
+.. php:namespace:: Swader\Diffbot\Abstracts
+
+.. php:class:: Entity
+
+:hidden:`__construct`
+"""""""""""""""""""""
+
+    .. php:method:: __construct(array $data)
+
+        This class takes a single argument during construction, an array of data. This data is then turned into gettable information by means of getters, both direct and magic. Some getters do additional processing of the data in order to make it more useful to the user.
+
+        :param array $data: The data
+
+:hidden:`getData`
+"""""""""""""""""
+
+    .. php:method:: getData()
+
+        Returns the raw data passed into the Entity by the parent API class. This will be an associative array (see Usage below).
+
+        :returns: array
+
+        Usage::
+
+            // ...
+
+            $data = $article->getData();
+
+            echo $data['title'];
+            echo $data['author'];
+
+            // etc.
+
+:hidden:`__call`
+""""""""""""""""
+
+    .. php:method:: __call()
+
+        Magic method for resolving undefined getters and only getters. If the method being called starts with ``get``, the remainder of its name will be turned into a key to search inside the `$data` property (see ``getData``). Once the call is identified as a *getter* call, ``__get`` is invoked (see below).
+
+        :returns: mixed
+        :throws: BadMethodCallException if the prefix of the method is not ``get``
+
+:hidden:`__get`
+"""""""""""""""
+
+    .. php:method:: __get()
+
+    This method is called automatically when ``__call`` is called. It looks for the property being asked for inside the ``$data`` property of the current class, or returns null if not found.
+
+    :returns: string
+
+    Usage::
+
+        $api-> // ... set up API
+        $myUrl = $api->buildUrl();
+

_build/doctrees/abstract-api.doctree

@@ -1,9 +1,88 @@
-.. Stub file
-   Added: September 7th, 2015
+.. Documentation of Analyze API
+   Added: September 25th, 2015
    Author: Bruno Skvorc <[email protected]>
 
 ===========
 Analyze API
 ===========
 
-Description goes here.
+This API is a sort of "catch all" for all other API types in that it automatically determines the type of content being processed, and applies the appropriate API call to it.
+
+This API will return entities matching the determined content type. For example, if you run Analyze API on a URL like ``www.sitepoint.com/quick-tip-get-homestead-vagrant-vm-running/``, the content type will be determined as "article" and it'll be exactly as if you had called the Article API (:php:class:`Swader\\Diffbot\\Api\\Article`) on it.
+
+Analyze API Class
+=================
+
+.. php:namespace:: Swader\Diffbot\Api
+
+.. php:class:: Analyze
+
+:hidden:`setDiscussion`
+"""""""""""""""""""""""
+
+    .. php:method:: setDiscussion($bool = true)
+
+        :param bool $bool: Either ``true`` or ``false``
+        :returns: $this
+
+        If set to false, will not extract article comments in a Discussion entity embedded in the Article / Product entity. By default, it will.
+
+:hidden:`setMode`
+"""""""""""""""""
+
+    .. php:method:: setMode($mode)
+
+        :param string $mode: "article", "product", "image" or "auto"
+        :returns: $this
+
+        By default the Analyze API will fully extract all pages that match an existing Automatic API -- articles, products or image pages. Set mode to a specific page-type (e.g., mode=article) to extract content only from that specific page-type. All other pages will simply return the default Analyze fields.
+
+Usage with defaults::
+
+    use Swader\Diffbot\Diffbot;
+
+    $url = "www.sitepoint.com/quick-tip-get-homestead-vagrant-vm-running/";
+
+    $diffbot = new Diffbot("my_token");
+    $api = $diffbot->createAnalyzeApi($url);
+
+    $result = $api->call();
+
+    echo $result->getAuthorUrl(); // "http://www.sitepoint.com/author/bskvorc/"
+
+    echo $result->getDiscussion()->getNumPosts(); // 7
+    echo $result->getDiscussion()->getProvider(); // Disqus
+
+Usage with discussion off::
+
+    use Swader\Diffbot\Diffbot;
+
+    $url = "www.sitepoint.com/quick-tip-get-homestead-vagrant-vm-running/";
+
+    $diffbot = new Diffbot("my_token");
+    $api = $diffbot->createAnalyzeApi($url);
+
+    $api->setDiscussion(false);
+    $result = $api->call();
+
+    echo $result->getAuthorUrl(); // "http://www.sitepoint.com/author/bskvorc/"
+
+    var_dump($result->getDiscussion()); // null
+
+Usage with non-matching mode::
+
+    use Swader\Diffbot\Diffbot;
+
+    $url = "www.sitepoint.com/quick-tip-get-homestead-vagrant-vm-running/";
+
+    $diffbot = new Diffbot("my_token");
+    $api = $diffbot->createAnalyzeApi($url);
+
+    $api->setMode("image");
+    $result = $api->call();
+
+    echo $result->getAuthorUrl(); // null
+    var_dump($result->getDiscussion()); // null
+
+
+In the last example above, no data is available due to a mismatch in mode - using image parsing on an article entity does not produce any useful information.