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
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 ]) : mixed
Parameters
$application : string

application id

$languageCode : string = null

language code, defaults to the current locale

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

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