Nextcloud PHP API (stable19)

Util

This class provides different helper functions to make the life of a developer easier

Tags
since
4.0.0

Table of Contents

DEBUG  = 0
ERROR  = 3
FATAL  = 4
INFO  = 1
WARN  = 2
$needUpgradeCache  : mixed
$shareManager  : mixed
\OCP\Share\IManager
$token  : string
Cached encrypted CSRF token. Some static unit-tests of ownCloud compare multiple OC_Template elements which invoke `callRegister`. If the value would not be cached these unit-tests would fail.
addHeader()  : mixed
Add a custom element to the header If $text is null then the element will be written as empty element.
addScript()  : mixed
add a javascript file
addStyle()  : mixed
add a css file
addTranslations()  : mixed
Add a translation JS file
callRegister()  : mixed
Register an get/post call. This is important to prevent CSRF attacks
computerFileSize()  : float
Make a computer file size (2 kB to 2048)
connectHook()  : bool
connects a function to a hook
emitHook()  : bool
Emits a signal. To get data from the slot use references!
encodePath()  : string
Public function to encode url parameters
freeSpace()  : int
Calculate free space left within user quota
getChannel()  : string
Get current update channel
getDefaultEmailAddress()  : string
Returns the default email address
getL10N()  : IL10N
get l10n object
getServerHostName()  : string
Returns the server host name without an eventual port number
getVersion()  : array
get the current installed version of Nextcloud
hasExtendedSupport()  : bool
humanFileSize()  : string
Make a human file size (2048 to 2 kB)
isDefaultExpireDateEnforced()  : bool
check if share API enforces a default expire date
isIe()  : bool
is this Internet explorer ?
isPublicLinkPasswordRequired()  : bool
check if a password is required for each public link
isSharingDisabledForUser()  : bool
check if sharing is disabled for the current user
isValidFileName()  : bool
Returns whether the given file name is valid
linkToAbsolute()  : string
Creates an absolute url to the given app and file.
linkToPublic()  : string
Creates an absolute url for public use
linkToRemote()  : string
Creates an absolute url for remote use.
maxUploadFilesize()  : int
calculates the maximum upload size respecting system settings, free space and user quota
mb_array_change_key_case()  : array
Returns an array with all keys from input lowercased or uppercased. Numbered indices are left as is.
naturalSortCompare()  : int
Compare two strings to provide a natural sort
needUpgrade()  : bool
Checks whether the current version needs upgrade.
recursiveArraySearch()  : mixed
performs a search in a nested array
sanitizeHTML()  : string|array
Used to sanitize HTML
setChannel()  : mixed
Set current update channel
uploadLimit()  : int
Calculate PHP upload limit
writeLog()  : mixed
write a message in the log

Constants

DEBUG

public mixed DEBUG = ""
Tags
deprecated
14.0.0

use \OCP\ILogger::DEBUG

ERROR

public mixed ERROR = 3
Tags
deprecated
14.0.0

use \OCP\ILogger::ERROR

FATAL

public mixed FATAL = 4
Tags
deprecated
14.0.0

use \OCP\ILogger::FATAL

INFO

public mixed INFO = 1
Tags
deprecated
14.0.0

use \OCP\ILogger::INFO

WARN

public mixed WARN = 2
Tags
deprecated
14.0.0

use \OCP\ILogger::WARN

Properties

$needUpgradeCache

protected static mixed $needUpgradeCache = null

$shareManager

\OCP\Share\IManager

private static mixed $shareManager

$token

Cached encrypted CSRF token. Some static unit-tests of ownCloud compare multiple OC_Template elements which invoke `callRegister`. If the value would not be cached these unit-tests would fail.

private static string $token = ''

Methods

addHeader()

Add a custom element to the header If $text is null then the element will be written as empty element.

public static addHeader(string $tag, array $attributes[, string $text = null ]) : mixed

So use "" to get a closing tag.

Parameters
$tag : string

tag name of the element

$attributes : array

array of attributes for the element

$text : string = null

the text content for the element

Tags
since
4.0.0
Return values
mixed —

addScript()

