Permalink
Browse files

Added new source code of FormHandler v5

  • Loading branch information...
gMQNQWo5KfjJDt committed Aug 30, 2017
1 parent 62df88d commit a07c1f0f4750992061101232b33ff05b4d4ab2d8
View
@@ -19,3 +19,4 @@ docs
*.old
*.bak
*.jar
View
@@ -27,4 +27,4 @@ script:
- ant travis
after_success:
- if [ "$TRAVIS_PHP_VERSION" = "5.6" ]; then travis_retry php vendor/bin/coveralls -v; fi
- if [ "$TRAVIS_PHP_VERSION" = "5.6" ]; then travis_retry php vendor/bin/coveralls -v; fi
View
172 README.md
@@ -1,4 +1,5 @@
[![Build Status](https://travis-ci.org/teyeheimans/FormHandler.svg?branch=master)](https://travis-ci.org/teyeheimans/FormHandler)
[![Build Status](https://travis-ci.org/teyeheimans/FormHandler.svg?branch=master)](https://travis-ci.org/teyeheimans/FormHandler)
[![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%205.6-8892BF.svg?style=flat-square)](https://php.net/)
[![Coverage Status](https://coveralls.io/repos/github/teyeheimans/FormHandler/badge.svg?branch=master)](https://coveralls.io/github/teyeheimans/FormHandler?branch=master)
FormHandler
@@ -18,14 +19,14 @@ To create a form you have to:
Requirements
------
FormHandler requires PHP 5.4 or higher.
FormHandler requires PHP 5.6 or higher. It should also work on 5.5 and 5.4, but automated Travis testing does
not work for these versions.
FormHandler is tested on:
* PHP 5.4
* PHP 5.5
FormHandler is tested on:
* PHP 5.6
* PHP 7.0
* PHP HHVM
* PHP 7.1
* PHP 7.2
* PHP Latest 'nightly' build
Installation
@@ -46,7 +47,6 @@ FormHandler has a few assumptions:
A very basic example is:
```php
#
# This code defines your form and what to do with it when it's valid.
# This code is probably defined in your controller.
@@ -55,23 +55,19 @@ A very basic example is:
// Create the form
$form = new Form();
// Create a field in the form. Fluent method chaining is supported.
$form -> textField('name')
-> addValidator( new StringValidator( 2, 50, true, 'You have to supply your name (between 2 and 50 characters)' ) )
-> setPlaceholder( 'Enter your name' );
// Create a field in the form. Fluent method chaining is supported.
$form->textField('name')
->addValidator(new StringValidator(2, 50, true, 'You have to supply your name (between 2 and 50 characters)'))
->setPlaceholder('Enter your name');
// Check if the form is submitted
if( $form -> isSubmitted() )
{
if ($form->isSubmitted()) {
// Check if the form is valid.
if( $form -> isValid() )
{
// Do your stuff here with the form, for example, store something
// in a database.
if ($form->isValid()) {
// Do your stuff here with the form, for example, store something in a database.
}
}
else
{
} else {
// Here, the form is not yet submitted!
// You could for example set some predefined values in the form.
}
@@ -81,10 +77,10 @@ else
#
// This will display the <form> html tag.
echo $form;
echo $form;
// This will display the HTML tag for the "name" field.
echo $form('name');
echo $form('name');
// You can mix plain old html with "dynamic" generated fields
// Of course you could also generate a SubmitButton object and use that one.
@@ -118,15 +114,16 @@ FormHandler implements a fluent interface. This means that you *can* use method
Example:
```php
<?php
$form = new Form();
// An example using method chaining.
$form -> textField( 'name' )
-> setSize( 10 )
-> setId( 'myName' )
-> setTitle( 'Enter your name' )
-> setPlaceholder( '<name here>' )
-> addValidator( new StringValidator( 2, 50, true ) );
$form->textField('name')
->setSize(10)
->setId('myName')
->setTitle('Enter your name')
->setPlaceholder('<name here>')
->addValidator(new StringValidator(2, 50, true));
```
General methods
@@ -168,11 +165,14 @@ like this:
$form = new Form();
// Create a field in the form
$form -> textField('name');
$form->textField('name');
// Retrieve the form by it's name using the shorthand:
$field = $form('name');
// Or use the "classic" way:
$field = $form->getFieldByName('name');
// ... Etc
```
@@ -227,6 +227,7 @@ Therefore it needs to be absolutly clear how FormHandler displays strings and wh
This means that button values are thus also not escaped, as they cannot be filled from the `$_GET` or `$_POST`.
Rendering
------
FormHandler tries to limit it's functionality to what it should do: handle forms. However, displaying the forms is
@@ -240,113 +241,24 @@ are always elements which are related:
* Displaying if the field is required or not
FormHandler tries to not to interfere with the design part of your application. However, it should be clear that
its inevitable that FormHandler has some responsibility of generating HTML content.
its thus inevitable that FormHandler has some responsibility of generating HTML content.
FormHandler comes with a class called a `Renderer`. This class is responsible for rendering the element
(field/button/form) and all its related information (error messages, titles, etc).
Our default Renderer is the `XhtmlRenderer`. This will render each field as an XHTML tag.
You can also influence the rendering of titles and error messages, or disable these at all.
It's quite easy to create your own class which will render the elements in the way you expect them. For example,
if you want to render titles and add a red asterisk (*) near each field, you could extend the `XhtmlRenderer`, override the
`render` method and add this logic to it.
A `Renderer` is a simple class which should have at least 1 method: `render( Element $element)`. This method
is in control to generate the correct HTML for the given `Element`. This could be a field, button, form or option.
Example:
```
The `XhtmlRenderer` is the default renderer. This class will make sure that all elements are rendered als XHTML.
This class will also make sure that:
```
* Error messages are rendered as an `<tt>` tag
* Help messages are rendered as an `<dfn>` tag
Validation
------
One of the most important parts of handling forms is validation. FormHandler comes with a complete set of
*Validators* which can be used to validate a field. You can also enter your own method/function/closure which will be
used to validate the specific field.
#### Using your own Validator
You can change this logic to setting it to render them as an attribute, or not render them at all.
A simple example with a own validator (closure) is:
```php
// Create a new field with a custom validator
$form->textField('terms')->addValidator(function (TextField $field) {
if ($field->getValue() == 'agree') {
return true;
} else {
return 'You have to enter "agree"';
}
});
```
The same principle also works with function names and methods. Example:
```php
// Just a field...
$field = $form->textField('name');
// Add a function as validator
$field->addValidator('myFunction');
// Add a static method as validator
$field->addValidator('myclass::staticMethod');
// Add a method as validator
$field->addValidator([$object, 'myMethod']);
```
#### Using an existing validator
FormHandler comes with a whole list of validators. Per validator you can define if the field should be required or not.
You can choose from the following validators:
* CharacterBlacklistValidator - Check if all characters of the value are in the predefined list of characters
* CharacterWhitelistValidator - Check that all characters of the value are not in a list of blacklisted characters
* DateValidator - Check if the entered value is a valid date. The input is considered valid if it can be parsed by the PHP function `date_parse`
* EmailValidator - Check if the value is a valid email address
* EqualsValidator - Check if the value is equal to a given value.
* FloatValidator - Check if the value is a valid float. Possible to check for comma, point or both.
* ImageUploadValidator - Check if the uploaded file is a valid image. Optional check proportions, aspect ratio, filesize, extension, etc.
* IpValidator - Check if the value is a valid ip. Checking for private ranges, ipv6 or reserved ranges is supported.
* IsOptionValidator - Check if the value is an existing option.
* NumberValidator - Check if the value is a valid number and between optional min and max value.
* RadioButtonCheckedValidator - Check if at least one radio button is checked of all radio buttons with the same name.
* RegexValidator - Check if the value matches a given regular expression
* SameFieldsValidator - Check if two fields have the same value
* StringValidator - Check if the given value is a valid string and optionally between min and max length.
* UploadValidator - Check if the uploaded field is valid. Check for correct mime type, extension and size are supported.
* UrlValidator - Check if the given value is a valid URL.
Because the `Renderer` is responsible for all rendering, it's quite easy to create your own class which will render
the elements in the way you expect them. The easiest way of doing this is by extending the XhtmlRenderer. For example
please take a look at the `CowSayRenderer`, which will render all _Fields_ with a nice CowSay around them.
FAQ
-----
##### How can I check if an element is an field or a button?
You can check if the element is an instanceof `AbstractFormField` or `AbstractFormButton`.
##### The form is never submitted, I tried everything!
You can retrieve the reason why the form is not submitted by giving it an argument `$reason`. This variable will be
filled with a reason message why FormHandler has decided that the form was not submitted.
Example:
```php
// Create a new form
$form = new Form();
// ... the rest of the form here ...
// When the form was not submitted, this variable is filled with the reason.
$reason = '';
if ($form->isSubmitted($reason)) {
// When the form was marked as valid.
if ($form->isValid()) {
// valid!
}
} else {
// The form was not submitted. Also display why
echo "Form is not submitted. Reason: " . htmlentities( $reason );
}
```
View
@@ -6,7 +6,6 @@
<property name="phpcpd" value="phpcpd"/>
<property name="phpcs" value="phpcs"/>
<property name="phpcbf" value="phpcbf"/>
<property name="phpdox" value="phpdox"/>
<property name="phploc" value="phploc"/>
<property name="phpmd" value="phpmd"/>
<property name="phpunit" value="phpunit"/>
@@ -17,7 +16,6 @@
<property name="phpcpd" value="${basedir}/build/tools/phpcpd.phar"/>
<property name="phpcbf" value="${basedir}/build/tools/phpcbf.phar"/>
<property name="phpcs" value="${basedir}/build/tools/phpcs.phar"/>
<property name="phpdox" value="${basedir}/build/tools/phpdox.phar"/>
<property name="phploc" value="${basedir}/build/tools/phploc.phar"/>
<property name="phpmd" value="${basedir}/build/tools/phpmd.phar"/>
<property name="composer" value="${basedir}/build/tools/composer.phar"/>
@@ -28,26 +26,25 @@
<property name="phpcpd" value="${basedir}/vendor/bin/phpcpd"/>
<property name="phpcbf" value="${basedir}/vendor/bin/phpcbf"/>
<property name="phpcs" value="${basedir}/vendor/bin/phpcs"/>
<property name="phpdox" value="${basedir}/vendor/bin/phpdox"/>
<property name="phploc" value="${basedir}/vendor/bin/phploc"/>
<property name="phpmd" value="${basedir}/vendor/bin/phpmd"/>
<property name="composer" value="composer"/> <!-- composer should be installed global -->
<property name="phpunit" value="${basedir}/vendor/bin/phpunit"/>
<target name="full-build"
depends="prepare,composer,static-analysis,phpunit,phpdox,-check-failure"
depends="prepare,composer,static-analysis,phpunit,-check-failure"
description="Performs static analysis, runs the tests, and generates project documentation"/>
<target name="precommit"
depends="prepare,composer,phpunit,phpcbf,phpcs,phpcpd,phpmd"
description="Performs precommit checks"/>
<target name="full-build-parallel"
depends="prepare,composer,static-analysis-parallel,phpunit,phpdox,-check-failure"
depends="prepare,composer,static-analysis-parallel,phpunit,-check-failure"
description="Performs static analysis (executing the tools in parallel), runs the tests, and generates project documentation"/>
<target name="travis"
depends="prepare,lint,phpunit-travis"
depends="prepare,lint,phpunit,-check-failure"
description="Build specific for Travis CI" />
<target name="static-analysis"
@@ -77,7 +74,6 @@
<delete dir="${basedir}/build/coverage"/>
<delete dir="${basedir}/build/logs"/>
<delete dir="${basedir}/build/pdepend"/>
<delete dir="${basedir}/build/phpdox"/>
<property name="clean.done" value="true"/>
</target>
@@ -89,7 +85,6 @@
<mkdir dir="${basedir}/build/coverage"/>
<mkdir dir="${basedir}/build/logs"/>
<mkdir dir="${basedir}/build/pdepend"/>
<mkdir dir="${basedir}/build/phpdox"/>
<property name="prepare.done" value="true"/>
</target>
@@ -258,18 +253,6 @@
<property name="phpcpd.done" value="true"/>
</target>
<target name="phpunit-travis"
unless="phpunit.done"
depends="prepare"
description="Run unit tests with PHPUnit">
<exec executable="phpunit" resultproperty="result.phpunit" taskname="phpunit">
<arg value="--configuration"/>
<arg path="${basedir}/build/phpunit.xml"/>
</exec>
<property name="phpunit.done" value="true"/>
</target>
<target name="phpunit"
unless="phpunit.done"
depends="prepare"
@@ -301,15 +284,6 @@
<property name="phpunit.done" value="true"/>
</target>
<target name="phpdox"
unless="phpdox.done"
depends="phploc-ci,phpcs-ci,phpmd-ci"
description="Generate project documentation using phpDox">
<exec executable="${phpdox}" dir="${basedir}/build" taskname="phpdox"/>
<property name="phpdox.done" value="true"/>
</target>
<target name="-check-failure">
<fail message="PHPUnit did not finish successfully">
<condition>
View
@@ -10,20 +10,6 @@
<directory suffix="Test.php">../tests/</directory>
</testsuite>
</testsuites>
<listeners>
<listener class="JohnKary\PHPUnit\Listener\SpeedTrapListener">
<arguments>
<array>
<element key="slowThreshold">
<integer>500</integer>
</element>
<element key="reportLength">
<integer>5</integer>
</element>
</array>
</arguments>
</listener>
</listeners>
<filter>
<whitelist>
<directory>../src</directory>
Oops, something went wrong.

0 comments on commit a07c1f0

Please sign in to comment.