modules/feed_node/aggregation_api.inc

<?php
/**
 * $Id: aggregation_api.inc,v 1.1 2006/12/18 23:45:57 dayre Exp $
 * Aggregation API
 * 
 * Drupal is a great aggregation platform. This is an attempt to 
 * create an API to allow unified access to shared aggregator 
 * functions - adding, updating and removing feeds, and querying 
 * existing feeds. 
 * 
 * Currently, this same file is also used in the feedfield project.
 * Once we achieve a more stable and functional API, online one
 * version will be used, and hopefully incorporated into other
 * aggregation related modules.
 * 
 */

/**
 * Phase 1: Create a set of functions to work with Aggregator. 
 * Phase 2: Create an extensible system of hooks to allow other modules to implement the API
 */

/**
 * Returns a valid feed ID for a feed which has the specified url and/or title. 
 * This function first checks to see if a feed with the given URL exists in the 
 * aggregator table.  If so, then an update is made to ensure that feed has the 
 * same title as the one specified (syncing on URL).  If no feed exists with 
 * the given URL, then a feed search is done by title.  If found, then the
 * feed is updated to ensure it has the same url as the one specified (sync on title).
 * If no feed exists with either the specified url or title, then a new aggregator
 * feed entry is made with the supplied values, and the new aggregator feed ID
 * is returned.
 * 
 * The purpose of this method is provide a quick method of editing the aggregator
 * feed information from within the feed node itself (a quick title or URL change,
 * or a complete new feed addition) so the user doesn't have to go to the aggregator
 * admin section.  
 * 
 * @param $title
 * @param $url
 * @return
 * 	 Returns the id for the corresponding aggregator feed in the database or
 *   -1 if a conflict exists with an existing feed in the database.
 */
function aggregation_sync_feed($title, $url) {
  
  // try to find a feed with the given URL
  $urlfeed   = aggregation_get_feed_by_url($url);
  $titlefeed = aggregation_get_feed_by_title($title);
  
  // if there is no feed with the given url or title, we have an insert
  if (!$urlfeed && !$titlefeed) {
    $newfeed['url']=$url;
 	  $newfeed['title']=$title;
 	  return _aggregation_insert_feed($newfeed);
  }
  // if a feed exists with the URL, but none with the given title,
  // we update the title
  else if ($urlfeed && !$titlefeed) {
    $urlfeed['title'] = $title;
    return _aggregation_update_feed($urlfeed);
  }
  // if a feed exists with the title, but none with the given url,
  // we update the url
  else if (!$urlfeed && $titlefeed) {
    $titlefeed['url'] = $url;
    return _aggregation_update_feed($titlefeed);
  }
  
	// if feeds exists with the given url and title and they are the same,
	// then there is nothing to update
	if ($urlfeed['fid'] == $titlefeed['fid']) {
	  return $urlfeed['fid'];
	}
   
	// else a feed exists with the given URL, and a different feed exists with
	// the given title, so we have a conflict the user must resolve
  return -1;

}


/**
 * Removes an aggregator feed and all associated aggregator feed items from
 * the database.  This function also removes pointers from the aggregator
 * category tables to the feed and feed items.
 * 
 * @param $fid
 */
function aggregation_delete_feed($fid) {
  if ($fid) {
    db_query('DELETE FROM {aggregator_category_feed} WHERE fid = %d', $fid);
    $result = db_query('SELECT iid FROM {aggregator_item} WHERE fid = %d', $fid);
    while ($item = db_fetch_object($result)) {
      $items[] = "iid = $item->iid";
    }
    if ($items) {
      db_query('DELETE FROM {aggregator_category_item} WHERE '. implode(' OR ', $items));
    }
    db_query('DELETE FROM {aggregator_feed} WHERE fid = %d', $fid);
    db_query('DELETE FROM {aggregator_item} WHERE fid = %d', $fid);
  }
}

/**
 * Remove all the items that belong to a feed
 *
 * @param $fid
 */
function aggregation_remove_feed_items($fid){
  aggregator_remove($fid);
}

//---------------- General feed identification functions
/**
 * Load a feed based on the url of the feed
 *
 * @param $url The feed url
 * @return 
 *   A feed array
 */
 function aggregation_get_feed_by_url($url) {
   if (!$url) return FALSE;
   return db_fetch_array(db_query("SELECT * FROM {aggregator_feed} WHERE url = '%s'", $url));
 }