add a javascript file

public static addScript(string $application[, string $file = null ]) : mixed
Parameters
$application : string
$file : string = null
Tags
since
4.0.0
Return values
mixed —

addStyle()

add a css file

public static addStyle(string $application[, string $file = null ]) : mixed
Parameters
$application : string
$file : string = null
Tags
since
4.0.0
Return values
mixed —

addTranslations()

Add a translation JS file

public static addTranslations(string $application[, string $languageCode = null ]) : mixed
Parameters
$application : string

application id

$languageCode : string = null

language code, defaults to the current locale

Tags
since
8.0.0
Return values
mixed —

callRegister()

Register an get/post call. This is important to prevent CSRF attacks

public static callRegister() : mixed
Tags
since
4.5.0
Return values
mixed —

connectHook()

connects a function to a hook

public static connectHook(string $signalClass, string $signalName, string|object $slotClass, string $slotName) : bool
Parameters
$signalClass : string

class name of emitter

$signalName : string

name of signal

$slotClass : string|object

class name of slot

$slotName : string

name of slot

Tags
since
4.0.0
Return values
bool —

This function makes it very easy to connect to use hooks.

TODO: write example

emitHook()

Emits a signal. To get data from the slot use references!

public static emitHook(string $signalclass, string $signalname[, array $params = [] ]) : bool
Parameters
$signalclass : string

class name of emitter

$signalname : string

name of signal

$params : array = []

default: array() array with additional data

Tags
since
4.0.0
Return values
bool —

true if slots exists or false if not

TODO: write example

encodePath()

Public function to encode url parameters

public static encodePath(string $component) : string

This function is used to encode path to file before output. Encoding is done according to RFC 3986 with one exception: Character '/' is preserved as is.

Parameters
$component : string

part of URI to encode

Tags
since
6.0.0
Return values
string —

freeSpace()

Calculate free space left within user quota

public static freeSpace(string $dir) : int
Parameters
$dir : string

the current folder where the user currently operates

Tags
since
7.0.0
Return values
int —

number of bytes representing

getChannel()

Get current update channel

public static getChannel() : string
Tags
since
8.1.0
Return values
string —

getDefaultEmailAddress()

Returns the default email address

public static getDefaultEmailAddress(string $user_part) : string
Parameters
$user_part : string

the user part of the address

Tags
since
5.0.0
Return values
string —

the default email address

