Index: lib/weblib.php
===================================================================
RCS file: /cvsroot/moodle/moodle/lib/weblib.php,v
retrieving revision 1.1344
diff -u -r1.1344 weblib.php
--- lib/weblib.php	13 Oct 2009 06:45:38 -0000	1.1344
+++ lib/weblib.php	5 Nov 2009 17:12:46 -0000
@@ -587,14 +587,37 @@
 }
 
 /**
+ * Reports whether the current request is a HTTP POST request.
+ * Normally, you should use {@link is_post_with_sesskey()} insead of this
+ * function, since it also checks that the sesskey is valid.
+ * @return boolean
+ */
+function is_post_request() {
+    return array_key_exists('REQUEST_METHOD', $_SERVER) &&
+            $_SERVER['REQUEST_METHOD'] == 'POST';
+}
+
+/**
+ * Reports whether the current request is a HTTP POST request that includes a
+ * valid sesskey.
+ * @return boolean
+ */
+function is_post_with_sesskey() {
+    return is_post_request() && confirm_sesskey();
+}
+
+/**
  * Determine if there is data waiting to be processed from a form
  *
- * Used on most forms in Moodle to check for data
- * Returns the data as an object, if it's found.
- * This object can be used in foreach loops without
- * casting because it's cast to (array) automatically
+ * This funciton may be deprecated at some piont. Please consider using one of
+ * these alternatives:
+ *  1. If you are dealing with a HTML form, use a {@link moodleform}.
+ *  2. If you just want to know whether this was a HTTP POST request,
+ *     use {@link is_post_with_sesskey()}.
+ *  3. If you want to get data submitted by the user, use
+ *     {@link required_param()} or {@link optional_param()}.
  *
- * Checks that submitted POST data exists and returns it as object.
+ * Returns the $_POST as an object, if it is an object, otherwise returns false.
  *
  * @uses $_POST
  * @return mixed false or object