/**
 * Load a feed based on it's id
 *
 * @param $fid Id of feed to load
 * @return
 *   An array of feed data
 */
 function aggregation_get_feed_by_id($fid) {
   return aggregator_get_feed($fid);
 }


/**
 * Returns a feed array (the first) for a feed with the specified title
 * 
 * @param $title
 * @return
 * 	 A array of aggregator feed information.
 */
 function aggregation_get_feed_by_title($title) {
   if (!$title) return FALSE;
   return db_fetch_array(db_query("SELECT * FROM {aggregator_feed} WHERE title = '%s'", $title));
 }


 //------------------- Aggregator category functions

/**
 * Assign categories to a specific feed 
 *
 * @param $fid Feed Id 
 * @param $categories An array of categories to assign  
 */
 function aggregation_set_feed_categories($fid,$categories){
   aggregation_clear_feed_categories($fid);
   if (is_array($categories)) {
     foreach ($categories as $cid) {
       if ($cid) db_query('INSERT INTO {aggregator_category_feed} (fid, cid) VALUES (%d, %d)', $fid, $cid);
     }
   }
 }

 /**
  * Remove all the categories assigned to a feed
  * 
  * @param $fid Feed Id
  */
 function aggregation_clear_feed_categories($fid){
   db_query('DELETE FROM {aggregator_category_feed} WHERE fid=%d', $fid);
 }
 
 
/**
 * Retrieve a list of categories assigned to a feed
 *
 * @param $fid 
 * @return 
 *   An array of category IDs
 */
 function aggregation_get_assigned_feed_categories($fid){
   $result=db_query('SELECT cid FROM {aggregator_category_feed} WHERE fid = %d', $fid);
   while($category=db_fetch_array($result)) {
     $values[]=$category[cid];
   }
   return $values;
 }


/**
 * Load all available feed categories
 * 
 * @return A list of options, Id as key, title as value 
 */
 function aggregation_get_all_feed_categories(){
   static $options;
   if (!$options) {
     // get aggregator categories
     $result = db_query('SELECT title, cid FROM {aggregator_category} ORDER BY title');
     while ($category = db_fetch_array($result)) {
      	$options[$category['cid']]=$category['title'];
     }
   }
  	return $options;
 }


 //=================================== Private Functions =================================//


/**
 * Insert a new feed. It is advised to use the sync_feed function rather than this function 
 * directly so as to make sure that no feeds are duplicated. 
 *
 * @param $feed An array of feed data
 * @return 
 *   A feed id for the inserted feed
 */
 function _aggregation_insert_feed($feed){
   $fid = db_next_id('{aggregator_feed}_fid');
   $feed['refresh'] or $feed['refresh']=3600;
   $feed['block_id'] or $feed['block_id']=5;
   db_query("INSERT INTO {aggregator_feed} (fid, title, url, refresh, block) VALUES (%d, '%s', '%s', %d, %d)",
   $fid,
   $feed['title'],
   $feed['url'],
   $feed['refresh'],
   $feed['block_id']);
   
   if (!db_error()) {
     drupal_set_message(t('A new aggregator feed "%title" was created', array('%title' => $feed['title'])));
   }
   else {
     drupal_set_message(t('A database error occured, no aggregator feed could be created.'), "error");
   }
   return $fid;
 }

/**
 * Update an existing feed. Do not call directly, use sync_feed
 *
 * @param array $feed An array containing the details of the feed to update
 * @return 
 *   A feed id for the updated feed
 */
 function _aggregation_update_feed($feed){
   $feed['refresh'] or $feed['refresh']=3600;
   db_query("UPDATE {aggregator_feed} SET title = '%s', url = '%s', refresh = %d WHERE fid = %d",
   $feed['title'],
   $feed['url'],
   $feed['refresh'],
   $feed['fid']);
   return $feed['fid'];
 }