Assembles a default email address (using the server hostname and the given user part, and returns it Example: when given lostpassword-noreply as $user_part param, and is currently accessed via http(s)://example.com/, it would return 'lostpassword-noreply@example.com'

If the configuration value 'mail_from_address' is set in config.php, this value will override the $user_part that is passed to this function

getL10N()

get l10n object

public static getL10N(string $application[, string|null $language = null ]) : IL10N
Parameters
$application : string
$language : string|null = null
Tags
since
6.0.0
  • parameter $language was added in 8.0.0
Return values
IL10N —

getServerHostName()

Returns the server host name without an eventual port number

public static getServerHostName() : string
Tags
since
5.0.0
Return values
string —

the server hostname

getVersion()

get the current installed version of Nextcloud

public static getVersion() : array
Tags
since
4.0.0
Return values
array —

hasExtendedSupport()

public static hasExtendedSupport() : bool
Tags
since
17.0.0
Return values
bool —

humanFileSize()

Make a human file size (2048 to 2 kB)

public static humanFileSize(int $bytes) : string
Parameters
$bytes : int

file size in bytes

Tags
since
4.0.0
Return values
string —

a human readable file size

isDefaultExpireDateEnforced()

check if share API enforces a default expire date

public static isDefaultExpireDateEnforced() : bool
Tags
since
8.0.0
Return values
bool —

isIe()

is this Internet explorer ?

public static isIe() : bool
Tags
since
14.0.0
Return values
bool —

isPublicLinkPasswordRequired()

check if a password is required for each public link

public static isPublicLinkPasswordRequired() : bool
Tags
since
7.0.0
Return values
bool —

isSharingDisabledForUser()

check if sharing is disabled for the current user

public static isSharingDisabledForUser() : bool
Tags
since
7.0.0
deprecated
9.1.0

Use \OC::$server->getShareManager()->sharingDisabledForUser

Return values
bool —

isValidFileName()

Returns whether the given file name is valid

public static isValidFileName(string $file) : bool
Parameters
$file : string

file name to check

Tags
deprecated
8.1.0

use \OC\Files\View::verifyPath()

since
7.0.0
suppress

PhanDeprecatedFunction

Return values
bool —

true if the file name is valid, false otherwise

linkToAbsolute()

Creates an absolute url to the given app and file.

public static linkToAbsolute(string $app, string $file[, array $args = [] ]) : string
Parameters
$app : string

app

$file : string

file

$args : array = []

array with param=>value, will be appended to the returned url The value of $args will be urlencoded

Tags
since
4.0.0
  • parameter $args was added in 4.5.0
Return values
string —

the url

linkToPublic()

Creates an absolute url for public use

public static linkToPublic(string $service) : string
Parameters
$service : string

id

Tags
since
4.5.0
deprecated
15.0.0
  • use OCP\IURLGenerator
Return values
string —

the url

linkToRemote()

Creates an absolute url for remote use.

public static linkToRemote(string $service) : string
Parameters
$service : string

id

Tags
since
4.0.0
Return values
string —

the url

maxUploadFilesize()

calculates the maximum upload size respecting system settings, free space and user quota

public static maxUploadFilesize(string $dir[, int $free = null ]) : int
Parameters
$dir : string

the current folder where the user currently operates

$free : int = null

the number of bytes free on the storage holding $dir, if not set this will be received from the storage directly

Tags
since
5.0.0
Return values
int —

number of bytes representing

mb_array_change_key_case()

Returns an array with all keys from input lowercased or uppercased. Numbered indices are left as is.

public static mb_array_change_key_case(array $input[, int $case = MB_CASE_LOWER ][, string $encoding = 'UTF-8' ]) : array
Parameters
$input : array

The array to work on

$case : int = MB_CASE_LOWER

Either MB_CASE_UPPER or MB_CASE_LOWER (default)

$encoding : string = 'UTF-8'

The encoding parameter is the character encoding. Defaults to UTF-8

Tags
since
4.5.0
Return values
array —

naturalSortCompare()

Compare two strings to provide a natural sort

public static naturalSortCompare(string $a, string $b) : int
Parameters
$a : string

first string to compare

$b : string

second string to compare

Tags
since
7.0.0
Return values
int —

-1 if $b comes before $a, 1 if $a comes before $b or 0 if the strings are identical

needUpgrade()

Checks whether the current version needs upgrade.

public static needUpgrade() : bool
Tags
since
7.0.0
Return values
bool —

true if upgrade is needed, false otherwise

recursiveArraySearch()

performs a search in a nested array

public static recursiveArraySearch(array $haystack, string $needle[, mixed $index = null ]) : mixed
Parameters
$haystack : array

the array to be searched

$needle : string

the search string

$index : mixed = null

optional, only search this key name

Tags
since
4.5.0
deprecated
15.0.0
Return values
mixed —

the key of the matching field, otherwise false

sanitizeHTML()

Used to sanitize HTML

public static sanitizeHTML(string|array $value) : string|array

This function is used to sanitize HTML and should be applied on any string or array of strings before displaying it on a web page.

Parameters
$value : string|array
Tags
since
4.5.0
Return values
string|array —

an array of sanitized strings or a single sanitized string, depends on the input parameter.

setChannel()

Set current update channel

public static setChannel(string $channel) : mixed
Parameters
$channel : string
Tags
since
8.1.0
Return values
mixed —

uploadLimit()

Calculate PHP upload limit

public static uploadLimit() : int
Tags
since
7.0.0
Return values
int —

number of bytes representing

writeLog()

write a message in the log

public static writeLog(string $app, string $message, int $level) : mixed
Parameters
$app : string
$message : string
$level : int
Tags
since
4.0.0
deprecated
13.0.0

use log of \OCP\ILogger

Return values
mixed —

Search results