Docs

Controller/Component/AjaxComponent.php

@@ -11,6 +11,9 @@ App::uses('Component', 'Controller');
  * It will also avoid redirects and pass those down as content
  * of the JSON response object.
  *
+ * Don't forget Configure::write('Ajax.flashKey', 'messages');
+ * if you want to use it with Tools.Flash component.
+ *
  * @author Mark Scherer
  * @license http://opensource.org/licenses/mit-license.php MIT
  */
@@ -25,7 +28,7 @@ class AjaxComponent extends Component {
 	protected $_defaultConfig = array(
 		'autoDetect' => true,
 		'resolveRedirect' => true,
-		'flashKey' => 'Message.flash' // Use "messages" for Tools plugin, set to false to disable
+		'flashKey' => 'Message.flash' // Use "messages" for Tools plugin Flash component, set to false to disable
 	);
 
 	/**

README.md

@@ -120,7 +120,8 @@ public $helpers = array(
 * Disable cache also works for older IE versions.
 * Default settings for Paginator, ... can be set using Configure.
 * RSS and Ajax Views for better responses (Ajax also comes with an optional component).
-* testAction() defaults to GET
+* testAction() defaults to GET.
+* [Shims](docs/Shims.md) to write cutting edge 2.x code - and prepare for 3.x.
 
 A full list of fixes and useful migration tweaks towards the next major version see [here](https://github.com/dereuromark/cakephp-tools/wiki/Included-fixes-and-migration-tweaks).
 
@@ -154,7 +155,7 @@ If you are able to help on that one, that would be awesome.
 
 ### Branching strategy
 The master branch is the currently active and maintained one and works with the current 2.x stable version.
-Older versions might be found in their respective branches (1.3, 2.0, 2.3, ...).
+Older versions might be found in their respective branches (2.0, 2.4, ...).
 Please provide PRs mainly against master branch then.
 
 For details on how to contribute please read the [CONTRIBUTING page](CONTRIBUTING.md).
@@ -166,9 +167,7 @@ For details on how to contribute please read the [CONTRIBUTING page](CONTRIBUTIN
 
 ### Recent changes (possibly BC breaking)
 
-* 2014-01 Changed Garbige to Garbage in method names.
-* 2014-02 Qlogin now uses Token model instead of deprecated CodeKey per default.
 * 2014-07 Packagist package name has been renamed to "cakephp-tools".
 * 2014-11 All translations now use the `tools` domain; development messages are not translated anymore
 * 2014-12 Some model validations have also been transformed from generic `validation` into `tools` domain.
-* 2014-12 All `tools` domain translations need to exist in `APP/Locale` due to a core issue when trying to overwrite them in the application.
+* 2014-12 All `tools` domain translations need to exist in `APP/Locale` due to a core issue in `CakePHP <= 2.5` when trying to overwrite them in the application.

docs/Shims.md

@@ -0,0 +1,66 @@
+## Shims and CO
+Write cutting edge 2.x code - and prepare for 3.x.
+
+### Write smart (future aware) code
+- Drop deprecated stuff early.
+- Upgrade to new ways as soon as possible and while it's still easy to do so (minor changes well testable).
+- Use the current 2.x version and all the new syntax of it (You can leverage the Upgrade shell to automate necessary changes).
+
+See [Tips-Upgrading-to-CakePHP-2.x](https://github.com/dereuromark/cakephp-upgrade/wiki/Tips-Upgrading-to-CakePHP-2.x) and
+the plugin in general.
+
+### Assert query strings througout the project
+Don't use named params anywhere, they will be gone in 3.x anyway.
+
+Default settings for Paginator, ... can be set using Configure:
+```php
+$config['Paginator'] = array(
+	'paramType' => 'querystring'
+);
+```
+Just make sure, that your AppController extends the `Tools.MyController` class.
+
+You can also set `Configure::write('App.warnAboutNamedParams', true)` to get a warning if
+any of your code still uses the deprecated named params.
+
+
+### FlashMessages
+In 3.x there will be a FlashComponent instead. Mine also provides stackable (multi) messages.
+See https://github.com/dereuromark/cakephp-tools/wiki/Flash-messages for details.
+
+### IntegrationTestCase
+The ControllerTestCase will be gone in 3.x. Instead there will be a IntegrationTestCase that involves
+less, but smarter, mocking.
+I backported a basic version of it in 2.x already.
+When upgrading you almost have nothing to change in those test case files.
+
+### Login/Passwords
+Already use the PHP5.5+ password functionality with the ModernPasswordHasher class and the Passwordable behavior.
+Easily upgradable to 3.x in minutes.
+
+### RSS
+Use RssView instead of the akward and limited helper approach.
+
+### MyCakeTestCase
+- testAction() defaults to GET
+- TestConsoleOutput() for stdout and stderr instead of mocks
+
+### Model shims
+In 3.x the updateAll() and deleteAll() won't autojoin anymore. In order to already write future proof versions of that you can use
+- updateAllJoinless()
+- deleteAllJoinless()
+In 3.x all you need to do is rename them back again instead of tryig to fix all broken code.
+
+For findById() and exists() there will be get(). You can directly use it via MyModel::get().
+
+
+### More
+
+#### Templates
+Backported StringTemplate class (from CakePHP3.0) can be used to use template based rendering of HTML tags.
+
+#### Helpers
+FormExt and HtmlExt helpers also provide extended functionality and 3.x shims.
+
+#### Ajax
+Use the AjaxView which will easily be upgradable as a clean component approach.