?>
1	<?php
2	/**
3	* $Id: aggregation_api.inc,v 1.1 2006/12/18 23:45:57 dayre Exp $
4	* Aggregation API
5	*
6	* Drupal is a great aggregation platform. This is an attempt to
7	* create an API to allow unified access to shared aggregator
8	* functions - adding, updating and removing feeds, and querying
9	* existing feeds.
10	*
11	* Currently, this same file is also used in the feedfield project.
12	* Once we achieve a more stable and functional API, online one
13	* version will be used, and hopefully incorporated into other
14	* aggregation related modules.
15	*
16	*/
17
18	/**
19	* Phase 1: Create a set of functions to work with Aggregator.
20	* Phase 2: Create an extensible system of hooks to allow other modules to implement the API
21	*/
22
23	/**
24	* Returns a valid feed ID for a feed which has the specified url and/or title.
25	* This function first checks to see if a feed with the given URL exists in the
26	* aggregator table. If so, then an update is made to ensure that feed has the
27	* same title as the one specified (syncing on URL). If no feed exists with
28	* the given URL, then a feed search is done by title. If found, then the
29	* feed is updated to ensure it has the same url as the one specified (sync on title).
30	* If no feed exists with either the specified url or title, then a new aggregator
31	* feed entry is made with the supplied values, and the new aggregator feed ID
32	* is returned.
33	*
34	* The purpose of this method is provide a quick method of editing the aggregator
35	* feed information from within the feed node itself (a quick title or URL change,
36	* or a complete new feed addition) so the user doesn't have to go to the aggregator
37	* admin section.
38	*
39	* @param $title
40	* @param $url
41	* @return
42	* Returns the id for the corresponding aggregator feed in the database or
43	* -1 if a conflict exists with an existing feed in the database.
44	*/
45	function aggregation_sync_feed($title, $url) {
46
47	// try to find a feed with the given URL
48	$urlfeed = aggregation_get_feed_by_url($url);
49	$titlefeed = aggregation_get_feed_by_title($title);
50
51	// if there is no feed with the given url or title, we have an insert
52	if (!$urlfeed && !$titlefeed) {
53	$newfeed['url']=$url;
54	$newfeed['title']=$title;
55	return _aggregation_insert_feed($newfeed);
56	}
57	// if a feed exists with the URL, but none with the given title,
58	// we update the title
59	else if ($urlfeed && !$titlefeed) {
60	$urlfeed['title'] = $title;
61	return _aggregation_update_feed($urlfeed);
62	}
63	// if a feed exists with the title, but none with the given url,
64	// we update the url
65	else if (!$urlfeed && $titlefeed) {
66	$titlefeed['url'] = $url;
67	return _aggregation_update_feed($titlefeed);
68	}
69
70	// if feeds exists with the given url and title and they are the same,
71	// then there is nothing to update
72	if ($urlfeed['fid'] == $titlefeed['fid']) {
73	return $urlfeed['fid'];
74	}
75
76	// else a feed exists with the given URL, and a different feed exists with
77	// the given title, so we have a conflict the user must resolve
78	return -1;
79
80	}
81
82
83	/**
84	* Removes an aggregator feed and all associated aggregator feed items from
85	* the database. This function also removes pointers from the aggregator
86	* category tables to the feed and feed items.
87	*
88	* @param $fid
89	*/
90	function aggregation_delete_feed($fid) {
91	if ($fid) {
92	db_query('DELETE FROM {aggregator_category_feed} WHERE fid = %d', $fid);
93	$result = db_query('SELECT iid FROM {aggregator_item} WHERE fid = %d', $fid);
94	while ($item = db_fetch_object($result)) {
95	$items[] = "iid = $item->iid";
96	}
97	if ($items) {
98	db_query('DELETE FROM {aggregator_category_item} WHERE '. implode(' OR ', $items));
99	}
100	db_query('DELETE FROM {aggregator_feed} WHERE fid = %d', $fid);
101	db_query('DELETE FROM {aggregator_item} WHERE fid = %d', $fid);
102	}
103	}
104
105	/**
106	* Remove all the items that belong to a feed
107	*
108	* @param $fid
109	*/
110	function aggregation_remove_feed_items($fid){
111	aggregator_remove($fid);
112	}
113
114	//---------------- General feed identification functions
115	/**
116	* Load a feed based on the url of the feed
117	*
118	* @param $url The feed url
119	* @return
120	* A feed array
121	*/
122	function aggregation_get_feed_by_url($url) {
123	if (!$url) return FALSE;
124	return db_fetch_array(db_query("SELECT * FROM {aggregator_feed} WHERE url = '%s'", $url));
125	}
126
127	/**
128	* Load a feed based on it's id
129	*
130	* @param $fid Id of feed to load
131	* @return
132	* An array of feed data
133	*/
134	function aggregation_get_feed_by_id($fid) {
135	return aggregator_get_feed($fid);
136	}
137
138
139	/**
140	* Returns a feed array (the first) for a feed with the specified title
141	*
142	* @param $title
143	* @return
144	* A array of aggregator feed information.
145	*/
146	function aggregation_get_feed_by_title($title) {
147	if (!$title) return FALSE;
148	return db_fetch_array(db_query("SELECT * FROM {aggregator_feed} WHERE title = '%s'", $title));
149	}
150
151
152
153
154	//------------------- Aggregator category functions
155
156	/**
157	* Assign categories to a specific feed
158	*
159	* @param $fid Feed Id
160	* @param $categories An array of categories to assign
161	*/
162	function aggregation_set_feed_categories($fid,$categories){
163	aggregation_clear_feed_categories($fid);
164	if (is_array($categories)) {
165	foreach ($categories as $cid) {
166	if ($cid) db_query('INSERT INTO {aggregator_category_feed} (fid, cid) VALUES (%d, %d)', $fid, $cid);
167	}
168	}
169	}
170
171	/**
172	* Remove all the categories assigned to a feed
173	*
174	* @param $fid Feed Id
175	*/
176	function aggregation_clear_feed_categories($fid){
177	db_query('DELETE FROM {aggregator_category_feed} WHERE fid=%d', $fid);
178	}
179
180
181	/**
182	* Retrieve a list of categories assigned to a feed
183	*
184	* @param $fid
185	* @return
186	* An array of category IDs
187	*/
188	function aggregation_get_assigned_feed_categories($fid){
189	$result=db_query('SELECT cid FROM {aggregator_category_feed} WHERE fid = %d', $fid);
190	while($category=db_fetch_array($result)) {
191	$values[]=$category[cid];
192	}
193	return $values;
194	}
195
196
197	/**
198	* Load all available feed categories
199	*
200	* @return A list of options, Id as key, title as value
201	*/
202	function aggregation_get_all_feed_categories(){
203	static $options;
204	if (!$options) {
205	// get aggregator categories
206	$result = db_query('SELECT title, cid FROM {aggregator_category} ORDER BY title');
207	while ($category = db_fetch_array($result)) {
208	$options[$category['cid']]=$category['title'];
209	}
210	}
211	return $options;
212	}
213
214
215
216
217	//=================================== Private Functions =================================//
218
219
220
221
222	/**
223	* Insert a new feed. It is advised to use the sync_feed function rather than this function
224	* directly so as to make sure that no feeds are duplicated.
225	*
226	* @param $feed An array of feed data
227	* @return
228	* A feed id for the inserted feed
229	*/
230	function _aggregation_insert_feed($feed){
231	$fid = db_next_id('{aggregator_feed}_fid');
232	$feed['refresh'] or $feed['refresh']=3600;
233	$feed['block_id'] or $feed['block_id']=5;
234	db_query("INSERT INTO {aggregator_feed} (fid, title, url, refresh, block) VALUES (%d, '%s', '%s', %d, %d)",
235	$fid,
236	$feed['title'],
237	$feed['url'],
238	$feed['refresh'],
239	$feed['block_id']);
240
241	if (!db_error()) {
242	drupal_set_message(t('A new aggregator feed "%title" was created', array('%title' => $feed['title'])));
243	}
244	else {
245	drupal_set_message(t('A database error occured, no aggregator feed could be created.'), "error");
246	}
247	return $fid;
248	}
249
250	/**
251	* Update an existing feed. Do not call directly, use sync_feed
252	*
253	* @param array $feed An array containing the details of the feed to update
254	* @return
255	* A feed id for the updated feed
256	*/
257	function _aggregation_update_feed($feed){
258	$feed['refresh'] or $feed['refresh']=3600;
259	db_query("UPDATE {aggregator_feed} SET title = '%s', url = '%s', refresh = %d WHERE fid = %d",
260	$feed['title'],
261	$feed['url'],
262	$feed['refresh'],
263	$feed['fid']);
264	return $feed['fid'];
265	}
266	?>