Oihana Php Schema

Role extends WebAPI

Represents a Role resource within an OAuth2 and RBAC (Role-Based Access Control) context.

This class extends the Schema.org WebAPI type to describe an authorization role entity that groups a set of permissions and users. It integrates seamlessly with Casbin-based access control models, where roles define collections of permissions granted to specific users.

Features

Permissions management — Each role can include one or more Permission objects.
User assignment — A role can be linked to multiple users.
Counting properties — Provides quick access to the number of permissions or users attached.
Hydration via attributes — Uses the #[HydrateWith] attribute for reflective object construction.

Example

use xyz\oihana\schema\auth\Role;
use xyz\oihana\schema\auth\Permission;

$role = new Role();
$role->permissions = [
    new Permission(subject: 'admin', domain: 'project', action: 'read'),
    new Permission(subject: 'admin', domain: 'project', action: 'write'),
];
$role->permissionsCount = count($role->permissions);

$role->users = ['user:123', 'user:456'];
$role->usersCount = count($role->users);

Notes

Roles can be linked to APIs or services defined by WebAPI.
The $permissions and $users arrays can be hydrated automatically using reflection when deserializing from structured data.

Constants

CONTEXT = \xyz\oihana\schema\constants\Oihana::SCHEMA: The @context of the json-ld representation of the thing.
DEFAULT_ALGORITHM = \xyz\oihana\schema\constants\JWTAlgorithm::RS256: The default JSON Web Token (JWT) Signing Algorithm.
DEFAULT_IMPLICIT_HYBRID_TOKEN_LIFETIME = 7200: The default Implicit/Hybrid Flow Access Token Lifetime value in seconds.
DEFAULT_TOKEN_EXPIRATION = 86400: The default Maximum Access Token Lifetime value in seconds.
JSON_PRIORITY_KEYS = [\org\schema\constants\Schema::AT_TYPE, \org\schema\constants\Schema::AT_CONTEXT, \org\schema\constants\Schema::_KEY, \org\schema\constants\Schema::_FROM, \org\schema\constants\Schema::_TO, \org\schema\constants\Schema::ID, \org\schema\constants\Schema::NAME, \org\schema\constants\Schema::URL, \org\schema\constants\Schema::CREATED, \org\schema\constants\Schema::MODIFIED]: Defines the priority order of keys when serializing the object to JSON-LD.

Properties

