Nextcloud PHP API (master)

IRequest
in

Immutable request wrapper with accessors for request variables and other request-related data.

Request data should be retrieved through this interface whenever possible.

Parameters can be accessed through dedicated methods or via magic property access, for example:

$request->post['myvar']; // POST body parameters on POST requests $request->myvar; // merged request parameters

Magic access to a named parameter reads from the merged request parameter set. Method-specific properties such as get, post, put, and patch are only available for the matching HTTP method and may throw a \LogicException otherwise.

In PUT requests, if the body is JSON or form-encoded, ->put behaves like the other method-specific accessors and returns parsed request parameters. Otherwise, for non-empty request bodies, it returns a readable stream resource for the raw request body. Such streamed PUT bodies can only be accessed once; repeated access throws a \LogicException.

Tags
since
6.0.0

Table of Contents

Constants

JSON_CONTENT_TYPE_REGEX  : mixed = '/^application\/(?:[a-z0-9.-]+\+)?json\b/'
USER_AGENT_CLIENT_ANDROID  : mixed = '/^Mozilla\/5\.0 \(Android\) (?:ownCloud|Nextcl...
USER_AGENT_CLIENT_DESKTOP  : mixed = '/^Mozilla\/5\.0 \([A-Za-z ]+\) (?:mirall|csync...
USER_AGENT_CLIENT_IOS  : mixed = '/^Mozilla\/5\.0 \(iOS\) (?:ownCloud|Nextcloud)...
USER_AGENT_OUTLOOK_ADDON  : mixed = '/^Mozilla\/5\.0 \([A-Za-z ]+\) Nextcloud\-Outl...
USER_AGENT_TALK_ANDROID  : mixed = '/^Mozilla\/5\.0 \(Android\) Nextcloud\-Talk v(...
USER_AGENT_TALK_DESKTOP  : mixed = '/^Mozilla\/5\.0 \((?!Android|iOS)[A-Za-z ]+\)...
USER_AGENT_TALK_IOS  : mixed = '/^Mozilla\/5\.0 \(iOS\) Nextcloud\-Talk v([^ ]...
USER_AGENT_THUNDERBIRD_ADDON  : mixed = '/^Filelink for \*cloud\/([1-9]\d*\.\d+\.\d+)$/'

Properties

$get  : array<string, mixed>
$method  : string
$patch  : array<string, mixed>
$post  : array<string, mixed>
$put  : array<string, mixed>|resource
$server  : array<string, mixed>
$urlParams  : array<string|int, string>

Methods

getCookie()  : string|null
Returns a cookie value, if present.
getEnv()  : mixed|null
Returns an environment value from the request environment, if present.
getFormat()  : string|null
Returns the requested response format, if it can be determined.
getHeader()  : string
Returns the value of a request header, or an empty string if missing.
getHttpProtocol()  : string
Returns the HTTP protocol version used for the request.
getId()  : string
Returns a request identifier intended primarily for logging and tracing.
getInsecureServerHost()  : string
Returns the effective host value without validating it against the trusted domains configuration.
getMethod()  : string
Returns the request method.
getParam()  : mixed
Returns a parameter value from the merged parameter set.
getParams()  : array<string|int, mixed>
Returns the merged parameter set currently available on the request.
getPathInfo()  : string|false
Returns decoded path info from the request.
getRawPathInfo()  : string
Returns raw path info from the request without URL decoding.
getRemoteAddress()  : string
Returns the effective remote IP address.
getRequestUri()  : string
Returns the request URI, taking reverse-proxy and overwrite settings into account.
getScriptName()  : string
Returns the effective script name, taking reverse-proxy and overwrite settings into account.
getServerHost()  : string
Returns the validated effective server host.
getServerProtocol()  : string
Returns the effective server protocol.
getUploadedFile()  : array<string|int, mixed>|null
Returns an uploaded file entry from the `$_FILES` data, if present.
isUserAgent()  : bool
Checks whether the current user agent matches at least one of the given regular expressions.
passesCSRFCheck()  : bool
Checks whether the request passes CSRF validation.
passesLaxCookieCheck()  : bool
Checks whether the lax same-site cookie requirement is satisfied when session or authentication cookies are part of the request.
passesStrictCookieCheck()  : bool
Checks whether the strict same-site cookie requirement is satisfied when session or authentication cookies are part of the request.
throwDecodingExceptionIfAny()  : void
Throws any stored request-content decoding exception.

Constants

JSON_CONTENT_TYPE_REGEX

public mixed JSON_CONTENT_TYPE_REGEX = '/^application\/(?:[a-z0-9.-]+\+)?json\b/'
Tags
since
26.0.0

