Skip to content

Commit 0fe985c

Browse files
srtabsrtab
authored
Merge pull request #7 from dipcode-software/feat/docs
Feat/docs
2 parents faa1454 + 3deaa83 commit 0fe985c

File tree

19 files changed

+363
-131
lines changed

19 files changed

+363
-131
lines changed

‎.editorconfig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ insert_final_newline = true
1313
trim_trailing_whitespace = true
1414

1515
# The JSON files contain newlines inconsistently
16-
[*.json]
16+
[*.json,*.yml]
1717
indent_size = 2
1818
insert_final_newline = ignore
1919

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,5 @@ composer.lock
55
*.sublime-project
66
*.sublime-workspace
77
/build
8+
env
9+
site

‎.travis.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ matrix:
1010
- php: nightly
1111

1212
before_script:
13-
- composer self-update
13+
- travis_retry composer self-update
1414

1515
install:
16-
- composer install --dev --no-interaction
16+
- travis_retry composer install --no-interaction
1717

1818
script:
1919
- mkdir -p build/logs

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
66

77
## [2.0.0] - 2017-12-11
88
### Added
9+
- Documentation of package;
910
- Renderers to facilitate integrations of template-engines:
1011
- Added `Renderer` interface;
1112
- Added `TwigRenderer` that integrates `twig/twig`;

‎README.md‎