$_from : string|null: The metadata to indicates the edge 'from' identifier.
$_id : null|string: The metadata identifier of the item.
$_key : null|string: The metadata unique key identifier of the thing.
$_rev : null|string: The metadata revision value of the thing.
$_to : string|null: The metadata to indicates the edge 'to' identifier.
$active : bool|null: The active flag.
$additionalType : array<string|int, mixed>|string|null|object: An additionalType for the item.
$aggregateRating : array<string|int, mixed>|AggregateRating|null: The overall rating, based on a collection of reviews or ratings, of the item.
$algorithm : string|null: The JSON Web Token (JWT) Signing Algorithm (Default RS256).
$allowOfflineAccess : bool|null: If this setting is enabled, will allow applications to ask for Refresh Tokens for this API.
$allowSkipUserConsent : bool|null: If this setting is enabled, this API will skip user consent for applications flagged as First Party.
$alternateName : string|object|array<string|int, mixed>|null: An alias for the item.
$areaServed : null|string|Place|GeoShape|AdministrativeArea|array<string|int, mixed>: The geographic area where a service or offered item is provided.
$audience : array<string|int, mixed>|Audience|null: An intended audience, i.e. a group for whom something was created. Supersedes serviceAudience.
$availableChannel : ServiceChannel|null: A means of accessing the service (e.g. a phone bank, a web site, a location, etc.).
$award : string|array<string|int, mixed>|null: An award won by or for this item.
$brand : Brand|Organization|array<string|int, mixed>|null: The brand(s) associated with a product or service, or the brand(s) maintained by an organization or business person.
$broker : Person|Organization|null: An entity that arranges for an exchange between a buyer and a seller.
$category : null|array<string|int, mixed>|string|CategoryCode|Thing: A category for the item. Greater signs or slashes can be used to informally indicate a category hierarchy.
$created : null|string: Date of creation of the resource.
$description : string|object|array<string|int, mixed>|null: A short description of the item.
$disambiguatingDescription : string|null: A sub property of description. A short description of the item used to disambiguate from other, similar items. Information from other properties (in particular, name) may be necessary for the description to be useful for disambiguation.
$documentation : string|CreativeWork|null: Further documentation describing the Web API in more detail.
$hasCertification : array<string|int, mixed>|Certification|null: Certification information about a product, organization, service, place, or person.
$hasOfferCatalog : array<string|int, mixed>|OfferCatalog|null: Indicates an OfferCatalog listing for this Organization, Person, or Service.
$hasPart : string|Thing|array<string|int, Thing>|null: Indicates an item that this part of this item.
$hoursAvailable : OpeningHoursSpecification|null: The hours during which this service or contact is available.
$id : null|int|string: The unique identifier of the item.
$identifier : string|null: The identifier of the item.
$image : string|ImageObject|array<string|int, ImageObject|string>|null: The image reference of this resource.
$implicitHybridTokenLifetime : int|null: The Implicit/Hybrid Flow Access Token Lifetime.
$isPartOf : string|Thing|array<string|int, Thing>|null: Indicates an item that this item is part of.
$isRelatedTo : Product|Service|array<string|int, mixed>|null: A pointer to another, somehow related product (or multiple products).
$isSimilarTo : Product|Service|array<string|int, mixed>|null: A pointer to another, functionally similar product (or multiple products).
$license : string|object|null: A legal document giving official permission to do something with the resource.
$logo : string|ImageObject|null: An associated logo.
$mainEntityOfPage : string|null: Indicates a page (or other CreativeWork) for which this thing is the main entity being described.
$maximumAccessTokenExpiration : int|null: The maximum Access Token lifetime in seconds.
$modified : null|string: Date on which the resource was changed.
$name : int|string|null: The name of the item.
$offers : array<string|int, mixed>|Offer|Demand|null: An offer to provide this item.
$owner : null|string|Thing: The owner of this Thing.
$permissions : array<string|int, Permission>|null: Define the permissions (scopes) that this Role uses.
$permissionsCount : int|null: The number of permissions attached on this Role.
$potentialAction : array<string|int, mixed>|Action|null: Indicates a potential Action, which describes an idealized action in which this thing would play an 'object' role.
$provider : Person|Organization|null: The service provider, service operator, or service performer; the goods producer.
$providerMobility : string|null: Indicates the mobility of a provided service (e.g. 'static', 'dynamic').
$publisher : string|array<string|int, string|Person|Organization>|Person|Organization|null: The publisher of the resource.
$rbac : bool|null: Indicates if the RBAC is enabled.
$review : array<string|int, mixed>|Review|null: A review of the item.
$sameAs : string|array<string|int, mixed>|null: URL of a reference Web page that unambiguously indicates the item's identity.
$scopeHasPermission : bool|null: If this setting is enabled, the Permissions claim will be added to the access token.
$serviceOutput : Thing|null: The tangible thing generated by the service, e.g. a passport, permit, etc.
$serviceType : string|Enumeration|DefinedTerm|null: The type of service being offered, e.g. veterans' benefits, emergency relief, etc.
$slogan : string|null: A slogan or motto associated with the item.
$subjectOf : null|string|array<string|int, mixed>|CreativeWork|Event: A CreativeWork or Event about this Thing.
$termsOfService : string|null|object: Human-readable terms of service documentation.
$url : int|string|null: URL of the item.
$users : array<string|int, User>|null: Define the users that this Role is attached.
$usersCount : int|null: The number of users attached on this Role.
$atContext : string|null: The JSON-LD `@context` value.
$atType : string|null: The JSON-LD `@type` value.

Methods

__construct() : mixed: Constructor to hydrate public properties from an array or stdClass.
jsonSerialize() : array<string|int, mixed>: Serializes the current object into a JSON-LD array.
toPolicy() : array<string|int, mixed>: Returns an array of policies ready to inject dans Casbin
withAtContext() : $this: Sets the internal JSON-LD `@context` attribute.
withAtType() : $this: Sets the internal JSON-LD `@type` attribute.
withJSONLDMeta() : $this: Initializes both JSON-LD metadata: `@type` and `@context`.

CONTEXT

The @context of the json-ld representation of the thing.


    public
        mixed
    CONTEXT
    = \xyz\oihana\schema\constants\Oihana::SCHEMA

DEFAULT_ALGORITHM