USER_AGENT_CLIENT_ANDROID

public mixed USER_AGENT_CLIENT_ANDROID = '/^Mozilla\/5\.0 \(Android\) (?:ownCloud|Nextcloud)\-android\/([^ ]*).*$/'
Tags
since
9.1.0
28.0.0

The regex has a group matching the version number

USER_AGENT_CLIENT_DESKTOP

public mixed USER_AGENT_CLIENT_DESKTOP = '/^Mozilla\/5\.0 \([A-Za-z ]+\) (?:mirall|csyncoC)\/([^ ]*).*$/'
Tags
since
9.1.0
28.0.0

The regex has a group matching the version number

USER_AGENT_CLIENT_IOS

public mixed USER_AGENT_CLIENT_IOS = '/^Mozilla\/5\.0 \(iOS\) (?:ownCloud|Nextcloud)\-iOS\/([^ ]*).*$/'
Tags
since
9.1.0
28.0.0

The regex has a group matching the version number

USER_AGENT_OUTLOOK_ADDON

public mixed USER_AGENT_OUTLOOK_ADDON = '/^Mozilla\/5\.0 \([A-Za-z ]+\) Nextcloud\-Outlook v([^ ]*).*$/'
Tags
since
13.0.1
28.0.0

The regex has a group matching the version number

USER_AGENT_TALK_ANDROID

public mixed USER_AGENT_TALK_ANDROID = '/^Mozilla\/5\.0 \(Android\) Nextcloud\-Talk v([^ ]*).*$/'
Tags
since
13.0.0
28.0.0

The regex has a group matching the version number

USER_AGENT_TALK_DESKTOP

public mixed USER_AGENT_TALK_DESKTOP = '/^Mozilla\/5\.0 \((?!Android|iOS)[A-Za-z ]+\) Nextcloud\-Talk v([^ ]*).*$/'
Tags
since
26.0.0
28.0.0

The regex has a group matching the version number

USER_AGENT_TALK_IOS

public mixed USER_AGENT_TALK_IOS = '/^Mozilla\/5\.0 \(iOS\) Nextcloud\-Talk v([^ ]*).*$/'
Tags
since
13.0.0
28.0.0

The regex has a group matching the version number

USER_AGENT_THUNDERBIRD_ADDON

public mixed USER_AGENT_THUNDERBIRD_ADDON = '/^Filelink for \*cloud\/([1-9]\d*\.\d+\.\d+)$/'
Tags
since
13.0.1
28.0.0

The regex has a group matching the version number

Properties

$get read-only

public array<string, mixed> $get

$patch read-only

public array<string, mixed> $patch

$post read-only

public array<string, mixed> $post

$put read-only

public array<string, mixed>|resource $put

$server read-only

public array<string, mixed> $server

$urlParams read-only

public array<string|int, string> $urlParams

Methods

getCookie()

Returns a cookie value, if present.

public getCookie(string $key) : string|null
Parameters
$key : string

the cookie name

Tags
psalm-taint-source

input

since
6.0.0
Return values
string|null —

the cookie value, or null if missing

getEnv()

Returns an environment value from the request environment, if present.

public getEnv(string $key) : mixed|null
Parameters
$key : string

the environment variable name

Tags
since
6.0.0
Return values
mixed|null —

the environment value, or null if missing

getFormat()

Returns the requested response format, if it can be determined.

public getFormat() : string|null

The format request parameter takes precedence. Otherwise the format may be inferred from the Accept header.

Tags
since
33.0.0
Return values
string|null

getHeader()

Returns the value of a request header, or an empty string if missing.

public getHeader(string $name) : string

Header names are matched case-insensitively.

Besides normal HTTP headers, also supports selected request-related server values such as REMOTE_ADDR.

Parameters
$name : string
Tags
psalm-taint-source

input

since
6.0.0
Return values
string

getHttpProtocol()

Returns the HTTP protocol version used for the request.

public getHttpProtocol() : string
Tags
since
8.2.0
Return values
string —

HTTP protocol, for example HTTP/2, HTTP/1.1, or HTTP/1.0

getId()

Returns a request identifier intended primarily for logging and tracing.

public getId() : string

The value is not guaranteed to be globally unique. If mod_unique_id is installed, that value may be used by the implementation.

Tags
since
8.1.0
Return values
string

getInsecureServerHost()

Returns the effective host value without validating it against the trusted domains configuration.

public getInsecureServerHost() : string

This may be derived from request headers, proxy headers, or server variables, depending on the deployment setup.

Tags
psalm-taint-source

