Nextcloud PHP API (master)

Principal
in package
implements JsonSerializable

Read onlyYes
FinalYes

A principal defines the identity of an actor.

It specifies who the actor is and where that identity lives.

Tags
psalm-type

PrincipalData = array{type: non-empty-string, id: non-empty-string, origin: ?non-empty-string, source: ?non-empty-string}

psalm-immutable
since
36.0.0
Attributes
#[Consumable]
$since: '36.0.0'

Table of Contents

Interfaces

JsonSerializable

Properties

$id  : string
$origin  : non-empty-string|null
Remote instance for federated users, optional visitor id within the scope for anonymous users, null otherwise
$source  : string|null
$type  : PrincipalType

Methods

anonymous()  : self
Identifies an anonymous user, e.g. a public visitor of a public share.
bot()  : self
Identifies a bot, e.g. a Talk bot or the assistant.
equals()  : bool
fromArray()  : self
Rehydrate from a serialized payload.
jsonSerialize()  : PrincipalData
key()  : string
Stable key for logs and cache keys
system()  : self
Identifies a system component.
user()  : self
Identifies a local or federated user.
__construct()  : mixed
assertValidData()  : void
escapeKeyPart()  : string
normalizeRemote()  : string
Remove the trailing slash and the "https://" scheme, keeping an explicit "http://" as cloud ids do
validateAnonymousKind()  : void
Verify the given anonymous kind is of the form `appid:kind`, the kind consisting of lowercase alphanumerics, `_` and `-`
validateAppId()  : void
Verify the given app id is well-formed, without checking whether the app is installed or enabled

Properties

$origin

Remote instance for federated users, optional visitor id within the scope for anonymous users, null otherwise

public non-empty-string|null $origin
Tags
since
36.0.0

Methods

anonymous()

Identifies an anonymous user, e.g. a public visitor of a public share.

public static anonymous(non-empty-string $scope, non-empty-string $source[, non-empty-string|null $visitorId = null ]) : self
Parameters
$scope : non-empty-string
  • what the anonymous user was granted access through, e.g. a share token, a Talk room token or a form hash
$source : non-empty-string
  • app-namespaced kind of anonymous user, e.g. files_sharing:visitor or spreed:guest
$visitorId : non-empty-string|null = null
  • stable id of the visitor within the scope, e.g. a Talk guest id or a session id; never the nickname
Tags
throws
InvalidArgumentException
  • if the source is not of the form appid:kind
since
36.0.0
Return values
self

bot()

Identifies a bot, e.g. a Talk bot or the assistant.

public static bot(non-empty-string $botId, non-empty-string $appId) : self
Parameters
$botId : non-empty-string
  • bot id, unique within the owning app
$appId : non-empty-string
  • app owning the bot, e.g. "spreed"
Tags
throws
InvalidArgumentException
  • if the app id is not valid
since
36.0.0
Return values
self

equals()

public equals(self $other) : bool
Parameters
$other : self
Tags
since
36.0.0
Return values
bool

fromArray()

Rehydrate from a serialized payload.

public static fromArray(array<string, mixed> $data) : self

Payloads written by a newer server version may contain principal types unknown to this version, callers reading stored payloads must handle the exception.

Parameters
$data : array<string, mixed>
  • see Principal::jsonSerialize
Tags
throws
InvalidArgumentException

if the data is invalid or the type is unknown

since
36.0.0
Return values
self

jsonSerialize()

public jsonSerialize() : PrincipalData
Tags
since
36.0.0
Attributes
#[Override]
Return values
PrincipalData

key()

Stable key for logs and cache keys

public key() : string

e.g. a federated user: user|bob@cloud.example an anonymous visitor of a public share: anonymous|sharetoken|files_sharing:visitor a Talk guest: anonymous|roomtoken@guestid|spreed:guest or a system component: system|retention|files_versions

The delimiters |, @ and # are percent-encoded within the parts, e.g. the local user "bob@cloud.example": user|bob%40cloud.example

Tags
since
36.0.0
Return values
string

system()

Identifies a system component.

public static system(non-empty-string $component, non-empty-string $appId) : self

e.g. the "retention" component of the "files_versions" app: Principal::system('retention', 'files_versions')

Parameters
$component : non-empty-string
  • component name, unique within the owning app
$appId : non-empty-string
  • app owning the component, or "core" for server components
Tags
throws
InvalidArgumentException
  • if the app id is not valid
since
36.0.0
Return values
self

user()

Identifies a local or federated user.

public static user(non-empty-string $userId[, non-empty-string|null $remote = null ]) : self
Parameters
$userId : non-empty-string
  • user id
$remote : non-empty-string|null = null
  • remote instance for federated users, null for local users; a trailing slash and the "https://" scheme are removed, as in cloud ids
Tags
since
36.0.0
Return values
self

__construct()

private __construct(PrincipalType $type, non-empty-string $id[, non-empty-string|null $origin = null ][, non-empty-string|null $source = null ]) : mixed
Parameters
$type : PrincipalType
$id : non-empty-string
  • user id, scope of anonymous users, bot id or component name of a system principal
$origin : non-empty-string|null = null
  • see Principal::$origin
$source : non-empty-string|null = null
  • app owning the principal: appid:kind for anonymous users, e.g. "spreed:guest", the app id for bots and system components, e.g. "spreed"; null for users

assertValidData()

private static assertValidData(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>
Tags
psalm-assert

array{type: non-empty-string, id: non-empty-string, origin?: ?non-empty-string, source?: ?non-empty-string} $data

throws
InvalidArgumentException
  • if the data is invalid

escapeKeyPart()

private static escapeKeyPart(string $part) : string
Parameters
$part : string
Tags
psalm-pure
Return values
string

normalizeRemote()

Remove the trailing slash and the "https://" scheme, keeping an explicit "http://" as cloud ids do

private static normalizeRemote(string $remote) : string
Parameters
$remote : string
Return values
string

validateAnonymousKind()

Verify the given anonymous kind is of the form `appid:kind`, the kind consisting of lowercase alphanumerics, `_` and `-`

private static validateAnonymousKind(string $kind) : void
Parameters
$kind : string
Tags
throws
InvalidArgumentException
  • If the kind is invalid

validateAppId()

Verify the given app id is well-formed, without checking whether the app is installed or enabled

private static validateAppId(non-empty-string $appId) : void
Parameters
$appId : non-empty-string
  • app id to validate
Tags
throws
InvalidArgumentException
  • If the app id is invalid
On this page

Search results