The default JSON Web Token (JWT) Signing Algorithm.


    public
        mixed
    DEFAULT_ALGORITHM
    = \xyz\oihana\schema\constants\JWTAlgorithm::RS256

DEFAULT_IMPLICIT_HYBRID_TOKEN_LIFETIME

The default Implicit/Hybrid Flow Access Token Lifetime value in seconds.


    public
        mixed
    DEFAULT_IMPLICIT_HYBRID_TOKEN_LIFETIME
    = 7200

DEFAULT_TOKEN_EXPIRATION

The default Maximum Access Token Lifetime value in seconds.


    public
        mixed
    DEFAULT_TOKEN_EXPIRATION
    = 86400

JSON_PRIORITY_KEYS

Defines the priority order of keys when serializing the object to JSON-LD.


    public
        array<string|int, string>
    JSON_PRIORITY_KEYS
    = [\org\schema\constants\Schema::AT_TYPE, \org\schema\constants\Schema::AT_CONTEXT, \org\schema\constants\Schema::_KEY, \org\schema\constants\Schema::_FROM, \org\schema\constants\Schema::_TO, \org\schema\constants\Schema::ID, \org\schema\constants\Schema::NAME, \org\schema\constants\Schema::URL, \org\schema\constants\Schema::CREATED, \org\schema\constants\Schema::MODIFIED]

Keys listed here will always appear first in the serialized array, in the order specified. All remaining public properties will be sorted alphabetically after these priority keys.

This ensures that important JSON-LD metadata and system fields (like @type, @context, _key, id, url, created, modified, etc.) appear at the top of the output for consistency and readability.

Usage:

$orderedKeys = self::JSON_PRIORITY_KEYS;

Notes:

Can be overridden in a subclass by redefining the constant.
Late static binding (static::JSON_PRIORITY_KEYS) allows child classes to modify the serialization order.

List of JSON-LD keys in priority order.

$_from

The metadata to indicates the edge 'from' identifier.


        public
            string|null
    $_from

$_id

The metadata identifier of the item.


        public
            null|string
    $_id

$_key

The metadata unique key identifier of the thing.


        public
            null|string
    $_key

$_rev

The metadata revision value of the thing.


        public
            null|string
    $_rev

$_to

The metadata to indicates the edge 'to' identifier.


        public
            string|null
    $_to

$active

The active flag.


        public
            bool|null
    $active

$additionalType

An additionalType for the item.


        public
            array<string|int, mixed>|string|null|object
    $additionalType

$aggregateRating

The overall rating, based on a collection of reviews or ratings, of the item.


        public
            array<string|int, mixed>|AggregateRating|null
    $aggregateRating

$algorithm

The JSON Web Token (JWT) Signing Algorithm (Default RS256).


        public
            string|null
    $algorithm

$allowOfflineAccess

If this setting is enabled, will allow applications to ask for Refresh Tokens for this API.


        public
            bool|null
    $allowOfflineAccess

$allowSkipUserConsent

If this setting is enabled, this API will skip user consent for applications flagged as First Party.


        public
            bool|null
    $allowSkipUserConsent

$alternateName

An alias for the item.


        public
            string|object|array<string|int, mixed>|null
    $alternateName

$areaServed

The geographic area where a service or offered item is provided.


        public
            null|string|Place|GeoShape|AdministrativeArea|array<string|int, mixed>
    $areaServed

$audience

An intended audience, i.e. a group for whom something was created. Supersedes serviceAudience.


        public
            array<string|int, mixed>|Audience|null
    $audience

$availableChannel

A means of accessing the service (e.g. a phone bank, a web site, a location, etc.).


        public
            ServiceChannel|null
    $availableChannel

$award

An award won by or for this item.


        public
            string|array<string|int, mixed>|null
    $award

$brand

The brand(s) associated with a product or service, or the brand(s) maintained by an organization or business person.


        public
            Brand|Organization|array<string|int, mixed>|null
    $brand

$broker

An entity that arranges for an exchange between a buyer and a seller.


        public
            Person|Organization|null
    $broker

In most cases a broker never acquires or releases ownership of a product or service involved in an exchange. If it is not clear whether an entity is a broker, seller, or buyer, the latter two terms are preferred.

$category

A category for the item. Greater signs or slashes can be used to informally indicate a category hierarchy.


        public
            null|array<string|int, mixed>|string|CategoryCode|Thing
    $category
     = null

