Merge branch 'bugfix/missing-doc-4547-4548'

fixes #4546
fixes #4548

doc/form_elements.md

@@ -0,0 +1,66 @@
+# Form Elements Shipped With Icinga 2 Web
+
+On top of the elements provided by the Zend Framework, Icinga 2 Web ships its own to offer additional functionality.
+The following is a list of these classes, as well as descriptions of the functionality they offer.
+
+## DateTimePicker
+
+`Icinga\Web\Form\Element\DateTimePicker` represents a control that allows the user to select date/time and to
+display the date and time with a user specified format. Internally the element returns the input as Unix timestamp after
+it has been proven valid. That is when the input is valid to `\DateTime::createFromFormat()` according to the user
+specified format. Input is always timezone aware because the element utilizes `Icinga\Util\DateTimeFactory` which relies
+on the timezone set by the user.
+
+**Example #1 DateTimePicker expecting date**
+
+    use Icinga\Web\Form\Element\DateTimePicker;
+
+    $element = new DateTimePicker(
+        array(
+            'name'      => 'date',
+            'label'     => t('Date'),
+            'patterns'  => array('Y-m-d') // Allowed format
+        )
+    )
+
+**Example #2 DateTimePicker expecting time**
+
+    use Icinga\Web\Form\Element\DateTimePicker;
+
+    $element = new DateTimePicker(
+        array(
+            'name'      => 'time',
+            'label'     => t('Time'),
+            'patterns'  => array('H:i:s') // Allowed format
+        )
+    )
+
+**Example #3 DateTimePicker expecting date and time**
+
+    use Icinga\Web\Form\Element\DateTimePicker;
+
+    $element = new DateTimePicker(
+        array(
+            'name'      => 'datetime',
+            'label'     => t('Date And Time'),
+            'patterns'  => array('Y-m-d H:i:s') // Allowed format
+        )
+    )
+
+**Example #4 DateTimePicker expecting date/time w/ default value**
+
+    use Icinga\Web\Form\Element\DateTimePicker;
+    use Icinga\Util\DateTimeFactory;
+
+    $now = DateTimeFactory::create();
+
+    $element =  new DateTimePicker(
+        array(
+            'name'      => 'datetime',
+            'label'     => t('Date/Time'),
+            'value'     => $now->getTimestamp() + 3600, // now plus 1 hour
+            'patterns'  => array('Y-m-d H:i:s', 'Y-m-d', 'H:i:s') // Allowed format
+        )
+    )
+
+

doc/test/php_tests.md

@@ -28,6 +28,37 @@ modules/mymodule/library/MyModule/Helper/MyClass.php.
         }
     }
 
+## Testing Singletons
+
+When test methods **modify static** class properties (which is the case when using singletons), add the PHPUnit
+[`@backupStaticAttributes enabled`](http://phpunit.de/manual/3.7/en/appendixes.annotations.html#appendixes.annotations.backupStaticAttributes)
+annotation to their [DockBlock](http://www.phpdoc.org/docs/latest/for-users/phpdoc/basic-syntax.html#what-is-a-docblock)
+in order to backup and restore static attributes before and after the method execution respectively. For reference you
+should **document** that the test interacts with static attributes:
+
+    <?php
+
+    namespace My\Test;
+
+    use \PHPUnit_Framework_TestCase;
+    use My\CheesecakeFactory;
+
+    class SingletonTest extends PHPUnit_Framework_TestCase
+    {
+        /**
+         * Interact with static attributes
+         *
+         * Utilizes singleton CheesecakeFactory
+         *
+         * @backupStaticAttributes enabled
+         */
+        public function testThatInteractsWithStaticAttributes()
+        {
+            CheesecakeFactory::setOpeningHours(24);
+            // ...
+        }
+    }
+
 ## Requirements and the dependency mess
 
 ### spl_autoload_register vs. require