Services_Scribd
[ class tree: Services_Scribd ] [ index: Services_Scribd ] [ all elements ]

Source for file Docs.php

Documentation is available at Docs.php

  1. <?php
  2. /**
  3.  * Interface for Scribd's "docs" API endpoint.
  4.  *
  5.  * PHP version 5.2.0+
  6.  *
  7.  * LICENSE: This source file is subject to the New BSD license that is
  8.  * available through the world-wide-web at the following URI:
  9.  * http://www.opensource.org/licenses/bsd-license.php. If you did not receive
  10.  * a copy of the New BSD License and are unable to obtain it through the web,
  11.  * please send a note to license@php.net so we can mail you a copy immediately.
  12.  *
  13.  * @category  Services
  14.  * @package   Services_Scribd
  15.  * @author    Rich Schumacher <rich.schu@gmail.com>
  16.  * @copyright 2009 Rich Schumacher <rich.schu@gmail.com>
  17.  * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
  18.  * @version   Release: 0.2.0
  19.  * @link      http://pear.php.net/package/Services_Scribd
  20.  */
  21.  
  22. require_once 'Services/Scribd/Common.php';
  23.  
  24. /**
  25.  * The interface for the "docs" API endpoint.  Provides all interaction that
  26.  * is associated with a specific document or several documents, such as
  27.  * uploading, editing, etc.
  28.  *
  29.  * @category  Services
  30.  * @package   Services_Scribd
  31.  * @author    Rich Schumacher <rich.schu@gmail.com>
  32.  * @copyright 2009 Rich Schumacher <rich.schu@gmail.com>
  33.  * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
  34.  * @link      http://www.scribd.com/developers/platform/api
  35.  */
  36. {
  37.     /**
  38.      * Array of API endpoints that are supported
  39.      *
  40.      * @var array 
  41.      */
  42.     protected $validEndpoints = array(
  43.         'browse',
  44.         'changeSettings',
  45.         'delete',
  46.         'featured',
  47.         'getCategories',
  48.         'getConversionStatus',
  49.         'getDownloadUrl',
  50.         'getList',
  51.         'getSettings',
  52.         'getStats',
  53.         'search',
  54.         'upload',
  55.         'uploadFromUrl',
  56.         'uploadThumb',
  57.     );
  58.  
  59.     /**
  60.      * Supported document formats for uploading
  61.      *
  62.      * @link http://www.scribd.com/developers/platform/api/docs_upload
  63.      * @var array 
  64.      */
  65.     private $_validUploadDocTypes = array(
  66.         'pdf''txt''ps''rtf''epub''odt',
  67.         'odp''ods''odg''odf''sxw''sxc',
  68.         'sxi''sxd''doc''ppt''pps''xls',
  69.         'docx''pptx''ppsx''xlsx''tif''tiff'
  70.     );
  71.  
  72.     /**
  73.      * Supported document formats for downloading
  74.      *
  75.      * @link http://www.scribd.com/developers/platform/api/docs_getdownloadurl
  76.      * @var array 
  77.      */
  78.     private $_validDownloadDocTypes = array('pdf''txt''original');
  79.  
  80.     /**
  81.      * Returns a list of documents that meet filter criteria
  82.      *
  83.      * @param integer $limit      Number of results to return
  84.      * @param integer $offset     Number to start at
  85.      * @param integer $categoryId A category ID to search documents in
  86.      * @param string  $sort       Sort order, options are popular, views, newest
  87.      *
  88.      * @link http://www.scribd.com/developers/platform/api/docs_browse
  89.      * @return SimpleXMLElement 
  90.      */
  91.     public function browse($limit = 20$offset = 1$categoryId = null,
  92.         $sort 'popular'
  93.     {
  94.         $this->arguments['offset'$offset;
  95.         $this->arguments['limit']  $limit;
  96.         $this->arguments['sort']   $sort;
  97.  
  98.         if ($categoryId !== null{
  99.             $this->arguments['category_id'$categoryId;
  100.         }
  101.  
  102.         $response $this->call('docs.browse'HTTP_Request2::METHOD_GET);
  103.  
  104.         return $response->result_set;
  105.     }
  106.  
  107.     /**
  108.      * Changes metadata for one or many documents
  109.      *
  110.      * @param array $docIds   Array of document ids to modify
  111.      * @param array $settings Associative array of values to use
  112.      *
  113.      * @link http://www.scribd.com/developers/platform/api/docs_changesettings
  114.      * @return true 
  115.      */
  116.     public function changeSettings(array $docIdsarray $settings)
  117.     {
  118.         $validSettings = array(
  119.             'title',
  120.             'description',
  121.             'access',
  122.             'license',
  123.             'show_ads',
  124.             'link_back_url',
  125.             'tags',
  126.             'author',
  127.             'pubisher',
  128.             'when_published',
  129.             'edition'
  130.         );
  131.  
  132.         $docIds = implode(','$docIds);
  133.  
  134.         foreach ($settings as $key => $value{
  135.             if (!in_array($key$validSettings)) {
  136.                 unset($settings[$key]);
  137.             }
  138.         }
  139.  
  140.         $this->arguments            = $settings;
  141.         $this->arguments['doc_ids'$docIds;
  142.  
  143.         $response $this->call('docs.changeSettings'HTTP_Request2::METHOD_POST);
  144.  
  145.         return true;
  146.     }
  147.  
  148.     /**
  149.      * Deletes a document
  150.      *
  151.      * @param integer $docId The id of the document to delete
  152.      *
  153.      * @link http://www.scribd.com/developers/platform/api/docs_delete
  154.      * @return true 
  155.      */
  156.     public function delete($docId)
  157.     {
  158.         $this->arguments['doc_id'$docId;
  159.  
  160.         $this->call('docs.delete'HTTP_Request2::METHOD_POST);
  161.  
  162.         return true;
  163.     }
  164.  
  165.     /**
  166.      * Return a list of featured documents
  167.      *
  168.      * @param integer $limit  Max amount of results to return
  169.      * @param integer $offset Offset into the list of documents
  170.      * @param string  $scope  Whether to search new documents or hot only. Valid
  171.      *  scopes are "hot" and "new".
  172.      *
  173.      * @return SimpleXMLElement 
  174.      */
  175.     public function featured($limit = 20$offset = 0$scope "hot")
  176.     {
  177.         $this->arguments['limit']  $limit;
  178.         $this->arguments['offset'$offset;
  179.         $this->arguments['scope']  $scope;
  180.  
  181.         $response $this->call('docs.featured'HTTP_Request2::METHOD_GET);
  182.  
  183.         return $response->result_set;
  184.     }
  185.  
  186.     /**
  187.      * Fetch a list of categories
  188.      *
  189.      * @param integer $categoryId        The ID of category to retrieve children
  190.      *  for. If none - all root categories will be returned.
  191.      * @param boolean $withSubcategories Include subcategories in results
  192.      *
  193.      * @link http://www.scribd.com/developers/platform/api/docs_getcategories
  194.      * @return SimpleXMLElement 
  195.      */
  196.     public function getCategories($categoryId = null$withSubcategories = true)
  197.     {
  198.         $this->arguments['with_subcategories'$withSubcategories;
  199.  
  200.         if ($categoryId !== null{
  201.             $this->arguments['category_id'$categoryId;
  202.         }
  203.  
  204.         $response $this->call('docs.getCategories'HTTP_Request2::METHOD_GET);
  205.  
  206.         return $response->result_set;
  207.     }
  208.  
  209.     /**
  210.      * Retrieves the conversion status of a document
  211.      *
  212.      * @param integer $docId The id of document to check
  213.      *
  214.      * @link http://www.scribd.com/developers/platform/api/docs_getconversionstatus
  215.      * @return string 
  216.      */
  217.     public function getConversionStatus($docId)
  218.     {
  219.         $this->arguments['doc_id'$docId;
  220.  
  221.         $response $this->call('docs.getConversionStatus');
  222.  
  223.         return trim((string) $response->conversion_status);
  224.     }
  225.  
  226.     /**
  227.      * Gets a download URL for a particular document
  228.      *
  229.      * @param integer $docId   The id of the document
  230.      * @param string  $docType The format of the document
  231.      *
  232.      * @link http://www.scribd.com/developers/platform/api/docs_getdownloadurl
  233.      * @throws Services_Scribd_Exception
  234.      * @return string 
  235.      */
  236.     public function getDownloadUrl($docId$docType 'original')
  237.     {
  238.         if (!in_array($docType$this->_validDownloadDocTypes)) {
  239.             throw new Services_Scribd_Exception(
  240.                 'Invalid document type requested: ' $docType
  241.             );
  242.         }
  243.  
  244.         $this->arguments['doc_id']   $docId;
  245.         $this->arguments['doc_type'$docType;
  246.  
  247.         $response $this->call('docs.getDownloadUrl');
  248.  
  249.         return trim((string) $response->download_link);
  250.     }
  251.  
  252.     /**
  253.      * Revtrieves a list of documents owned by a user
  254.      *
  255.      * @param integer $limit         Max amount of results to return
  256.      * @param integer $offset        Offset into the list of documents
  257.      * @param boolean $useAPIAccount Show documents associated with the API
  258.      *  account, rather the Scribd user account
  259.      *
  260.      * @link http://www.scribd.com/developers/platform/api/docs_getlist
  261.      * @return array 
  262.      */
  263.     public function getList($limit = 10$offset = 0$useAPIAccount = false)
  264.     {
  265.         $this->arguments['limit']           $limit;
  266.         $this->arguments['offset']          $offset;
  267.         $this->arguments['use_api_account'$useAPIAccount;
  268.  
  269.         $response $this->call('docs.getList');
  270.         $response = (array) $response->resultset;
  271.  
  272.         return $response['result'];
  273.     }
  274.  
  275.     /**
  276.      * Gets metadata about a particular document
  277.      *
  278.      * @param integer $docId The id of the document
  279.      *
  280.      * @link http://www.scribd.com/developers/platform/api/docs_getsettings
  281.      * @return SimpleXMLElement 
  282.      */
  283.     public function getSettings($docId)
  284.     {
  285.         $this->arguments['doc_id'$docId;
  286.  
  287.         return $this->call('docs.getSettings');
  288.     }
  289.  
  290.     /**
  291.      * Retrieves statistics of a document
  292.      *
  293.      * @param integer $docId The id of the document
  294.      *
  295.      * @link http://www.scribd.com/developers/platform/api/docs_getstats
  296.      * @return SimpleXMLElement 
  297.      */
  298.     public function getStats($docId)
  299.     {
  300.         $this->arguments['doc_id'$docId;
  301.  
  302.         return $this->call('docs.getStats');
  303.     }
  304.  
  305.     /**
  306.      * Searches for the text string within Scribd documents
  307.      *
  308.      * @param string  $query      The text to search for
  309.      * @param integer $limit      The max number of results to return
  310.      * @param integer $offset     The number to start at
  311.      * @param integer $categoryId Restricts search results to this category
  312.      * @param string  $language   Restrict search results to this language
  313.      *  (ISO 639-1 format)
  314.      * @param boolean $simple     Use advanced search queries
  315.      *
  316.      * @link http://www.scribd.com/developers/platform/api/docs_search
  317.      * @throws Services_Scribd_Exception
  318.      * @return SimpleXMLElement 
  319.      */
  320.     public function search($query$limit = 10$offset = 1$categoryId = null,
  321.         $language = null$simple = true
  322.     {
  323.  
  324.         $this->arguments['query']       $query;
  325.         $this->arguments['num_results'$limit;
  326.         $this->arguments['num_start']   $offset;
  327.         $this->arguments['simple']      $simple;
  328.  
  329.         if ($categoryId !== null{
  330.             $this->arguments['category_id'$categoryId;
  331.         }
  332.  
  333.         $response $this->call('docs.search');
  334.  
  335.         return $response->result_set;
  336.     }
  337.  
  338.     /**
  339.      * Uploads and publishes a document from the filesystem
  340.      *
  341.      * @param string  $filepath    A path to the file we want to upload
  342.      * @param string  $docType     The type of document
  343.      * @param string  $access      Document Access {public, private}
  344.      * @param integer $paidContent Is this paid content? {0,1}
  345.      * @param integer $revisionId  The document id we are revising
  346.      *
  347.      * @link http://www.scribd.com/developers/platform/api/docs_upload
  348.      * @throws Services_Scribd_Exception
  349.      * @return SimpleXMLElement 
  350.      */
  351.     public function upload($filepath$docType$access 'public',
  352.         $paidContent = 0$revisionId = null
  353.     {
  354.         if (!in_array($docType$this->_validUploadDocTypes)) {
  355.             throw new Services_Scribd_Exception(
  356.                 'Invalid document type requested: ' $docType
  357.             );
  358.         }
  359.  
  360.         if (!file_exists($filepath)) {
  361.             throw new Services_Scribd_Exception(
  362.                 'The selected file was not found'
  363.             );
  364.         }
  365.  
  366.         $this->arguments['file']         $filepath;
  367.         $this->arguments['doc_type']     $docType;
  368.         $this->arguments['access']       $access;
  369.         $this->arguments['paid_content'$paidContent;
  370.         $this->arguments['rev_id']       $revisionId;
  371.  
  372.         $response $this->call('docs.upload'HTTP_Request2::METHOD_POST);
  373.  
  374.         unset($response['stat']);
  375.  
  376.         return $response;
  377.     }
  378.  
  379.     /**
  380.      * Uploads and publishes a document from a URL
  381.      *
  382.      * @param string  $url         The URL where the file is located
  383.      * @param string  $docType     The type of document
  384.      * @param string  $access      Document Access {public, private}
  385.      * @param integer $paidContent Is this paid content? {0,1}
  386.      * @param integer $revisionId  The document id we are revising
  387.      *
  388.      * @link http://www.scribd.com/developers/platform/api/docs_uploadfromurl
  389.      * @throws Services_Scribd_Exception
  390.      * @return SimpleXMLElement 
  391.      */
  392.     public function uploadFromUrl($url$docType$access 'public',
  393.         $paidContent = 0$revisionId = null
  394.     {
  395.         if (!in_array($docType$this->_validUploadDocTypes)) {
  396.             throw new Services_Scribd_Exception(
  397.                 'Invalid document type requested: ' $docType
  398.             );
  399.         }
  400.  
  401.         $this->arguments['url']          $url;
  402.         $this->arguments['doc_type']     $docType;
  403.         $this->arguments['access']       $access;
  404.         $this->arguments['paid_content'$paidContent;
  405.         $this->arguments['rev_id']       $revisionId;
  406.  
  407.         $response $this->call('docs.uploadFromUrl'HTTP_Request2::METHOD_POST);
  408.     
  409.         unset($response['stat']);
  410.  
  411.         return $response;
  412.     }
  413.  
  414.     /**
  415.      * XXX: This doesn't appear to be working; throwing 500's consistently.
  416.      *
  417.      * Uploads a thumbnail for a document
  418.      *
  419.      * @param string $filepath A path to the thumbnail we want to upload
  420.      * @param string $docId    The id of the document
  421.      *
  422.      * @link http://www.scribd.com/developers/platform/api/docs_uploadthumb
  423.      * @throws Services_Scribd_Exception
  424.      * @return boolean 
  425.      */
  426.     public function uploadThumb($filepath$docId)
  427.     {
  428.         if (!file_exists($filepath)) {
  429.             throw new Services_Scribd_Exception(
  430.                 'The selected file was not found'
  431.             );
  432.         }
  433.  
  434.         $this->arguments['file']   $filepath;
  435.         $this->arguments['doc_id'$docId;
  436.  
  437.         $response $this->call('docs.uploadThumb'HTTP_Request2::METHOD_POST);
  438.  
  439.         return (string) $response['stat'== "ok";
  440.     }
  441. }
  442.  
  443. ?>

Documentation generated on Sat, 06 Apr 2013 14:30:03 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.