CakeSession improvements

lib/Cake/Model/Datasource/CakeSession.php

@@ -213,7 +213,7 @@ public static function started() {
  * @return boolean True if variable is there
  */
 	public static function check($name = null) {
-		if (!self::started() && !self::start()) {
+		if (!self::start()) {
 			return false;
 		}
 		if (empty($name)) {
@@ -223,9 +223,17 @@ public static function check($name = null) {
 	}
 
 /**
- * Returns the Session id
+ * Returns the session id.
+ * Calling this method will not auto start the session. You might have to manually
+ * assert a started session.
  *
- * @param string $id
+ * Passing an id into it, you can also replace the session id if the session
+ * has not already been started.
+ * Note that depending on the session handler, not all characters are allowed
+ * within the session id. For example, the file session handler only allows
+ * characters in the range a-z A-Z 0-9 , (comma) and - (minus).
+ *
+ * @param string $id Id to replace the current session id
  * @return string Session id
  */
 	public static function id($id = null) {
@@ -254,7 +262,7 @@ public static function delete($name) {
 	}
 
 /**
- * Used to write new data to _SESSION, since PHP doesn't like us setting the _SESSION var itself
+ * Used to write new data to _SESSION, since PHP doesn't like us setting the _SESSION var itself.
  *
  * @param array $old Set of old variables => values
  * @param array $new New set of variable => value
@@ -333,10 +341,10 @@ protected static function _validAgentAndTime() {
 	}
 
 /**
- * Get / Set the userAgent
+ * Get / Set the user agent
  *
- * @param string $userAgent Set the userAgent
- * @return void
+ * @param string $userAgent Set the user agent
+ * @return string Current user agent
  */
 	public static function userAgent($userAgent = null) {
 		if ($userAgent) {
@@ -355,7 +363,7 @@ public static function userAgent($userAgent = null) {
  * @return mixed The value of the session variable
  */
 	public static function read($name = null) {
-		if (!self::started() && !self::start()) {
+		if (!self::start()) {
 			return false;
 		}
 		if (is_null($name)) {
@@ -393,7 +401,7 @@ protected static function _returnSessionVars() {
  * @return boolean True if the write was successful, false if the write failed
  */
 	public static function write($name, $value = null) {
-		if (!self::started() && !self::start()) {
+		if (!self::start()) {
 			return false;
 		}
 		if (empty($name)) {
@@ -418,9 +426,7 @@ public static function write($name, $value = null) {
  * @return void
  */
 	public static function destroy() {
-		if (!self::started()) {
-			self::start();
-		}
+		self::start();
 		session_destroy();
 		self::clear();
 	}
@@ -620,7 +626,7 @@ protected static function _startSession() {
  * @return void
  */
 	protected static function _checkValid() {
-		if (!self::started() && !self::start()) {
+		if (!self::start()) {
 			self::$valid = false;
 			return false;
 		}