more docs

docs/Behavior/Reset.md

@@ -0,0 +1,78 @@
+# Reset Behavior
+
+A CakePHP behavior to automatically "reset" all records as batch process
+- Re-triggers all callbacks (beforeValidate/beforeSave)
+- Batch process of x entries per run to avoid memory overkill
+- Custom callbacks attachable
+
+## Configs
+- 'limit' => 100 // batch of records per loop
+- 'timeout' => null // in seconds
+- 'fields' => array() // if not displayField
+- 'updateFields' => array() // if saved fields should be different from fields
+- 'validate' => true // trigger beforeValidate callback
+- 'updateTimestamp' => false // update modified/updated timestamp
+- 'scope' => array() // optional conditions
+- 'callback' => null
+
+## Usage
+Attach it to your models in `initialize()` like so:
+```php
+$this->addBehavior('Tools.Reset', $config);
+```
+
+This resetting should ideally be done via CLI shell/task.
+You should make a shell command for this and execute this migration code once
+on deploy of the modified code or SQL schema.
+If you are not using CLI, make sure you set the time limit in your controller action accordingly (HOUR for example).
+
+## Examples
+
+### Resetting Slugs
+```php
+// First we need to re-load the Slugged behavior to enable "overwrite" mode
+$this->Post->removeBehavior('Slugged');
+$this->Post->addBehavior('Tools.Slugged', array('label' => 'title', 'overwite' => true));
+// Load the Reset behavior with only the title and slug field to read and modify.
+$this->Post->addBehavior('Tools.Reset', array('fields' => array('title', 'slug')));
+$res = $this->Post->resetRecords();
+// Debug output with number of records modified in $res
+```
+
+### Retrigger/Init Geocoding
+```php
+$this->Post->addBehavior('Tools.Reset', array('fields' => array('address', 'lat', 'lng'), 'timeout' => 3));
+$res = $this->Post->resetRecords();
+```
+Since all lat/lng fields are still null it will geocode the records and populate those fields.
+It will skip already geocoded ones. If you want to skip those completely (not even read them),
+just set the scope to `'NOT' => array('lat' => null)` etc.
+
+Note that in this case we also use a timeout to avoid getting a penalty by Google for geocoding too many records per minute.
+
+### Advanced example: Resetting composite cache field
+
+In this case we added a new cache field to our messages in order to make the search faster with >> 100000 records. The data was containing all the info we needed – in serialized format. We needed a callback here as there was some logic involved. So we simply made a shell containing both callback method and shell command:
+```php
+$this->Message->addBehavior('Tools.Reset', array(
+    'fields' => array('data'), 'updateFields' => array('guest_name'),
+    'scope' => array('data LIKE' => '{%'), 'callback' => 'UpdateShell::prepMessage'));
+$res = $this->Message->resetRecords();
+$this->out('Done: ' . $res);
+```
+
+The callback method (in this case just statically, as we didnt want to mess with the model itself):
+```php
+public static function prepMessage(array $row) {
+    if (empty($row['Message']['data_array']['GUEST_FIRST_NAME'])) {
+        return array();
+    }
+
+    $row['Message']['guest_name'] = $row['Message']['data_array']['GUEST_FIRST_NAME'] . ' ' . $row['Message']['data_array']['GUEST_LAST_NAME'];
+    return $row;
+}
+```
+See the test cases for more ways to use callbacks – including adjusting the updateFields list.
+
+So as you can see, everything that involves a complete “re-save” including triggering of important
+callbacks (in model and behaviors) of all or most records can leverage this behavior in a DRY, quick and reusable way.

docs/View/Rss.md

@@ -0,0 +1,48 @@
+# Rss View
+
+A CakePHP view class to quickly output RSS feeds
+- By default template-less
+- Very customizable regarding namespaces and prefixes
+- Supports CDATA (unescaped content).
+
+## Configs
+- 'limit' => 100 // batch of records per loop
+- 'timeout' => null // in seconds
+- 'fields' => array() // if not displayField
+- 'updateFields' => array() // if saved fields should be different from fields
+- 'validate' => true // trigger beforeValidate callback
+- 'updateTimestamp' => false // update modified/updated timestamp
+- 'scope' => array() // optional conditions
+- 'callback' => null
+
+## Usage
+You can config it in your actions like so:
+```php
+$this->viewClass = 'Tools.Rss';
+```
+
+The nicer way would be to use extenions-routing and let CakePHP auto-switch to this view class.
+See the documentation on how to use view class mapping to automatically respond with the RssView for each request to the rss extension:
+
+    'rss' => 'Tools.Rss'
+
+With the help of parseExtensions() and RequestHandler this will save you the extra view config line in your actions.
+
+By setting the '_serialize' key in your controller, you can specify a view variable
+that should be serialized to XML and used as the response for the request.
+This allows you to omit views + layouts, if your just need to emit a single view
+variable as the XML response.
+
+In your controller, you could do the following:
+```php
+$this->set(array('posts' => $posts, '_serialize' => 'posts'));
+```
+When the view is rendered, the `$posts` view variable will be serialized
+into the RSS XML.
+
+**Note** The view variable you specify must be compatible with Xml::fromArray().
+
+If you don't use the `_serialize` key, you will need a view. You can use extended
+views to provide layout like functionality. This is currently not yet tested/supported.
+
+## Examples

src/View/Helper/GoogleMapV3Helper.php

@@ -15,18 +15,19 @@ use Cake\Router\Router;
  * CodeAPI: http://code.google.com/intl/de-DE/apis/maps/documentation/javascript/basics.html
  * Icons/Images: http://gmapicons.googlepages.com/home
  *
- * @author Rajib Ahmed
- * @author Mark Scherer
- * @link http://www.dereuromark.de/2010/12/21/googlemapsv3-cakephp-helper/
- * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
- * @version 1.5
- *
  * You can now either keep map() + script(), or you can now write the script to the buffer with
  * map() + finalize(). You can then decide wether the JS should be in the head or the footer of your layout.
  * Don't forget to put `echo $this->Js->writeBuffer(array('inline' => true));` somewhere in your layout then, though.
  *
  * You can now also add directions using addDirections().
  * Markers can be open now by default on page load. Works for both single and multi window mode.
+ *
+ * @author Rajib Ahmed
+ * @author Mark Scherer
+ * @link http://www.dereuromark.de/2010/12/21/googlemapsv3-cakephp-helper/
+ * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
+ * @version 1.5
+ * @deprecated Use dereuromark/cakephp-geo and the Geo plugin instead
  */
 class GoogleMapV3Helper extends Helper {
 

src/View/RssView.php

@@ -1,13 +1,4 @@
 <?php
-/**
- * Licensed under The MIT License
- * For full copyright and license information, please see the LICENSE.txt
- * Redistributions of files must retain the above copyright notice.
- *
- * @author Mark Scherer
- * @license http://www.opensource.org/licenses/mit-license.php MIT License
- * @link http://www.dereuromark.de/2013/10/03/rss-feeds-in-cakephp
- */
 namespace Tools\View;
 
 use Cake\Core\Configure;
@@ -40,6 +31,12 @@ use App\Router\Routing;
  *
  * If you don't use the `_serialize` key, you will need a view. You can use extended
  * views to provide layout like functionality. This is currently not yet tested/supported.
+ *
+ * Usage see docs.
+ *
+ * @author Mark Scherer
+ * @license http://www.opensource.org/licenses/mit-license.php MIT License
+ * @link http://www.dereuromark.de/2013/10/03/rss-feeds-in-cakephp
  */
 class RssView extends View {