Skip to main content

HTTP Requests

The base FormRequest instance provides a variety of methods for examining the incoming HTTP request. FormRequest is built on top of FastifyRequest, this means you can access FastifyRequest methods and properties from the FormRequest instance.

You may also use Request, an alias of FormRequest.

Accessing The Request​

Formidable loads requests to route actions as first parameters by default:

app/Http/Controllers/TaskController.ts
import { Request } from '@formidablejs/framework'
import { Controller } from './Controller'

export class TaskController extends Controller {
    store(request: Request): void {
        const description: string = request.get('description')
    }
}

The request loaded by default, is the standard FormRequest class provided by the Formidable Framework.

To use a different FormRequest, you may use the @use decorator:

app/Http/Controllers/TaskController.ts
import { use } from '@formidablejs/ts-ports'
import { StoreTaskRequest } from '../Requests/StoreTaskRequest'
import { Controller } from './Controller'

export class TaskController extends Controller {
    @use(StoreTaskRequest)
    store(request: StoreTaskRequest): void {
        const description: string = request.get('description')
    }
}

This, will use the StoreTaskRequest request instead.

Request Host & Origin​

Retrieving The Request Host​

The getHost method returns the request's host:

const host: string = request.getHost()

Retrieving The Request Origin​

The getOrigin method returns the request's origin:

const origin: string = request.getOrigin()

You may also use the getFullOrigin method to retrieve the full origin including the protocol:

const fullOrigin: string = request.getFullOrigin()

Retrieving The Request Origin protocol​

The getOriginProtocol method returns the request's protocol:

const protocol: string = request.getOriginProtocol()

Request Path, Param & Method​

Retrieving The Request Url​

The url method returns the request's path. So, if the incoming request is targeted at http://example.com/tasks/store, the url method will return tasks/store:

const uri = request.url()

Inspecting The Request Url / Path / Route​

The isUrl method allows you to verify that the incoming request path matches a given url:

if (request.isUrl('tasks/store')) {
    // do somthing
}

You may also use pathIs. You may use the * character as a wildcard when utilizing this method:

if (request.pathIs('tasks/*')) {
    // do somthing
}

Using the isRoute method, you may determine if the incoming request has matched a named route. You may use the * character as a wildcard when utilizing this method:

if (request.isRoute('tasks.*')) {
    // do something
}

Retrieving The Request URL​

To retrieve the full URL for the incoming request you may use the url, urlWithoutQuery or fullUrl methods. The url method will return the path with the query string, the urlWithoutQuery method will return the URL without the query string, and the fullUrl method will return the host, the path and the query string:

const url: string = request.url()

const urlWithoutQueryString: string = request.urlWithoutQuery()

const fullUrl: string = request.fullUrl()

Retrieving Route Parameters​

To retrieve a route parameter from the incoming request you may use the param method. The param method accepts a parameter name:

const slug: string|null = request.param('slug')

To retrieve all route parameters, you may use the params method:

const params: object = request.params()

Retrieving The Request Method​

The method method will return the HTTP verb for the request. You may use the isMethod method to verify that the HTTP verb matches a given string:

const method: string = request.method()

if (request.isMethod('POST')) {
    // do something
}

Request Headers​

You may retrieve a request header from the FormRequest instance using the header method. If the header is not present on the request, null will be returned. However, the header method accepts an optional second argument that will be returned if the header is not present on the request:

const value: string|null = request.header('header-name')

const value: string = request.header('header-name', 'default')

The hasHeader method may be used to determine if the request contains a given header:

if (request.hasHeader('header-name')) {
    // do something
}

For convenience, the bearerToken method may be used to retrieve a bearer token from the Authorization header. If no such header is present, an empty string will be returned:

const token: string|null = request.bearerToken()

Request IP Address​

The ip method may be used to retrieve the IP address of the client that made the request to your application:

const ipAddress: string = request.ip()

Input​

Retrieving Input​

Retrieving All Input Data​

You may retrieve all of the incoming request's input data as an object using the all method:

const input: object = request.all()

Retrieving An Input Value​

Using a few simple methods, you may access all of the user input from your FormRequest instance without worrying about which HTTP verb was used for the request. Regardless of the HTTP verb, the input method may be used to retrieve user input:

const name: string|null = request.input('name')

You may pass a default value as the second argument to the input method. This value will be returned if the requested input value is not present on the request:

const name: string = request.input('name', 'Luna')

You may call the input method without any arguments in order to retrieve all of the input values as an object:

const input: object = request.input()

Retrieving Input From The Query String​

While the input method retrieves values from the entire request payload (including the query string), the query method will only retrieve values from the query string:

const name: string|null = request.name('name')

If the requested query string value data is not present, the second argument to this method will be returned:

const name: string = request.name('name', 'Luna')

You may call the query method without any arguments in order to retrieve all of the query string values as an object:

const query: object = request.query()

Retrieving A Portion Of The Input Data​

If you need to retrieve a subset of the input data, you may use the only method. This method accepts an array:

const input: object = request.only(['email', 'password'])

Retrieving Input From The Input Data And The Query String​

If you are expecting data from both the query string data and input data, you may use the get method. Note, input data takes first preference over the query string:

const name: string|null = request.get('name')

If the requested query string value data or input data is not present, the second argument to this method will be returned:

const name: string = request.get('name', 'Luna')

Determining If Input Is Present​

You may use the has method to determine if a value is present on the request. The has method returns true if the value is present on the request:

if(request.has('name')) {
    // do something
}

Type-safe​

When using TypeScript, you may generate types based on your request rules. You may do this for the purpose of type-hinting your request within your forms. This works with Imba (SPA), Vue, React, and Svelte.

info

This feature is only available when using TypeScript as the default language and nodemon as the default development mode.

Generating Types​

To generate types, you may use the types:generate Craftsman command:

node craftsman types:generate

This command will generate types for all of your request rules. The generated types will be placed in the app/Types/Forms directory.

Using Generated Types​

Once you have generated your types, you may use them in your frontend forms. For example, let's assume we have a StorePersonRequest class that contains the following rules:

app/Http/Requests/StorePersonRequest.ts
import { Request } from '@formidablejs/framework'

export class StorePersonRequest extends Request {
    rules() {
        return {
            first_name: 'required|string',
            last_name: 'required|string',
            email: 'required|email',
            phone: 'nullable|string',
            address: 'nullable|string',
        }
    }
}

After running the types:generate command, we will have a StorePersonForm type generated in the app/Types/Forms directory:

app/Types/Forms/StorePersonForm.ts
type StorePersonForm = {
    first_name: string
    last_name: string
    email: string
    phone: string | null
    address: string | null
}

We may now use this type in our frontend form:

Create a Create.vue file in the resources/js/Pages/People directory:

resources/js/Pages/People/Create.vue
<script lang="ts" setup>
import { useForm } from '@inertia/vue3'

const form = useForm<StorePersonForm>({
    first_name: '',
    last_name: '',
    email: '',
    phone: null,
    address: null
})
</script>

...

Auto-generation​

You may also generate types automatically when you run the serve command with the --dev flag. You can do this by adding the node craftsman types:generate command to your package.json file under development.commands:

package.json
{
    "development": {
        "mode": "nodemon",
        "commands": [
            "node craftsman types:generate",
        ]
    }
}

This will generate types for all of your request rules whenever you make changes to your application.