Improve docs

docs/README.md

@@ -72,22 +72,12 @@ The Tools plugin controller will allow you to:
 
 
 
-
 ### BC shims for easier migration from 2.x
-The session component of the core is deprecated and will throw a warning as it will soon be removed.
-Better use the plugin one right away. It is a 1:1 clone of it.
-```php
-namespace App\Controller;
-
-use Tools\Controller\Controller;
-
-class AppController extends Controller {
-
-	public $components = array('Tools.Session');
-
-}
-```
+It contains many shims to provide 2.x functionality when upgrading apps to 3.0.
+This eases migration as complete parts of the code, such as validation and other model property settings
+can be reused immediatelly without refactoring them right away.
 
+* See [Shims](Shims.md) for details.
 
 ## Testing the Plugin
 You can test using a local installation of phpunit or the phar version of it:

docs/Shims.md

@@ -0,0 +1,28 @@
+# Migration from 2.x to 3.x: Shims
+
+## Session
+The session component of the core is deprecated and will throw a warning as it will soon be removed.
+Better use the plugin one right away. It is a 1:1 clone of it.
+```php
+namespace App\Controller;
+
+use Tools\Controller\Controller;
+
+class AppController extends Controller {
+
+	public $components = array('Tools.Session');
+
+}
+```
+It also contains the new consume() method.
+
+## Model
+The following can be used in 3.x via shim support:
+
+### Used to be on models => now on tables
+- $order property
+- $validate property
+- relations (hasX, belongsTo)
+- $displayField
+- $primaryKey
+- Timestamp behavior added by default (if modified or created exists)

src/Controller/Component/SessionComponent.php