$created

Date of creation of the resource.


        public
            null|string
    $created

$description

A short description of the item.


        public
            string|object|array<string|int, mixed>|null
    $description

$disambiguatingDescription

A sub property of description. A short description of the item used to disambiguate from other, similar items. Information from other properties (in particular, name) may be necessary for the description to be useful for disambiguation.


        public
            string|null
    $disambiguatingDescription

$documentation

Further documentation describing the Web API in more detail.


        public
            string|CreativeWork|null
    $documentation

$hasCertification

Certification information about a product, organization, service, place, or person.


        public
            array<string|int, mixed>|Certification|null
    $hasCertification

$hasOfferCatalog

Indicates an OfferCatalog listing for this Organization, Person, or Service.


        public
            array<string|int, mixed>|OfferCatalog|null
    $hasOfferCatalog

$hasPart

Indicates an item that this part of this item.


        public
            string|Thing|array<string|int, Thing>|null
    $hasPart

$hoursAvailable

The hours during which this service or contact is available.


        public
            OpeningHoursSpecification|null
    $hoursAvailable

$id

The unique identifier of the item.


        public
            null|int|string
    $id

$identifier

The identifier of the item.


        public
            string|null
    $identifier

$image

The image reference of this resource.


        public
            string|ImageObject|array<string|int, ImageObject|string>|null
    $image

$implicitHybridTokenLifetime

The Implicit/Hybrid Flow Access Token Lifetime.


        public
            int|null
    $implicitHybridTokenLifetime

Time until an access token issued for this API, using either the implicit or hybrid flow, will expire. Cannot exceed the maximum access token lifetime.

$isPartOf

Indicates an item that this item is part of.


        public
            string|Thing|array<string|int, Thing>|null
    $isPartOf

$isRelatedTo

A pointer to another, somehow related product (or multiple products).


        public
            Product|Service|array<string|int, mixed>|null
    $isRelatedTo

$isSimilarTo

A pointer to another, functionally similar product (or multiple products).


        public
            Product|Service|array<string|int, mixed>|null
    $isSimilarTo

$license

A legal document giving official permission to do something with the resource.


        public
            string|object|null
    $license

$logo

An associated logo.


        public
            string|ImageObject|null
    $logo

$mainEntityOfPage

Indicates a page (or other CreativeWork) for which this thing is the main entity being described.


        public
            string|null
    $mainEntityOfPage

$maximumAccessTokenExpiration

The maximum Access Token lifetime in seconds.


        public
            int|null
    $maximumAccessTokenExpiration

Time until an access token issued for this API will expire.

$modified

Date on which the resource was changed.


        public
            null|string
    $modified

$name

The name of the item.


        public
            int|string|null
    $name

$offers

An offer to provide this item.


        public
            array<string|int, mixed>|Offer|Demand|null
    $offers

$owner

The owner of this Thing.


        public
            null|string|Thing
    $owner

Represents any entity (person, organization, system, or other object) that can be considered the possessor of this Thing.

$permissions

Define the permissions (scopes) that this Role uses.


        public
            array<string|int, Permission>|null
    $permissions

#[HydrateWith]: \xyz\oihana\schema\auth\Permission::class

$permissionsCount

The number of permissions attached on this Role.


        public
            int|null
    $permissionsCount

$potentialAction

Indicates a potential Action, which describes an idealized action in which this thing would play an 'object' role.


        public
            array<string|int, mixed>|Action|null
    $potentialAction

$provider

The service provider, service operator, or service performer; the goods producer.


        public
            Person|Organization|null
    $provider

Another party (a seller) may offer those services or goods on behalf of the provider. A provider may also serve as the seller.

$providerMobility

Indicates the mobility of a provided service (e.g. 'static', 'dynamic').


        public
            string|null
    $providerMobility

$publisher

The publisher of the resource.


        public
            string|array<string|int, string|Person|Organization>|Person|Organization|null
    $publisher

$rbac

Indicates if the RBAC is enabled.


        public
            bool|null
    $rbac

$review

A review of the item.


        public
            array<string|int, mixed>|Review|null
    $review

$sameAs

URL of a reference Web page that unambiguously indicates the item's identity.


        public
            string|array<string|int, mixed>|null
    $sameAs

E.g. the URL of the item's Wikipedia page, Wikidata entry, or official website.

