README
¶
form
database is a simple library that builds on top of gorilla/schema to allow for easy unmarshalling and validation of request data.
Quick start
To use the library, import it and define a new form into which request data can
be unmarshalled. Below is a simple example that unmarshals the request data into
the LoginForm and validates it.
type LoginForm struct {
Username string
Password string
}
func (f *LoginForm) Fields() form.Fields {
return form.Fields{
"username": f.Username,
}
}
func (f *LoginForm) Validate(ctx context.Context) error {
var v form.Validator
v.Add("username", f.Username, form.Required)
v.Add("password", f.Password, form.Required)
return v.Validate(ctx)
}
func LoginHandler(w http.ResponseWriter, r *http.Request) {
var f LoginForm
if err := form.UnmarshalAndValidate(r, &f); err != nil {
// Handle error.
}
// Handle the login.
}
Forms
Forms are represented via the form.Form interface which wraps two methods,
Fields- The fields of the form, this is used for flashing form data to the session.Validate- For validating the content of the form once it has been unmarshalled.
As long as a struct implements these methods, it can be used as a form and given to the [Unmarshal][] and [UnmarshalAndValidate][] functions.
Since this library is built on top of gorilla/schema, it makes use of the
schema struct tag to define which fields can be populated with request data,
type SignupForm struct {
Email string `schema:"email"`
Verified bool `schema:"-"`
}
File uploads
This library automatically handles unmarshalling of files from multipart/form-data requests. Each field in a struct that has the type of form.File will have the multipart file, or files, mapped to it, as long as there is a corresponding field in the request data for that file.
For example, assume an application is being built to handle file uploads that takes a single file, then the form implementation would look something like,
type UploadForm struct {
Attachment *form.File
}
func (f *UploadForm) Fields() form.Fields { return nil }
func (f *UploadForm) Validate(ctx context.Context) error {
var v form.Validator
v.Add("attachment", f.Attachment, form.Required)
return v.Validate(ctx)
}
with the above implementation, a handler can now be defined to handle the uploading of files,
func UploadHandler(w http.ResponseWriter, r *http.Request) {
var f UploadForm
if err := form.UnmarshalAndValidate(r, &f); err != nil {
// Handle error.
}
dst, err := os.Create(f.Attachment.Name())
if err != nil {
// Handle error.
}
defer dst.Close()
if _, err := io.Copy(dst, f.Attachment.Name()); err != nil {
// Handle error.
}
}
Multiple file uploads can be handled by simply defining a slice.
type UploadForm struct {
Attachments []*form.File
}
With this in place, the new handler would look like,
func StoreAttachment(f *form.File) error {
dst, err := os.Create(f.Name())
if err != nil {
return err
}
defer dst.Close()
_, err = io.Copy(dst, f.Name())
return err
}
func UploadHandler(w http.ResponseWriter, r *http.Request) {
var f UploadForm
if err := form.UnmarshalAndValidate(r, &f); err != nil {
// Handle error.
}
for _, f := range f.Attachments {
if err := StoreAttachment(f); err != nil {
// Handle error.
}
}
}
The form.File type implements the following interfaces,
Validation
Validation is done via the form.Validator type. This has an the Add method which takes the name of the field being validated, the value for that field, and the [Rules][] to apply to that field value. The Validate method is then used to execute all of the rules against the given form data. If any of the rules fail, then the form.Errors type is returned. This type is a map of errors and fields for which the error occured.
The form.Validator is used in the Validate method of form implementations to validate their inputs.
type SignupForm struct {
Email string
Username string
Password string
VerifyPassword string `schema:"verify_password"`
}
func (f *SignupForm) Validate(ctx context.Context) error {
var v form.Validator
v.Add("email", f.Email, form.Required, form.Email)
v.Add("username", f.Username, form.Required, form.Length(3, 32))
v.Add("password", f.Password, form.Required, form.Length(6, 60))
v.Add("verify_password", f.VerifyPassword, form.Required, form.Equals("password", f.Password))
return v.Validate(ctx)
}
A Rule is a function that takes a context, and the form value being validated.
type Rule func(ctx context.Context, val any) error
This library comes with the following rules out of the box,
- Required - Make sure the field is given a value.
- Matches - Make sure the field matches the given regex pattern.
- Email[[] - Make sure the field matches an email pattern.
- Length - Make sure the field is between the given length.
- Equals - Make sure the field is equal to another field's value.
Session flashing
It is common to want to flash the form data, along with the errors, upon validation errors so it can be displayed back to the user. This library makes use of gorilla/sessions to achieve easy flashing and retrieving of form data, via the form.Flash and form.Old functions.
In the following example a handler is setup for a signup page. This will flash the form and the errors to the session so that they can be retrieved to show to the user,
var (
hashKey = []byte(os.Getenv("HASH_KEY"))
blockKey = []byte(os.Getenv("BLOCK_KEY"))
store = sessions.NewFilesystemStore("", hashKey, blockKey)
)
func SignupHandler(w http.ResponseWriter, r *http.Request) {
sess, _ := store.Get(r, "session")
if r.Method == "POST" {
var f SignupForm
if err := form.UnmarshalAndValidate(r, &f); err != nil {
errs := make(form.Errors)
if errors.As(err, &errs) {
form.Flash(sess, &f, errs)
}
http.Redirect(w, r, r.Header.Get("Referer"), http.StatusSeeOther)
return
}
}
var (
f SignupForm
errs form.Errors = make(form.Errors)
)
form.Old(sess, &f, errs)
// Render form data and errors in a template back to the user.
}
Note: Because form.Errors contains the error interface, the underlying concrete type will be lost when flashed to the session and subsequently retrieved. This means that the individual error types cannot be inspected once retrieved via a call to form.Old.
Documentation
¶
Index ¶
- Variables
- func Email(ctx context.Context, val any) error
- func Flash(s *sessions.Session, f Form, errs Errors)
- func Old(sess *sessions.Session, f Form, errs Errors)
- func Required(_ context.Context, val any) error
- func Unmarshal(r *http.Request, f Form, opts ...Option) error
- func UnmarshalAndValidate(r *http.Request, f Form, opts ...Option) error
- type Converter
- type DecodeError
- type Decoder
- type Errors
- func (e Errors) Add(field string, err error)
- func (e Errors) Error() string
- func (e Errors) First(field string) error
- func (e Errors) Get(field string) []error
- func (e Errors) Is(target error) bool
- func (e Errors) MarshalJSON() ([]byte, error)
- func (e Errors) Merge(errs Errors)
- func (e Errors) UnmarshalJSON(b []byte) error
- type FieldEqualsError
- type Fields
- type File
- type Form
- type LengthError
- type MatchError
- type Option
- type Options
- type Rule
- type Validator
Constants ¶
This section is empty.
Variables ¶
var ErrEmailInvalid = errors.New("not a valid address")
var ErrFieldRequired = errors.New("field is required")
Functions ¶
func Email ¶
Email checks to see if the given value is an email address. This does a very simple pattern match to check for the presence of "@" in the string. Further validation of the email address itself should be done through the sending of a verification email.
func Flash ¶
Flash stores the given Form and Errors to the given session, which can then be retrieved via a subsequent call to Old.
func Old ¶
Old unmarshals the previous Form and Errors that could be found in the given session. If found, they will be deleted from the given session.
func Required ¶
Required checks to see if the given value was provided. If the value is a string, or returns a string via a call to String, then it will determine presence by whether or not that value is empty. If the value is a pointer then it is checked for nilness.
func Unmarshal ¶
Unmarshal parses the given request and unmarshals the data into the given form. If the given request has the Content-Type of application/json, then it will be decoded as such. If the given request has the Content-Type of multipart/form-data, then [net.http.Request.ParseMultipartForm] is called, otherwise [net.http.Request.ParseForm] is called.
Types ¶
type DecodeError ¶
func (DecodeError) Error ¶
func (e DecodeError) Error() string
type Errors ¶
Errors contains the errors that occurred during the validation of a form. Each key in the map will be the field for which the errors occurred.
func (Errors) First ¶
First returns the first error that occurred for the named field. This returns nil if there is no error.
func (Errors) Get ¶
Get the errors that occurred for the named field. This returns nil if there are no errors.
func (Errors) MarshalJSON ¶
func (Errors) Merge ¶
Merge the given errors into the underlying set of errors. This will not merge in duplicates. That is, if an error exists in the given set being merged, and also exists in the underlying set, then it will not be added.
func (Errors) UnmarshalJSON ¶
type FieldEqualsError ¶
type FieldEqualsError string
func (FieldEqualsError) Error ¶
func (e FieldEqualsError) Error() string
type Fields ¶
Fields represents the fields in the form. This is the value that is stored in the session data when a form is flashed to the session. This should not contain sensitive data, such as passwords.
type File ¶
File is a wrapper around the underlying [mime.multipart.File] interface. This also implements the [io.fs.FileInfo] interface. This represents a multipart file that has been sent in a request.
func (*File) MarshalJSON ¶
type Form ¶
Form represents a form into which request data has been unmarshalled into. It wraps the Fields and Validate methods.
Fields returns the Fields type which should contain the fields of the form. This value is used for flashing data into the session.
Validate validates the form data itself. This should return the Errors type containing the errors, if any, that occurred during validation and for which field.
type LengthError ¶
func (LengthError) Error ¶
func (e LengthError) Error() string
func (LengthError) Is ¶
func (e LengthError) Is(target error) bool
type MatchError ¶
func (MatchError) Error ¶
func (e MatchError) Error() string
func (MatchError) Is ¶
func (e MatchError) Is(target error) bool
type Option ¶
type Option func(opts *Options)
func AliasTag ¶
AliasTag specifies the struct tag alias that should be used for mapping data to the struct fields. The default for this is "schema".
func IgnoreUnknownKeys ¶
func IgnoreUnknownKeys() Option
IgnoreUnknownKeys will ignore any keys that exist in the request data but do not exist in the struct being decoded into.
func RegisterConverter ¶
RegisterConverter registers a converter function for a custom type.
type Options ¶
type Options struct {
AliasTag string
IgnoreUnknownKeys bool
MaxSize int
Converters map[any]Converter
ZeroEmpty bool
}
Options are the decoder options that will be configured on the Decoder when decoding the request data. This will be configured via the Option function.
type Rule ¶
Rule is used for validating field values in a form.
func Equals ¶
Equals returns a Rule that checks to ensure the form value matches the given expected value. The given field is the name of the other form field the form value should match. This field value is returned as the FieldEqualsError type.
func Length ¶
Length returns a Rule that checks to ensure the form value is between the min and max length in size. If the form value is not of type string then this errors. If the value falls outside the given bounds then the error type of LengthError is returned.
Source Files