Documentation

Obtaining the Request Object

Webman will automatically inject the request object into the first parameter of the action method, for example:

Example

<?php
namespace app\controller;

use support\Request;

class UserController
{
    public function hello(Request $request)
    {
        $default_name = 'webman';
        // Get the 'name' parameter from the get request, or return $default_name if the parameter is not passed
        $name = $request->get('name', $default_name);
        // Return a string to the browser
        return response('hello ' . $name);
    }
}

Through the $request object, we can obtain any data related to the request.

Sometimes we may want to get the $request object in other classes, in which case we can use the helper function request()

Getting request parameters from get

Get the entire get array

$request->get();

If the request does not contain get parameters, it returns an empty array.

Get a value from the get array

$request->get('name');

If the get array does not contain this value, it returns null.

You can also pass a default value as the second parameter to the get method. If the corresponding value is not found in the get array, it will return the default value. For example:

$request->get('name', 'tom');

Getting request parameters from post

Get the entire post array

$request->post();

If the request does not contain post parameters, it returns an empty array.

Get a value from the post array

$request->post('name');

If the post array does not contain this value, it returns null.

Similar to the get method, you can also pass a default value as the second parameter to the post method. If the corresponding value is not found in the post array, it will return the default value. For example:

$request->post('name', 'tom');

Helper Function input()

Similar to $request->input(), the input() helper can retrieve all parameters. It accepts two parameters:

  1. name: The name of the parameter to retrieve (if empty, returns an array of all parameters)
  2. default: Default value (used when the parameter from the first argument is not found)

Example

// Get parameter name
$name = input('name');
// Get parameter name, use default value if not present
$name = input('name', 'John');
// Get all parameters
$all_params = input();

Getting the Raw Request Body

$post = $request->rawBody();

This function is similar to the file_get_contents("php://input") operation in php-fpm. It is used to obtain the raw HTTP request body, which is very useful when obtaining post request data in a non-application/x-www-form-urlencoded format.

Getting header

Get the entire header array

$request->header();

If the request does not contain header parameters, it returns an empty array. Note that all keys are lowercase.

Get a value from the header array

$request->header('host');

If the header array does not contain this value, it returns null. Note that all keys are lowercase.

Similar to the get method, you can also pass a default value as the second parameter to the header method. If the corresponding value is not found in the header array, it will return the default value. For example:

$request->header('host', 'localhost');

Getting cookie

Get the entire cookie array

$request->cookie();

If the request does not contain cookie parameters, it returns an empty array.

Get a value from the cookie array

$request->cookie('name');

If the cookie array does not contain this value, it returns null.

Similar to the get method, you can also pass a default value as the second parameter to the cookie method. If the corresponding value is not found in the cookie array, it will return the default value. For example:

$request->cookie('name', 'tom');

Getting all inputs

Includes the collection of post and get.

$request->all();

Getting a specific input value

Get a value from the collection of post and get.

$request->input('name', $default_value);

Getting partial input data

Get part of the data from the collection of post and get.

// Get an array of username and password, ignoring the key if it does not exist
$only = $request->only(['username', 'password']);
// Get all inputs except 'avatar' and 'age'
$except = $request->except(['avatar', 'age']);

Getting Input via Controller Parameters

<?php
namespace app\controller;
use support\Response;

class UserController
{
    public function create(string $name, int $age = 18): Response
    {
        return json(['name' => $name, 'age' => $age]);
    }
}

The logic above is equivalent to:

<?php
namespace app\controller;
use support\Request;
use support\Response;

class UserController
{
    public function create(Request $request): Response
    {
        $name = $request->input('name');
        $age = (int)$request->input('age', 18);
        return json(['name' => $name, 'age' => $age]);
    }
}

For more information, see Controller Parameter Binding.

Getting Uploaded Files

Note
File uploads require forms with multipart/form-data encoding.

Get the entire uploaded file array

$request->file();

Form example:

<form method="post" action="http://127.0.0.1:8787/upload/files" enctype="multipart/form-data">
<input name="file1" multiple="multiple" type="file">
<input name="file2" multiple="multiple" type="file">
<input type="submit">
</form>

The format returned by $request->file() is similar to the following:

array (
    'file1' => object(webman\Http\UploadFile),
    'file2' => object(webman\Http\UploadFile)
)

It is an array of instances of webman\Http\UploadFile. The webman\Http\UploadFile class inherits the native PHP SplFileInfo class and provides some practical methods.

<?php
namespace app\controller;

use support\Request;

class UploadController
{
    public function files(Request $request)
    {
        foreach ($request->file() as $key => $spl_file) {
            var_export($spl_file->isValid()); // Whether the file is valid, for example true|false
            var_export($spl_file->getUploadExtension()); // Uploaded file extension, for example 'jpg'
            var_export($spl_file->getUploadMimeType()); // Uploaded file MIME type, for example 'image/jpeg'
            var_export($spl_file->getUploadErrorCode()); // Get the upload error code, for example UPLOAD_ERR_NO_TMP_DIR UPLOAD_ERR_NO_FILE UPLOAD_ERR_CANT_WRITE
            var_export($spl_file->getUploadName()); // Uploaded file name, for example 'my-test.jpg'
            var_export($spl_file->getSize()); // Get file size, for example 13364, in bytes
            var_export($spl_file->getPath()); // Get the upload directory, for example '/tmp'
            var_export($spl_file->getRealPath()); // Get the temporary file path, for example `/tmp/workerman.upload.SRliMu`
        }
        return response('ok');
    }
}