$scopeHasPermission

If this setting is enabled, the Permissions claim will be added to the access token.


        public
            bool|null
    $scopeHasPermission

Only available if RBAC is enabled for this API.

$serviceOutput

The tangible thing generated by the service, e.g. a passport, permit, etc.


        public
            Thing|null
    $serviceOutput

$serviceType

The type of service being offered, e.g. veterans' benefits, emergency relief, etc.


        public
            string|Enumeration|DefinedTerm|null
    $serviceType

$slogan

A slogan or motto associated with the item.


        public
            string|null
    $slogan

$subjectOf

A CreativeWork or Event about this Thing.


        public
            null|string|array<string|int, mixed>|CreativeWork|Event
    $subjectOf

$termsOfService

Human-readable terms of service documentation.


        public
            string|null|object
    $termsOfService

$url

URL of the item.


        public
            int|string|null
    $url

$users

Define the users that this Role is attached.


        public
            array<string|int, User>|null
    $users

#[HydrateWith]: \xyz\oihana\schema\auth\User::class

$usersCount

The number of users attached on this Role.


        public
            int|null
    $usersCount

$atContext

The JSON-LD `@context` value.


        private
            string|null
    $atContext
     = null

Default is https://schema.org.

$atType

The JSON-LD `@type` value.


        private
            string|null
    $atType
     = null

This can be manually set or automatically inferred from the class name.

__construct()

Constructor to hydrate public properties from an array or stdClass.


    public
                    __construct([array<string|int, mixed>|object|null $init = null ]) : mixed

This allows objects to be quickly populated with associative data without manually setting each property.

Parameters

$init : array<string|int, mixed>|object|null = null: A data array or object used to initialize the instance. Keys must match public property names.

jsonSerialize()

Serializes the current object into a JSON-LD array.


    public
                    jsonSerialize() : array<string|int, mixed>

Includes public properties, the JSON-LD @context and @type. Null values are automatically removed.

Return values

array<string|int, mixed> —

JSON-LD representation of the object.

toPolicy()

Returns an array of policies ready to inject dans Casbin


    public
                    toPolicy() : array<string|int, mixed>

Return values

array<string|int, mixed>

withAtContext()

Sets the internal JSON-LD `@context` attribute.


    public
                    withAtContext(string $context) : $this

Useful if you need a custom JSON-LD context.

Parameters

$context : string: Optional JSON-LD context.

Return values

$this

withAtType()

Sets the internal JSON-LD `@type` attribute.


    public
                    withAtType(string $type) : $this

Allows overriding the default type inferred from the class.

Parameters

$type : string: Optional JSON-LD type

Return values

$this

withJSONLDMeta()

Initializes both JSON-LD metadata: `@type` and `@context`.


    public
                    withJSONLDMeta([string|null $atType = null ][, string|null $atContext = null ]) : $this

Can be called from constructor or later to override default values.

Parameters

$atType : string|null = null: Optional JSON-LD type
$atContext : string|null = null: Optional JSON-LD context

Return values

$this

Role extends WebAPI

Features

Example

Notes

Tags

Table of Contents

Constants

Properties

Methods

Constants

CONTEXT

DEFAULT_ALGORITHM

DEFAULT_IMPLICIT_HYBRID_TOKEN_LIFETIME

DEFAULT_TOKEN_EXPIRATION

JSON_PRIORITY_KEYS

Properties

$_from

$_id

$_key

$_rev

$_to

$active

$additionalType

$aggregateRating

$algorithm

$allowOfflineAccess

$allowSkipUserConsent

$alternateName

$areaServed

$audience

$availableChannel

$award

$brand

$broker

$category

$created

$description

$disambiguatingDescription

$documentation

$hasCertification

$hasOfferCatalog

$hasPart

$hoursAvailable

$id

$identifier

$image

$implicitHybridTokenLifetime

$isPartOf

$isRelatedTo

$isSimilarTo

$license

$logo

$mainEntityOfPage

$maximumAccessTokenExpiration

$modified

$name

$offers

$owner

$permissions

Attributes

$permissionsCount

$potentialAction

$provider

$providerMobility

$publisher

$rbac

$review

$sameAs

$scopeHasPermission

$serviceOutput

$serviceType

$slogan

$subjectOf

$termsOfService

$url

$users

Attributes

$usersCount

$atContext

$atType