input

since
8.1.0
Return values
string —

server host

getMethod()

Returns the request method.

public getMethod() : string
Tags
since
6.0.0
Return values
string —

the HTTP method, for example GET, POST, PUT, or PATCH

getParam()

Returns a parameter value from the merged parameter set.

public getParam(string $key[, mixed $default = null ]) : mixed

The merged parameter set is primarily composed from route URL parameters, POST parameters and GET parameters. Depending on request content type and prior access, lazily decoded request-body parameters may also be present.

Parameters
$key : string

the key to look up

$default : mixed = null

the value to return if the key is not found

Tags
psalm-taint-source

input

since
6.0.0
Return values
mixed —

the parameter value, or $default if the key is not present

getParams()

Returns the merged parameter set currently available on the request.

public getParams() : array<string|int, mixed>

This includes request parameters from GET, POST and route URL parameters, and may also include decoded request-body parameters.

Tags
psalm-taint-source

input

since
6.0.0
Return values
array<string|int, mixed> —

the merged parameters

getPathInfo()

Returns decoded path info from the request.

public getPathInfo() : string|false
Tags
psalm-taint-source

input

throws
Exception
since
8.1.0
Return values
string|false —

path info, or false when it cannot be determined

getRawPathInfo()

Returns raw path info from the request without URL decoding.

public getRawPathInfo() : string
Tags
psalm-taint-source

input

throws
Exception
since
8.1.0
Return values
string —

path info

getRemoteAddress()

Returns the effective remote IP address.

public getRemoteAddress() : string

If the connection comes from a trusted proxy and forwarded_for_headers is configured, the client IP from those forwarded headers is used instead.

Do not use $_SERVER['REMOTE_ADDR'] directly when this method is available.

Tags
since
8.1.0
Return values
string —

IP address

getRequestUri()

Returns the request URI, taking reverse-proxy and overwrite settings into account.

public getRequestUri() : string
Tags
psalm-taint-source

input

since
8.1.0
Return values
string

getScriptName()

Returns the effective script name, taking reverse-proxy and overwrite settings into account.

public getScriptName() : string
Tags
since
8.1.0
Return values
string —

the script name

getServerHost()

Returns the validated effective server host.

public getServerHost() : string

The implementation may use overwrite host configuration first. Otherwise it derives the host from the request and returns it only if it is trusted; if not, it falls back to the first configured trusted domain.

Tags
since
8.1.0
Return values
string —

server host

getServerProtocol()

Returns the effective server protocol.

public getServerProtocol() : string

Respects reverse proxies and load balancers. Precedence:

  1. overwriteprotocol config value
  2. X-Forwarded-Proto header value
  3. $_SERVER['HTTPS'] value

Invalid values fall back to http.

Tags
since
8.1.0
Return values
string —

Server protocol: http or https

getUploadedFile()

Returns an uploaded file entry from the `$_FILES` data, if present.

public getUploadedFile(string $key) : array<string|int, mixed>|null
Parameters
$key : string

the file field name

Tags
since
6.0.0
Return values
array<string|int, mixed>|null —

the matching uploaded file entry, or null if missing

isUserAgent()

Checks whether the current user agent matches at least one of the given regular expressions.

public isUserAgent(array<string|int, mixed> $agent) : bool
Parameters
$agent : array<string|int, mixed>

array of user-agent regex patterns

Tags
since
8.1.0
Return values
bool —

true if at least one pattern matches, false otherwise

passesCSRFCheck()

Checks whether the request passes CSRF validation.

public passesCSRFCheck() : bool

Depending on the request, this may include same-site cookie checks and token validation from request parameters or headers. OCS API requests are handled specially by the implementation (if the OCS-APIRequest header is included in the request).

Tags
since
6.0.0
Return values
bool —

true if the request passes CSRF validation

passesLaxCookieCheck()

Checks whether the lax same-site cookie requirement is satisfied when session or authentication cookies are part of the request.

public passesLaxCookieCheck() : bool
Tags
since
9.0.0
Return values
bool —

true if the lax cookie check passes

passesStrictCookieCheck()

Checks whether the strict same-site cookie requirement is satisfied when session or authentication cookies are part of the request.

public passesStrictCookieCheck() : bool
Tags
since
9.0.0
Return values
bool —

true if the strict cookie check passes

throwDecodingExceptionIfAny()

Throws any stored request-content decoding exception.

public throwDecodingExceptionIfAny() : void

Currently this is used for JSON decoding errors, but implementations may throw other decoding-related exceptions in the future.

Tags
throws
Exception
since
32.0.0
On this page

Search results