Merging develop to master in preparation for 2.12.0 release.

Author: weierophinney

CHANGELOG.md

@@ -2,10 +2,18 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 2.11.1 - TBD
+## 2.12.0 - 2018-05-16
 
 ### Added
 
+- [#194](https://github.com/zendframework/zend-form/pull/194) adds the ability to whitelist additional HTML attributes for use with a view helper,
+  as well as attribute prefixes. These can be enabled via the following:
+  
+  ```php
+  $helper->addValidAttribute('attribute-name');
+  $helper->addValidAttributePrefix('prefix-');
+  ```
+
 - [#188](https://github.com/zendframework/zend-form/pull/188) adds a new method to the `FormElementErrors` view helper, `setTranslateMessages(bool $flag)`.
   By default, the helper continues to translate error messages (if a translator
   is present), as introduced in 2.11.0. However, using this method, you can
@@ -23,9 +31,9 @@ All notable changes to this project will be documented in this file, in reverse
 ### Changed
 
 - [#193](https://github.com/zendframework/zend-form/pull/193) modifies how attributes are escaped. If zend-espaper raises an exception
-  for an invalid attribute value, helpers will now catch the exception, and use a
-  blank value for the attribute. This prevents 500 errors from being raised for
-  such pages.
+  for an invalid attribute value, helpers will now catch the exception, and use
+  a blank value for the attribute. This prevents 500 errors from being raised
+  for such pages.
 
 ### Deprecated
 

composer.json

@@ -66,8 +66,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.11.x-dev",
-            "dev-develop": "2.12.x-dev"
+            "dev-master": "2.12.x-dev",
+            "dev-develop": "2.13.x-dev"
         },
         "zf": {
             "component": "Zend\\Form",

composer.lock

@@ -25,6 +25,8 @@ Method signature                                               | Description
 `addTranslatableAttributePrefix(string $prefix) : self`        | Marks all HTML attributes that start with the given prefix as translatable.
 `addDefaultTranslatableAttribute(string $attribute) : void`    | Marks the given HTML attribute as translatable for all view helpers.
 `addDefaultTranslatableAttributePrefix(string $prefix) : void` | Marks all HTML attributes that start with the given prefix as translatable for all view helpers.
+`addValidAttribute(string $attribute) : self`                  | Add an HTML attribute to the list of valid attributes for the given element.
+`addValidAttributePrefix(string $prefix) : self`               | Add an HTML attribute prefix to the list of valid attribute prefixes. Any attribute with this preix will be considered valid. By default, the list includes "data-", "aria-", and "x-".
 
 ## Translation
 
@@ -69,3 +71,27 @@ Or you can mark them as translatable for all view helpers (e. g. the title attri
 // mark an prefix as translatable
 \Zend\Form\View\Helper\AbstractHelper->addDefaultTranslatableAttributePrefix('data-translatable-');
 ```
+
+## Allowing framework-specific attributes
+
+Many JavaScript frameworks use custom attributes and/or attribute prefixes with
+elements, to facilitate various bindings and event listeners. Examples include
+`ng-` for [Angular](https://angularjs.org) elements, and `v-` for
+[Vue](https://vuejs.org).
+
+zend-form view helpers are strict about what attributes they consider valid. If
+you wish to allow additional attributes, you will need to notify the helper of
+them.
+
+The first mechanism is to add a specific attribute:
+
+```php
+$helper->addValidAttribute('some-attribute');
+```
+
+If you wish to allow a set of attributes with a common prefix, use the
+following:
+
+```php
+$helper->addValidAttributePrefix('ng-');
+```

docs/book/helper/abstract-helper.md

@@ -70,4 +70,5 @@ Method signature                                                     | Descripti
 `getMessageCloseString() : string`                                   | Returns the string used to close message representation.
 `setAttributes(array $attributes) : void`                            | Set the attributes that will go on the message open format as key/value pairs.
 `getAttributes() : array`                                            | Returns the attributes that will go on the message open format.
+`setTranslateMessages(bool $flag) : self`                            | Indicate whether or not element validation error messages should be translated during `render()`. Default is to translate them.
 `render(ElementInterface $element [, array $attributes = array()]) : string` | Renders validation errors for the provided `$element`. Attributes provided will be used in the `messageOpenFormat`, and merged with any provided previously via `setAttributes()`.

docs/book/helper/form-element-errors.md

@@ -9,6 +9,7 @@
 
 use Zend\Escaper\Exception\RuntimeException as EscaperException;
 use Zend\Form\ElementInterface;
+use Zend\Form\Exception\InvalidArgumentException;
 use Zend\I18n\View\Helper\AbstractTranslatorHelper as BaseAbstractHelper;
 use Zend\View\Helper\Doctype;
 use Zend\View\Helper\EscapeHtml;
@@ -160,6 +161,17 @@ abstract class AbstractHelper extends BaseAbstractHelper
         'xml:space'          => true,
     ];
 
+    /**
+     * Attribute prefixes valid for all tags
+     *
+     * @var array
+     */
+    protected $validTagAttributePrefixes = [
+        'data-',
+        'aria-',
+        'x-',
+    ];
+
     /**
      * Attributes valid for the tag represented by this helper
      *
@@ -375,11 +387,8 @@ protected function prepareAttributes(array $attributes)
 
             if (! isset($this->validGlobalAttributes[$attribute])
                 && ! isset($this->validTagAttributes[$attribute])
-                && 0 !== strpos($attribute, 'data-')
-                && 0 !== strpos($attribute, 'aria-')
-                && 0 !== strpos($attribute, 'x-')
+                && ! $this->hasAllowedPrefix($attribute)
             ) {
-                // Invalid attribute for the current tag
                 unset($attributes[$key]);
                 continue;
             }
@@ -455,6 +464,42 @@ protected function translateHtmlAttributeValue($key, $value)
         return $value;
     }
 
+    /**
+     * Adds an HTML attribute to the list of valid attributes
+     *
+     * @param string $attribute
+     * @return AbstractHelper
+     * @throws InvalidArgumentException for attribute names that are invalid
+     *     per the HTML specifications.
+     */
+    public function addValidAttribute($attribute)
+    {
+        if (! $this->isValidAttributeName($attribute)) {
+            throw new InvalidArgumentException(sprintf('%s is not a valid attribute name', $attribute));
+        }
+
+        $this->validTagAttributes[$attribute] = true;
+        return $this;
+    }
+
+    /**
+     * Adds a prefix to the list of valid attribute prefixes
+     *
+     * @param string $prefix
+     * @return AbstractHelper
+     * @throws InvalidArgumentException for attribute prefixes that are invalid
+     *     per the HTML specifications for attribute names.
+     */
+    public function addValidAttributePrefix($prefix)
+    {
+        if (! $this->isValidAttributeName($prefix)) {
+            throw new InvalidArgumentException(sprintf('%s is not a valid attribute prefix', $prefix));
+        }
+
+        $this->validTagAttributePrefixes[] = $prefix;
+        return $this;
+    }
+
     /**
      * Adds an HTML attribute to the list of translatable attributes
      *
@@ -502,4 +547,34 @@ public static function addDefaultTranslatableAttributePrefix($prefix)
     {
         self::$defaultTranslatableHtmlAttributePrefixes[] = $prefix;
     }
+
+    /**
+     * Whether the passed attribute is valid or not
+     *
+     * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2
+     *     Description of valid attributes
+     * @param string  $attribute
+     * @return bool
+     */
+    protected function isValidAttributeName($attribute)
+    {
+        return preg_match('/^[^\t\n\f \/>"\'=]+$/', $attribute);
+    }
+
+    /**
+     * Whether the passed attribute has a valid prefix or not
+     *
+     * @param string  $attribute
+     * @return bool
+     */
+    protected function hasAllowedPrefix($attribute)
+    {
+        foreach ($this->validTagAttributePrefixes as $prefix) {
+            if (substr($attribute, 0, strlen($prefix)) === $prefix) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

src/View/Helper/AbstractHelper.php

@@ -1,15 +1,14 @@
 <?php
 /**
- * Zend Framework (http://framework.zend.com/)
- *
- * @link      http://github.com/zendframework/zf2 for the canonical source repository
- * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
- * @license   http://framework.zend.com/license/new-bsd New BSD License
+ * @see       https://github.com/zendframework/zend-form for the canonical source repository
+ * @copyright Copyright (c) 2005-2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-form/blob/master/LICENSE.md New BSD License
  */
 
 namespace ZendTest\Form\View\Helper;
 
 use Zend\Escaper\Escaper;
+use Zend\Form\Exception\InvalidArgumentException;
 use Zend\Form\View\Helper\AbstractHelper;
 use Zend\I18n\Translator\Translator;
 
@@ -23,7 +22,6 @@ class AbstractHelperTest extends CommonTestCase
     public function setUp()
     {
         $this->helper = $this->getMockForAbstractClass('Zend\Form\View\Helper\AbstractHelper');
-
         parent::setUp();
     }
 
@@ -60,6 +58,77 @@ public function testWillNotEncodeValueAttributeValuesCorrectly()
         );
     }
 
+    public function addAttributesData()
+    {
+        return [
+            'valid'                => ['valid', 'valid="value"'],
+            'valid-prefix'         => ['px-custom', 'px-custom="value"'],
+            'xml-ns'               => ['xlink:custom', 'xlink:custom="value"'],
+            'invalid-slash'        => ['attr/', null, true],
+            'invalid-double-quote' => ['attr"', null, true],
+            'invalid-quote'        => ['attr\'', null, true],
+            'invalid-gt'           => ['attr>', null, true],
+            'invalid-equals'       => ['attr=value', null, true],
+            'invalid-space'        => ['at tr', null, true],
+            'invalid-newline'      => ["at\ntr", null, true],
+            'invalid-tab'          => ["at\ttr", null, true],
+            'invalid-formfeed'     => ["at\ftr", null, true],
+        ];
+    }
+
+    /**
+     * @dataProvider addAttributesData
+     */
+    public function testWillIncludeAdditionalAttributes($attribute, $expected = null, $exception = null)
+    {
+        if ($exception) {
+            $this->expectException(InvalidArgumentException::class);
+        }
+
+        $this->helper->addValidAttribute($attribute);
+
+        $this->assertSame(
+            $expected,
+            $this->helper->createAttributesString([$attribute => 'value'])
+        );
+    }
+
+    public function addAttributesPrefixData()
+    {
+        return [
+            'valid'                => ['v-', 'v-attr="value"'],
+            'valid-dash'           => ['custom-', 'custom-attr="value"'],
+            'xml-ns'               => ['xlink:', 'xlink:attr="value"'],
+            'valid-nodash'         => ['abc', 'abcattr="value"'],
+            'invalid-slash'        => ['custom/', null, true],
+            'invalid-double-quote' => ['custom"', null, true],
+            'invalid-quote'        => ['custom\'', null, true],
+            'invalid-gt'           => ['custom>', null, true],
+            'invalid-equals'       => ['custom=', null, true],
+            'invalid-space'        => ['custom ', null, true],
+            'invalid-newline'      => ["cus\ntom", null, true],
+            'invalid-tab'          => ["cus\ttom", null, true],
+            'invalid-formfeed'     => ["cus\ftom", null, true],
+        ];
+    }
+
+    /**
+     * @dataProvider addAttributesPrefixData
+     */
+    public function testWillIncludeAdditionalAttributesByPrefix($prefix, $expected = null, $exception = null)
+    {
+        if ($exception) {
+            $this->expectException(InvalidArgumentException::class);
+        }
+
+        $this->helper->addValidAttributePrefix($prefix);
+
+        $this->assertSame(
+            $expected,
+            $this->helper->createAttributesString([$prefix . 'attr' => 'value'])
+        );
+    }
+
     public function testWillTranslateAttributeValuesCorrectly()
     {
         $translator = self::getMockBuilder(Translator::class)