Nextcloud PHP API (master)

Util
in package

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

Tags
since
4.0.0

Table of Contents

Properties

$needUpgradeCache  : mixed
$scriptDeps  : array<string|int, mixed>
$scripts  : array<string|int, mixed>
$scriptsInit  : array<string|int, mixed>
$shareManager  : IManager|null
$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.

Methods

addHeader()  : mixed
Add a custom element to the header If $text is null then the element will be written as empty element.
addInitScript()  : void
Add a standalone init js file that is loaded for initialization
addScript()  : void
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()  : false|int|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|float
Calculate free space left within user quota
getChannel()  : string
Get current update channel
getDefaultEmailAddress()  : string
Returns the default email address
getForbiddenFileNameChars()  : array<string|int, string>
Get a list of characters forbidden in file names
getL10N()  : IL10N
get l10n object
getScripts()  : array<string|int, mixed>
Return the list of scripts injected to the page
getServerHostName()  : string
Returns the server host name without an eventual port number
getVersion()  : array<string|int, mixed>
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
isFunctionEnabled()  : bool
Check if a function is enabled in the php configuration
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.
linkToRemote()  : string
Creates an absolute url for remote use.
maxUploadFilesize()  : int|float
calculates the maximum upload size respecting system settings, free space and user quota
mb_array_change_key_case()  : array<string|int, mixed>
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.
numericToNumber()  : int|float
Converts string to int of float depending if it fits an int
recursiveArraySearch()  : mixed
performs a search in a nested array
sanitizeHTML()  : string|array<string|int, string>
Used to sanitize HTML
setChannel()  : mixed
Set current update channel
shortenMultibyteString()  : string
Sometimes a string has to be shortened to fit within a certain maximum data length in bytes. substr() you may break multibyte characters, because it operates on single byte level. mb_substr() operates on characters, so does not ensure that the shortened string satisfies the max length in bytes.
uploadLimit()  : int|float
Calculate PHP upload limit

Properties

$needUpgradeCache

protected static mixed $needUpgradeCache = null

$scriptDeps

private static array<string|int, mixed> $scriptDeps = []

$scripts

private static array<string|int, mixed> $scripts = []

$scriptsInit

private static array<string|int, mixed> $scriptsInit = []

$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<string|int, mixed> $attributes[, string $text = null ]) : mixed

So use "" to get a closing tag.

Parameters
$tag : string

tag name of the element

$attributes : array<string|int, mixed>

array of attributes for the element

$text : string = null

the text content for the element

Tags
since
4.0.0

addInitScript()

Add a standalone init js file that is loaded for initialization

public static addInitScript(string $application, string $file) : void

Be careful loading scripts using this method as they are loaded early and block the initial page rendering. They should not have dependencies on any other scripts than core-common and core-main.

Parameters
$application : string
$file : string
Tags
since
28.0.0

addScript()

add a javascript file

public static addScript(string $application[, string|null $file = null ][, string $afterAppId = 'core' ][, bool $prepend = false ]) : void
Parameters
$application : string
$file : string|null = null
$afterAppId : string = 'core'
$prepend : bool = false
Tags
since
4.0.0

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

addTranslations()

Add a translation JS file

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

application id

$languageCode : string = null

language code, defaults to the current locale

$init : bool = false

whether the translations should be loaded early or not

Tags
since
8.0.0

callRegister()

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

public static callRegister() : mixed
Tags
since
4.5.0

computerFileSize()

Make a computer file size (2 kB to 2048)

public static computerFileSize(string $str) : false|int|float
Parameters
$str : string

file size in a fancy format

Tags
since
4.0.0
Return values
false|int|float

a file size in bytes

Inspired by: https://www.php.net/manual/en/function.filesize.php#92418

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
deprecated
21.0.0

use \OCP\EventDispatcher\IEventDispatcher::addListener

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<string|int, mixed> $params = [] ]) : bool
Parameters
$signalclass : string

class name of emitter

$signalname : string

name of signal

$params : array<string|int, mixed> = []

default: array() array with additional data

Tags
since
4.0.0
deprecated
21.0.0

use \OCP\EventDispatcher\IEventDispatcher::dispatchTypedEvent

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|float
Parameters
$dir : string

the current folder where the user currently operates

Tags
since
7.0.0
Return values
int|float

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

getForbiddenFileNameChars()

Get a list of characters forbidden in file names

public static getForbiddenFileNameChars() : array<string|int, string>
Tags
since
29.0.0
Return values
array<string|int, string>

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

getScripts()

Return the list of scripts injected to the page

public static getScripts() : array<string|int, mixed>
Tags
since
24.0.0
Return values
array<string|int, mixed>

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<string|int, mixed>
Tags
since
4.0.0
Return values
array<string|int, mixed>

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|float $bytes) : string
Parameters
$bytes : int|float

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

isFunctionEnabled()

Check if a function is enabled in the php configuration

public static isFunctionEnabled(string $functionName) : bool
Parameters
$functionName : string
Tags
since
25.0.0
Return values
bool

isPublicLinkPasswordRequired()

Check if a password is required for each public link

public static isPublicLinkPasswordRequired([bool $checkGroupMembership = true ]) : bool
Parameters
$checkGroupMembership : bool = true

Check group membership exclusion

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->get(\OCP\Share\IManager::class)->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 OCP\Files\Storage\IStorage::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<string|int, mixed> $args = [] ]) : string
Parameters
$app : string

app

$file : string

file

$args : array<string|int, mixed> = []

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

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|float|null $free = null ]) : int|float
Parameters
$dir : string

the current folder where the user currently operates

$free : int|float|null = 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|float

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<string|int, mixed> $input[, int $case = MB_CASE_LOWER ][, string $encoding = 'UTF-8' ]) : array<string|int, mixed>
Parameters
$input : array<string|int, mixed>

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<string|int, mixed>

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

numericToNumber()

Converts string to int of float depending if it fits an int

public static numericToNumber(numeric-string|float|int $number) : int|float
Parameters
$number : numeric-string|float|int

numeric string

Tags
since
26.0.0
Return values
int|float

int if it fits, float if it is too big

recursiveArraySearch()

performs a search in a nested array

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

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<string|int, string> $value) : string|array<string|int, string>

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<string|int, string>
Tags
since
4.5.0
Return values
string|array<string|int, string>

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

shortenMultibyteString()

Sometimes a string has to be shortened to fit within a certain maximum data length in bytes. substr() you may break multibyte characters, because it operates on single byte level. mb_substr() operates on characters, so does not ensure that the shortened string satisfies the max length in bytes.

public static shortenMultibyteString(string $subject, int $dataLength[, int $accuracy = 5 ]) : string

For example, json_encode is messing with multibyte characters a lot, replacing them with something along "\u1234".

This function shortens the string with by $accuracy (-5) from $dataLength characters, until it fits within $dataLength bytes.

Parameters
$subject : string
$dataLength : int
$accuracy : int = 5
Tags
since
23.0.0
Return values
string

uploadLimit()

Calculate PHP upload limit

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

number of bytes representing


        
On this page

Search results