@@ -38,7 +38,6 @@ class SessionComponent extends Component {
 	 *    This should be in a Controller.key format for better organizing
 	 * @param string $value The value you want to store in a session.
 	 * @return void
-	 * @link http://book.cakephp.org/2.0/en/core-libraries/components/sessions.html#SessionComponent::write
 	 */
 	public function write($name, $value = null) {
 		$this->_session->write($name, $value);
@@ -52,20 +51,30 @@ class SessionComponent extends Component {
 	 *
 	 * @param string $name the name of the session key you want to read
 	 * @return mixed value from the session vars
-	 * @link http://book.cakephp.org/2.0/en/core-libraries/components/sessions.html#SessionComponent::read
 	 */
 	public function read($name = null) {
 		return $this->_session->read($name);
 	}
 
 	/**
+	 * Used to read and delete a session values for a key.
+	 *
+	 * In your controller: $this->Session->consume('Controller.sessKey');
+	 *
+	 * @param string $name the name of the session key you want to read
+	 * @return mixed value from the session vars
+	 */
+	public function consume($name) {
+		return $this->_session->consume($name);
+	}
+
+	/**
 	 * Wrapper for SessionComponent::del();
 	 *
 	 * In your controller: $this->Session->delete('Controller.sessKey');
 	 *
 	 * @param string $name the name of the session key you want to delete
 	 * @return void
-	 * @link http://book.cakephp.org/2.0/en/core-libraries/components/sessions.html#SessionComponent::delete
 	 */
 	public function delete($name) {
 		$this->_session->delete($name);
@@ -78,7 +87,6 @@ class SessionComponent extends Component {
 	 *
 	 * @param string $name the name of the session key you want to check
 	 * @return bool true is session variable is set, false if not
-	 * @link http://book.cakephp.org/2.0/en/core-libraries/components/sessions.html#SessionComponent::check
 	 */
 	public function check($name) {
 		return $this->_session->check($name);
@@ -101,7 +109,6 @@ class SessionComponent extends Component {
 	 * In your controller: $this->Session->destroy();
 	 *
 	 * @return void
-	 * @link http://book.cakephp.org/2.0/en/core-libraries/components/sessions.html#SessionComponent::destroy
 	 */
 	public function destroy() {
 		$this->_session->destroy();

src/Model/Table/Table.php

@@ -18,6 +18,9 @@ class Table extends CakeTable {
 	/**
 	 * initialize()
 	 *
+	 * All models will automatically get Timestamp behavior attached
+	 * if created or modified exists.
+	 *
 	 * @param mixed $config
 	 * @return void
 	 */
@@ -33,7 +36,9 @@ class Table extends CakeTable {
 
 		$this->prefixOrderProperty();
 
-		$this->addBehavior('Timestamp');
+		if ($this->hasField('created') || $this->hasField('modified')) {
+			$this->addBehavior('Timestamp');
+		}
 	}
 
 	/**

tests/Fixture/RolesFixture.php

@@ -17,7 +17,6 @@ class RolesFixture extends TestFixture {
 	public $fields = array(
 		'id' => ['type' => 'integer'],
 		'name' => ['type' => 'string', 'null' => false, 'length' => 64, 'collate' => 'utf8_unicode_ci', 'comment' => '', 'charset' => 'utf8'],
-		'description' => ['type' => 'string', 'null' => false, 'default' => null, 'collate' => 'utf8_unicode_ci', 'comment' => '', 'charset' => 'utf8'],
 		'alias' => ['type' => 'string', 'null' => false, 'default' => null, 'length' => 20, 'collate' => 'utf8_unicode_ci', 'comment' => '', 'charset' => 'utf8'],
 		'default_role' => ['type' => 'boolean', 'null' => false, 'default' => false, 'collate' => null, 'comment' => 'set at register'],
 		'created' => ['type' => 'datetime', 'null' => true, 'default' => null, 'collate' => null, 'comment' => ''],
@@ -36,7 +35,6 @@ class RolesFixture extends TestFixture {
 		array(
 			'id' => '2',
 			'name' => 'Admin',
-			'description' => 'Zuständig für die Verwaltung der Seite und Mitglieder, Ahndung von Missbrauch und CO',
 			'alias' => 'admin',
 			'default_role' => 0,
 			'created' => '2010-01-07 03:36:33',
@@ -47,7 +45,6 @@ class RolesFixture extends TestFixture {
 		array(
 			'id' => '4',
 			'name' => 'User',
-			'description' => 'Standardrolle jedes Mitglieds (ausreichend für die meisten Aktionen)',
 			'alias' => 'user',
 			'default_role' => 1,
 			'created' => '2010-01-07 03:36:33',
@@ -58,7 +55,6 @@ class RolesFixture extends TestFixture {
 		array(
 			'id' => '6',
 			'name' => 'Partner',
-			'description' => 'Partner',
 			'alias' => 'partner',
 			'default_role' => 0,
 			'created' => '2010-01-07 03:36:33',
@@ -69,7 +65,6 @@ class RolesFixture extends TestFixture {
 		array(
 			'id' => '1',
 			'name' => 'Super-Admin',
-			'description' => 'Zuständig für Programmierung, Sicherheit, Bugfixes, Hosting und CO',
 			'alias' => 'superadmin',
 			'default_role' => 0,
 			'created' => '2010-01-07 03:36:33',

tests/TestApp/Model/Table/RolesTable.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace TestApp\Model\Table;
+
+use Tools\Model\Table\Table;
+
+class RolesTable extends Table {
+}

tests/TestCase/Controller/Component/SessionComponentTest.php

@@ -99,6 +99,34 @@ class SessionComponentTest extends TestCase {
 	}
 
 /**
+ * Test consuming session data.
+ *
+ * @return void
+ */
+	public function testConsume() {
+		$Session = new SessionComponent($this->ComponentRegistry);
+
+		$Session->write('Some.string', 'value');
+		$Session->write('Some.array', ['key1' => 'value1', 'key2' => 'value2']);
+		$this->assertEquals('value', $Session->read('Some.string'));
+
+		$value = $Session->consume('Some.string');
+		$this->assertEquals('value', $value);
+		$this->assertFalse($Session->check('Some.string'));
+
+		$value = $Session->consume('');
+		$this->assertNull($value);
+
+		$value = $Session->consume(null);
+		$this->assertNull($value);
+
+		$value = $Session->consume('Some.array');
+		$expected = ['key1' => 'value1', 'key2' => 'value2'];
+		$this->assertEquals($expected, $value);
+		$this->assertFalse($Session->check('Some.array'));
+	}
+
+/**
  * testSessionDelete method
  *
  * @return void

tests/TestCase/Model/Table/TableTest.php

@@ -74,6 +74,19 @@ class TableTest extends TestCase {
 	}
 
 	/**
+	 * TableTest::testTimestamp()
+	 *
+	 * @return void
+	 */
+	public function testTimestamp() {
+		$this->Roles = TableRegistry::get('Roles');
+		$entity = $this->Roles->newEntity(['name' => 'Foo', 'alias' => 'foo']);
+		$result = $this->Roles->save($entity);
+		$this->assertTrue(!empty($result['created']));
+		$this->assertTrue(!empty($result['modified']));
+	}
+
+	/**
 	 * Check shims
 	 *
 	 * @return void
@@ -99,6 +112,11 @@ class TableTest extends TestCase {
 		$this->assertEquals(1, $result);
 	}
 
+	/**
+	 * TableTest::testField()
+	 *
+	 * @return void
+	 */
 	public function testField() {
 		$result = $this->Users->field('name', ['conditions' => ['name' => 'User 1']]);
 		$this->assertEquals('User 1', $result);