Lines changed: 2 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# PHP Form
22
[![Build Status](https://travis-ci.org/dipcode-software/php-form.svg?branch=master)](https://travis-ci.org/dipcode-software/php-form)
33
[![Coverage Status](https://coveralls.io/repos/github/dipcode-software/php-form/badge.svg?branch=master)](https://coveralls.io/github/dipcode-software/php-form?branch=master)
4+
[![Latest Stable Version](https://poser.pugx.org/dipcode/php-form/v/stable)](https://packagist.org/packages/dipcode/php-form)
45
[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](http://www.opensource.org/licenses/MIT)
56

6-
PHP class for form handling abstraction inspired in Django Framework forms.
7+
Full featured form engine library inspired in Django Framework.
78

89
## Instalation
910
Library can be installed using Composer like so:
@@ -12,129 +13,6 @@ Library can be installed using Composer like so:
1213
$ composer require dipcode/php-form
1314
```
1415

15-
## Simple Example
16-
17-
Start by defining your form class like so:
18-
```php
19-
<?php
20-
namespace MyForms;
21-
22-
use PHPForm\Exceptions\ValidationError;
23-
use PHPForm\Fields\CharField;
24-
use PHPForm\Fields\EmailField;
25-
use PHPForm\Forms\Form;
26-
use PHPForm\Widgets\Textarea;
27-
28-
class ContactForm extends Form
29-
{
30-
protected static function setFields()
31-
{
32-
return array(
33-
'name' => new CharField(['required' => true]),
34-
'email' => new EmailField(['required' => true]),
35-
'subject' => new CharField(),
36-
'body' => new CharField(["widget" => Textarea::class])
37-
);
38-
}
39-
40-
protected function clean()
41-
{
42-
// Use this function to crossfields validation
43-
//
44-
// You can use $this->addError($message, $field_name) to add error messages to specific fields.
45-
// Or just throw a ValidationError Exception.
46-
}
47-
}
48-
```
49-
50-
Define the template to render form fields:
51-
```php
52-
<form action="/contact-form/" method="POST" novalidate>
53-
<div class="form-row">
54-
<div class="col">
55-
<?php echo $form['name']->label_tag; ?>
56-
<?php echo $form['name']; ?>
57-
<?php echo $form['name']->errors; ?>
58-
</div>
59-
<div class="col">
60-
<?php echo $form['email']->label_tag; ?>
61-
<?php echo $form['email']; ?>
62-
<?php echo $form['email']->errors; ?>
63-
</div>
64-
</div>
65-
<div class="form-row">
66-
<div class="col">
67-
<?php echo $form['subject']->label_tag; ?>
68-
<?php echo $form['subject']; ?>
69-
<?php echo $form['subject']->errors; ?>
70-
</div>
71-
</div>
72-
<div class="form-row">
73-
<div class="col">
74-
<?php echo $form['body']->label_tag; ?>
75-
<?php echo $form['body']; ?>
76-
<?php echo $form['body']->errors; ?>
77-
</div>
78-
</div>
79-
80-
<input type="submit" value="Submit">
81-
</form>
82-
```
83-
84-
Now process the form and force validation when `$_POST` data is sended:
85-
```php
86-
namespace MyViews;
87-
88-
use MyForms\ContactForm;
89-
90-
public function handleForm()
91-
{
92-
if (!empty($_POST)) {
93-
$form = new ContactForm(["data" => $_POST]);
94-
95-
if ($form->isValid()) {
96-
// Form is valid, do your logic here
97-
// Use can use $form->getCleanedData() to access cleaned and validated data.
98-
}
99-
100-
return $form;
101-
}
102-
103-
return new ContactForm();
104-
}
105-
```
106-
107-
## Available Fields
108-
109-
```php
110-
// All fields has the following common arguments:
111-
$args = [
112-
PHPForm\Widgets\Widget $widget,
113-
string $label = null,
114-
string $help_text = '',
115-
bool $required = false,
116-
bool $disabled = false,
117-
mixed $initial = null,
118-
array $validators = array(),
119-
array $widget_attrs = array(),
120-
array $error_messages = array()
121-
]
122-
123-
// Fields available
124-
// '...' represents common fields
125-
126-
new BooleanField([...]);
127-
new CharField([int $max_length, int $min_length, ...]);
128-
new ChoiceField([array $choices, ...]);
129-
new DateField([string $format, ...]);
130-
new DateTimeField([string $format, ...]);
131-
new EmailField([...]);
132-
new FileField([int $max_size, array $valid_filetypes, ...]);
133-
new IntegerField([int $max_value, int $min_value, ...]);
134-
new URLField([...]);
135-
136-
```
137-
13816
## Starting development
13917
Start by cloning the repo:
14018

‎composer.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@
1111
}
1212
],
1313
"support": {
14-
"issues": "https://github.com/dipcode-software/php-form/issues"
14+
"issues": "https://github.com/dipcode-software/php-form/issues",
15+
"docs": "https://alexandriadocs.io/docs/php-form/index.html"
1516
},
1617
"require": {
1718
"php": ">=7.0.0",

‎docs/deploy.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/bash
2+
3+
cd docs/
4+
source env/bin/activate && \
5+
pip install -r requirements.txt && \
6+
cd php-form && \
7+
mkdocs build && \
8+
tar -zcvf phpform.tar.gz -C site . && \
9+
curl -X POST -H "Content-Type: multipart/form-data" -H "Api-Key: ${1}" -F "archive=@phpform.tar.gz" https://alexandriadocs.io/api/v1/projects/upload/ && \
10+
rm phpform.tar.gz

‎docs/php-form/docs/fields.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Fields
2+
The fields available to construct the `Form` class are described in this page.
3+
Each field can has custom data formating and validation.
4+
5+
Field **attributes** must be passed based in an array:
6+
```php
7+
<?php
8+
use PHPForm\Fields\CharField;
9+
10+
new CharField(["label" => "Name", required => true]);
11+
```
12+
13+
## Core attributes
14+
All fields available takes at least this attributes.
15+
16+
### `string $widget`
17+
Define which `Widget` class will be used to render the field. See [widgets](widgets.md) for more info.
18+
19+
### `string $label`
20+
Human-friendly label used when displaying the field.
21+
22+
The default value is calculated based on the field name, transforming underscores into spaces and upper-casing the first letter.
23+
24+
### `string $help_text`
25+
26+
27+
### `bool $required`
28+
By default, the field assumes the value is not required. To make it required, you need to define it as true explicitly.
29+
30+
When is required, calling `clean()` with empty value will throw a `ValidationError` exception.
31+
32+
```php
33+
<?php
34+
use PHPForm\Fields\CharField;
35+
36+
$field = new CharField(["required" => true]);
37+
38+
// all this examples will throw:
39+
// PHPForm\Exceptions\ValidationError: This field is required.
40+
$field->clean("");
41+
$field->clean(" ");
42+
$field->clean(null);
43+
$field->clean(false);
44+
$field->clean(0);
45+
46+
// all this examples not
47+
echo $field->clean("value"); // "value"
48+
echo $field->clean(1); // "1"
49+
```
50+
51+
!!! info "empty"
52+
[empty](http://php.net/manual/en/function.empty.php) php function used to check *emptiness*.
53+
54+
### `bool $disabled`
55+
### `mixed $initial`
56+
### `array $validators`
57+
### `array $widget_attrs`
58+
### `array $error_messages`
59+
60+
## BooleanField
61+
62+
## CharField
63+
### `int $min_length`
64+
### `int $max_length`
65+
66+
## ChoiceField
67+
### `array $choices`
68+
69+
## DateField
70+
### `string $format`
71+
72+
## DateTimeField
73+
### `string $format`
74+
75+
## EmailField
76+
77+
## FileField
78+
### `int $max_size`
79+
### `array $valid_filetypes`
80+
81+
## IntegerField
82+
### `int $min_value`
83+
### `int $max_value`
84+
85+
## MultipleChoiceField
86+
### `array $choices`
87+
88+
## URLField

‎docs/php-form/docs/forms.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Forms

0 commit comments

Comments
 (0)