Note:

  • The file will be renamed to a temporary file after upload, similar to /tmp/workerman.upload.SRliMu
  • The uploaded file size is limited by defaultMaxPackageSize, which is 10M by default and can be changed in the config/server.php file by modifying max_package_size.
  • The temporary files will be automatically cleared after the request ends
  • If there are no uploaded files in the request, $request->file() returns an empty array
  • The uploaded files do not support the move_uploaded_file() method, please use the $file->move() method instead, as shown in the example below

Getting a specific uploaded file

$request->file('avatar');

If the file exists, it returns the corresponding file's instance of webman\Http\UploadFile, otherwise it returns null.

Example

<?php
namespace app\controller;

use support\Request;

class UploadController
{
    public function file(Request $request)
    {
        $file = $request->file('avatar');
        if ($file && $file->isValid()) {
            $file->move(public_path().'/files/myfile.'.$file->getUploadExtension());
            return json(['code' => 0, 'msg' => 'upload success']);
        }
        return json(['code' => 1, 'msg' => 'file not found']);
    }
}

Getting host

Get the host information of the request.

$request->host();

If the request address is non-standard, i.e., not on port 80 or 443, the host information may include the port, for example, example.com:8080. If the port information is not needed, the first parameter can be set to true.

$request->host(true);

Getting the request method

 $request->method();

The return value may be one of GET, POST, PUT, DELETE, OPTIONS, or HEAD.

Getting the request URI

$request->uri();

Returns the URI of the request, including the path and query string parts.

Getting the request path

$request->path();

Returns the path part of the request.

Getting the request query string

$request->queryString();

Returns the query string part of the request.

Getting request URL

The url() method returns the URL without Query parameters.

$request->url();

It returns something like //www.workerman.net/workerman-chat.

The fullUrl() method returns the URL with Query parameters.

$request->fullUrl();

It returns something like //www.workerman.net/workerman-chat?type=download.

Note
url() and fullUrl() do not include the protocol part (neither http nor https). This is because using //example.com in the browser will automatically recognize the current site's protocol and send the request using either http or https.

If you are using an nginx proxy, add proxy_set_header X-Forwarded-Proto $scheme; to the nginx configuration, refer to nginx proxy. This way, you can use $request->header('x-forwarded-proto'); to determine whether it is http or https, for example:

echo $request->header('x-forwarded-proto'); // outputs http or https

Getting request HTTP version

$request->protocolVersion();

Returns a string 1.1 or 1.0.

Getting request session ID

$request->sessionId();

Returns a string consisting of letters and numbers.

Getting client's IP address

$request->getRemoteIp();

Getting client's port

$request->getRemotePort();

Getting client's real IP address

$request->getRealIp($safe_mode = true);

When the project is using a proxy (such as nginx), using $request->getRemoteIp() often returns the proxy server's IP (like 127.0.0.1 or 192.168.x.x) instead of the client's real IP. In such cases, you can try using $request->getRealIp() to obtain the client's real IP.

$request->getRealIp() will attempt to obtain the real IP from the x-forwarded-for, x-real-ip, client-ip, x-client-ip, and via fields in the HTTP header.

Since HTTP headers can be easily spoofed, the client IP obtained from this method is not 100% reliable, especially when $safe_mode is set to false. A more reliable method for obtaining the client's real IP through a proxy is to know the secure proxy server IP and explicitly know which HTTP header carries the real IP. If the IP returned by $request->getRemoteIp() confirms a known secure proxy server, then use $request->header('Header carrying the real IP') to obtain the real IP.

Getting server's IP address

$request->getLocalIp();

Getting server's port

$request->getLocalPort();

Checking if it is an AJAX request

$request->isAjax();

Checking if it is a PJAX request

$request->isPjax();

Checking if it expects JSON response

$request->expectsJson();

Checking if the client accepts JSON response

$request->acceptJson();

Getting the Requested Plugin Name

Returns an empty string '' for non-plugin requests.

$request->plugin;

Getting the Requested Application Name

Returns an empty string '' for single applications, and the application name for multiple applications.

$request->app;

Because closures do not belong to any application, the request from a closure route will always return an empty string ''.
Refer to Route for closure routes.

Getting the requested controller class name

Gets the class name corresponding to the controller

$request->controller;

Returns something like app\controller\IndexController.

Because closures do not belong to any controller, the request from a closure route will always return an empty string ''.
Refer to Route for closure routes.

Getting the Requested Method Name

Gets the method name corresponding to the request's controller method

$request->action;

Returns something like index.

Because closures do not belong to any controller, the request from a closure route will always return an empty string ''.
Refer to Route for closure routes.

Overwriting Parameters

Sometimes we need to overwrite request parameters, for example to filter the request and reassign values to the request object. In such cases, we can use the setGet(), setPost(), and setHeader() methods.

Overwriting GET Parameters

$request->get(); // Assume result is ['name' => 'tom', 'age' => 18]
$request->setGet(['name' => 'tom']);
$request->get(); // Final result is ['name' => 'tom']

Note
As shown in the example, setGet() overwrites all GET parameters. setPost() and setHeader() behave the same way.

Overwriting POST Parameters

$post = $request->post();
foreach ($post as $key => $value) {
    $post[$key] = htmlspecialchars($value);
}
$request->setPost($post);
$request->post(); // Get filtered post parameters

Overwriting HEADER Parameters

$request->setHeader(['host' => 'example.com']);
$request->header('host'); // Output: example.com