Nextcloud PHP API (stable18)

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 = array() ]) : bool
Parameters
$signalclass : string

class name of emitter

$signalname : string

name of signal

$params : array = 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 = array() ]) : string
Parameters
$app : string

app

$file : string

file

$args : array = 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