packagefactory/atomicfusion-proptypes

Fusion port of react-propTypes for the fusion-prototypes PackageFactory.AtomicFusion:Component and Neos.Fusion:Component

PackageFactory.AtomicFusion.PropTypes

, _(*1)

Validate the props passed to a component via @propType annotation. The syntax for the propType annotation is derived from react-propTypes., _(*2)

ATTENTION: This package is by default only validating the props in development-context., _(*3)

prototype(Vendor.Site:Example) < prototype(Neos.Fusion:Component) {
    @propTypes {
        # optional, enforce that only validated props exist
        @strict = true
        # validation rules for props
        title = ${PropTypes.string.isRequired}
        subtitle = ${PropTypes.string}
    }
}

This will validate the given props with the validator that created in the @propTypes section via., _(*4)

Fusion Validator Prototypes

Proptypes can also be specified via fusion objects., _(*5)

@propTypes {
    # all props can be marked as required via `@required = true`
    int = PropTypes:Int {
      @required = true
    }
    float = PropTypes:Float
    bool = PropTypes:Bool

    # strings allow to specify an optional `regularExpression`
    string = PropTypes:String {
        regularExpression = '/hello world/'
    }

    # allows array values that satisfy the `type`
    array = PropTypes:Array {
        type = PropTypes:Int
    }

    # allow values that satisfy one of the given validators
    union = PropTypes:Union {
        int = PropTypes:Int
        string = PropTypes:String
        ...
    }

    # allow exacly the values that are specified
    enum = PropTypes:Enum {     
      value1 = "foo"
      value2 = "bar"
      ...
    }

    # a nested structure that is valid once all children valídate
    dataStructure = PropTypes:DataStructure {
        title = PropTypes:String
        description = PropTypes:String
        ...
    }

    # a php object that satisfies the given interface
    instanceOf = PropTypes:InstanceOf {
        type = '\DateTimeInterface'
    }

    # data structure validator that uses the defined proptypes from another prototype
    fromPrototype = PropTypes:FromPrototype {
        prototypeName = "Vendor.Site:Prototype"
    }
}

Methods that are supported by the propTypes helper

• PropTypes.any: Accepts any value including null.
• PropTypes.boolean: Validate that a boolean value is given, accepts null.
• PropTypes.integer: Validate that an integer is given, accepts null.
• PropTypes.float:
  Validate that an float is given, accepts null.
• PropTypes.string:
  Validate that an string is given, accepts null.
• PropTypes.regex('/pattern/'): Validate that the given string matches the pattern
• PropTypes.oneOf([123, "foo", "bar"]): Validate the value equals one of the given options.
• PropTypes.arrayOf( PropTypes.string ): Validate an array was given and all validate with the given validator, accepts null.
• PropTypes.anyOf( PropTypes.string, PropTypes.integer ): Validate the value validates at least with one of the given validators, accepts null.
• PropTypes.dataStructure({'foo': PropTypes.integer, 'bar': PropTypes.string}): Validate the keys of the given array validate with the assigned Validator, accepts null and ignores all other keys. The key validators have to define wether a single key is required.
• PropTypes.shape({'foo': PropTypes.integer, 'bar': PropTypes.string}): Validate the keys of the given array validate with the assigned Validator, accepts null and ignores all other keys. The key validators have to define wether a single key is required.
• PropTypes.fileExists: Validate that a given value is an existing file.
• PropTypes.instanceOf('Neos.Neos:Document'): Validate the value with the given type, if the value is a Node the NodeType is checked instead of the php-class, accepts null.

Making values mandatory

• PropTypes.*.isRequired: To ensure a value is given the isRequired-method can be called after the type-validation. This adds an additional notEmpty validator to enforce that a value is given.

How it works

If the validation is enabled an aspect is wrapped around the evaluate method of Neos.Fusion:Component and PackageFactory.AtomicFusion:Component implementations., _(*6)

This aspect will evaluated the keys in the @propTypes section wich are expected to return Flow-Validators (Neos\Flow\Validation\Validator\ValidatorInterface). Next the current prop-value ford each key is evaluated and passed to the validator. If any of the validation results contains errors a fusion-error is thrown., _(*7)

The PropTypes-EelHelper is a wrapper around the PackageFactory\AtomicFusion\PropTypes\Validators\PropTypeValidator which is an EelHelper and Validator at the same time. This Object is creates an compound-validator that is controlled in a react-propTypes like syntax via eel., _(*8)

By creating FusionObjects or EelHelpers that return custom validators you can extend this mechanism if needed., _(*9)

Strict mode

In strict mode an error is thrown if an unvalidated prop is passed to a component in development context. This ensures that all props are validated., _(*10)

To enable strict mode for a component add @strict = true to the @propTypes., _(*11)

prototype(Vendor.Site:Example) < prototype(Neos.Fusion:Component) {
    @propTypes {
        @strict = true
        ...
    }
}

Settings

The propType-validation is enabled via settings. By default this setting is enabled for Development and Testing context but not enabled for Production., _(*12)

PackageFactory:
  AtomicFusion:
    PropTypes:
      enable: false

Installation

PackageFactory.AtomicFusion.PropTypes is available via packagist. Just run composer require packagefactory/atomicfusion-proptypes., _(*13)

We use semantic-versioning so every breaking change will increase the major-version number., _(*14)

License

see LICENSE file, _(*15)