Documentation

Repo
in package

Application

implements RepoInterface Uses RepoTrait

A repository connection class.

Interfaces

RepoInterface

Constants

ARCHE_CORE_MIN_VERSION = 3.2
REJECT_FAIL = 2
REJECT_INCLUDE = 3
REJECT_SKIP = 1

Properties

$resourceClass : string: A class used to instantiate objects representing repository resources.
$baseUrl : string: Repository REST API base URL
$client : Client: The Guzzle client object used to send HTTP requests
$headers : object: An object providing mappings of repository REST API parameters to HTTP headers used by a given repository instance.
$queryLog : AbstractLogger|null
$schema : Schema: An object providing mappings of repository concepts to RDF properties used to denote them by a given repository instance.
$txId : string|null: Current transaction id

Methods

__construct() : mixed: Creates an repository connection object.
begin() : void: Begins a transaction.
commit() : void: Commits the current transaction (started with `begin()`).
createResource() : RepoResource: Creates a repository resource.
createResourceAsync() : RepoResourcePromise: Asynchronous version of createResource()
factory() : Repo: Creates a repository object instance from a given configuration file.
factoryFromUrl() : self: Creates a Repo instance from any URL pointing (also trough redirects) to a valid REST API endpoint.
factoryInteractive() : self: Interactively creates a repository instance asking user for all required data.
getBaseUrl() : string: Returns the repository REST API base URL.
getGraphBySearchTerms() : Dataset: Returns RDF metadata graph of the search results.
getGraphBySearchTermsAsync() : GraphPromise: Asynchronous version of getGraphBySearchTerms()
getGraphBySqlQuery() : DatasetInterface: Asynchronous version of
getGraphBySqlQueryAsync() : GraphPromise: Asynchronous version of getGraphBySqlQuery()
getHeaderName() : string: Returns an HTTP header name to be used to pass a given information in the repository request.
getResourceById() : RepoResourceInterface: Tries to find a repository resource with a given id.
getResourceByIdAsync() : RepoResourcePromise: Asynchronous version of getResourceByIds()
getResourceByIds() : RepoResource: Tries to find a single repository resource matching provided identifiers.
getResourceByIdsAsync() : RepoResourcePromise: Asynchronous version of getResourceByIds()
getResourcesBySearchTerms() : Generator<string|int, RepoResource>: Returns repository resources matching all provided search terms.
getResourcesBySearchTermsAsync() : RepoResourceGeneratorPromise: Asynchronous version of getResourcesBySearchTerms()
getResourcesBySqlQuery() : Generator<string|int, RepoResource>: Performs a search
getResourcesBySqlQueryAsync() : RepoResourceGeneratorPromise: Asynchronous version of getResourcesBySqlQuery()
getSchema() : Schema: Returns the `Schema` object defining repository entities to RDF property mappings.
inTransaction() : bool: Checks if there is an active transaction.
map() : array<string|int, mixed>: A wrapper function for parallel repository requests execution.
prolong() : void: Prolongs the current transaction (started with `begin()`).
rollback() : void: Rolls back the current transaction (started with `begin()`).
sendRequest() : ResponseInterface: Sends an HTTP request to the repository.
sendRequestAsync() : ResponsePromise: Asynchronous version of sendRequest()
setQueryLog() : void: Sets a search queries logger
extractResourcesFromGraph() : Generator<string|int, RepoResourceInterface>: Extracts collection of RepoResource objects from the EasyRdf graph being parsed from a search response.
parseSearchResponse() : Dataset: Parses search request response into the EasyRdf Graph.
sortMatchingResources() : void
withReadHeaders() : Request

ARCHE_CORE_MIN_VERSION


    public
        mixed
    ARCHE_CORE_MIN_VERSION
    = 3.2

REJECT_FAIL


    public
        mixed
    REJECT_FAIL
    = 2

REJECT_INCLUDE


    public
        mixed
    REJECT_INCLUDE
    = 3

REJECT_SKIP


    public
        mixed
    REJECT_SKIP
    = 1

$resourceClass

A class used to instantiate objects representing repository resources.


    public
    static    string
    $resourceClass
     = \acdhOeaw\arche\lib\RepoResource::class

To be used by external libraries extending the RepoResource class funcionality provided by this library.

$baseUrl

Repository REST API base URL


    private
        string
    $baseUrl

$client

The Guzzle client object used to send HTTP requests


    private
        Client
    $client

$headers

An object providing mappings of repository REST API parameters to HTTP headers used by a given repository instance.


    private
        object
    $headers

$queryLog


    private
        AbstractLogger|null
    $queryLog

$schema

An object providing mappings of repository concepts to RDF properties used to denote them by a given repository instance.


    private
        Schema
    $schema

$txId

Current transaction id


    private
        string|null
    $txId

__construct()

Creates an repository connection object.


    public
                    __construct(string $baseUrl[, array<string|int, mixed> $guzzleOptions = [] ]) : mixed

Parameters

$baseUrl : string: repository REST API base URL
$guzzleOptions : array<string|int, mixed> = []: Guzzle HTTP client connection options to be used by all requests to the repository REST API (e.g. credentials)

begin()

Begins a transaction.


    public
                    begin() : void

All data modifications must be performed within a transaction.

commit()

Commits the current transaction (started with `begin()`).


    public
                    commit() : void

All data modifications must be performed within a transaction.

createResource()

Creates a repository resource.


    public
                    createResource(DatasetNodeInterface $metadata[, BinaryPayload $payload = null ][, string $class = null ][, string $readMode = RepoResourceInterface::META_RESOURCE ][, string $parentProperty = null ]) : RepoResource

Parameters

$metadata : DatasetNodeInterface

resource metadata

$payload : BinaryPayload = null

resource binary payload (can be null)

$class : string = null

an optional class of the resulting object representing the resource (to be used by extension libraries)

$readMode : string = RepoResourceInterface::META_RESOURCE

scope of the metadata returned by the repository

see the META_* constants defined by the RepoResourceInterface

$parentProperty : string = null

RDF property to be used by the metadata read mode denoted by the $readMode parameter

Return values

RepoResource

createResourceAsync()

Asynchronous version of createResource()


    public
                    createResourceAsync(DatasetNodeInterface $metadata[, BinaryPayload $payload = null ][, string $class = null ][, string $readMode = RepoResourceInterface::META_RESOURCE ][, string|null $parentProperty = null ]) : RepoResourcePromise

Parameters

$metadata : DatasetNodeInterface
$payload : BinaryPayload = null
$class : string = null
$readMode : string = RepoResourceInterface::META_RESOURCE
$parentProperty : string|null = null

Return values

RepoResourcePromise

factory()

Creates a repository object instance from a given configuration file.


    public
            static        factory(string $configFile) : Repo

Automatically parses required config properties and passes them to the Repo object constructor.

Parameters

$configFile : string: a path to the YAML config file

Return values

Repo

factoryFromUrl()

Creates a Repo instance from any URL pointing (also trough redirects) to a valid REST API endpoint.


    public
            static        factoryFromUrl(string $url[, array<string|int, mixed> $guzzleOptions = [] ][, string &$realUrl = null ][, string $metaReadModeHeader = null ]) : self

It can be slow (especially when redirects are involved) but requires no config.

Parameters

$url : string
$guzzleOptions : array<string|int, mixed> = []
$realUrl : string = null: if provided, the final resource URL will be stored in this variable.
$metaReadModeHeader : string = null: header used by the repository to denote the metadata read mode. Providing this parameter will speed up the initialization if the $url points to a repository resource.

Return values

self

factoryInteractive()

Interactively creates a repository instance asking user for all required data.


    public
            static        factoryInteractive([string|null $cfgLocation = null ][, string|null $login = null ][, string|null $pswd = null ]) : self

Parameters

$cfgLocation : string|null = null

optional path to a config file. The config file may provide a predefined list of repositories and/or ARCHE login formatted as follows:

repositories:
- urlBase: http://arche.acdh.oeaw.ac.at
  pathBase: /api/
- urlBase: https://arche-curation.acdh-dev.oeaw.ac.at
  pathBase: /
auth:
  httpBasic:
    user: myLogin

$login : string|null = null

ARCHE login. If null, user will be asked to provide it interactively.

$pswd : string|null = null

ARCHE password. If null, user will be asked to provide it interactively.

Return values

self

getBaseUrl()

Returns the repository REST API base URL.


    public
                    getBaseUrl() : string

Return values

string

getGraphBySearchTerms()

Returns RDF metadata graph of the search results.


    public
                    getGraphBySearchTerms(array<string|int, SearchTerm> $searchTerms, SearchConfig $config) : Dataset

Parameters

$searchTerms : array<string|int, SearchTerm>
$config : SearchConfig

Return values

Dataset

getGraphBySearchTermsAsync()

Asynchronous version of getGraphBySearchTerms()


    public
                    getGraphBySearchTermsAsync(array<string|int, SearchTerm> $searchTerms, SearchConfig $config) : GraphPromise

Parameters

$searchTerms : array<string|int, SearchTerm>
$config : SearchConfig

Return values

GraphPromise

getGraphBySqlQuery()

Asynchronous version of


    public
                    getGraphBySqlQuery(string $query, array<string|int, mixed> $parameters, SearchConfig $config) : DatasetInterface

Parameters

$query : string
$parameters : array<string|int, mixed>
$config : SearchConfig

Return values

DatasetInterface

getGraphBySqlQueryAsync()

Asynchronous version of getGraphBySqlQuery()


    public
                    getGraphBySqlQueryAsync(string $query, array<string|int, mixed> $parameters, SearchConfig $config) : GraphPromise

Parameters

$query : string
$parameters : array<string|int, mixed>
$config : SearchConfig

Return values

GraphPromise

getHeaderName()

Returns an HTTP header name to be used to pass a given information in the repository request.


    public
                    getHeaderName(string $purpose) : string

Parameters

$purpose : string

Return values

string

getResourceById()

Tries to find a repository resource with a given id.


    public
                    getResourceById(string $id[, string $class = null ]) : RepoResourceInterface

Throws an error on failure.

Parameters

$id : string
$class : string = null: an optional class of the resulting object representing the resource (to be used by extension libraries)

Return values

RepoResourceInterface

getResourceByIdAsync()

Asynchronous version of getResourceByIds()


    public
                    getResourceByIdAsync(string $id[, string $class = null ]) : RepoResourcePromise

Parameters

$id : string
$class : string = null

Return values

RepoResourcePromise

getResourceByIds()

Tries to find a single repository resource matching provided identifiers.


    public
                    getResourceByIds(array<string|int, string> $ids[, string $class = null ]) : RepoResource

A resource matches the search if at lest one id matches the provided list. Resource is not required to have all provided ids.

If more then one resources matches the search or there is no resource matching the search, an error is thrown.

Parameters

$ids : array<string|int, string>: an array of identifiers (being strings)
$class : string = null: an optional class of the resulting object representing the resource (to be used by extension libraries)

Return values

RepoResource

getResourceByIdsAsync()

Asynchronous version of getResourceByIds()


    public
                    getResourceByIdsAsync(array<string|int, string> $ids[, string $class = null ]) : RepoResourcePromise

Parameters

$ids : array<string|int, string>
$class : string = null

Return values

RepoResourcePromise

getResourcesBySearchTerms()

Returns repository resources matching all provided search terms.


    public
                    getResourcesBySearchTerms(array<string|int, SearchTerm> $searchTerms, SearchConfig $config) : Generator<string|int, RepoResource>

Parameters

$searchTerms : array<string|int, SearchTerm>
$config : SearchConfig

Return values

Generator<string|int, RepoResource>

getResourcesBySearchTermsAsync()

Asynchronous version of getResourcesBySearchTerms()


    public
                    getResourcesBySearchTermsAsync(array<string|int, SearchTerm> $searchTerms, SearchConfig $config) : RepoResourceGeneratorPromise

Parameters

$searchTerms : array<string|int, SearchTerm>
$config : SearchConfig

Return values

RepoResourceGeneratorPromise

getResourcesBySqlQuery()

Performs a search


    public
                    getResourcesBySqlQuery(string $query, array<string|int, mixed> $parameters, SearchConfig $config) : Generator<string|int, RepoResource>

Parameters

$query : string
$parameters : array<string|int, mixed>
$config : SearchConfig

Return values

Generator<string|int, RepoResource>

getResourcesBySqlQueryAsync()

Asynchronous version of getResourcesBySqlQuery()


    public
                    getResourcesBySqlQueryAsync(string $query, array<string|int, mixed> $parameters, SearchConfig $config) : RepoResourceGeneratorPromise

Parameters

$query : string
$parameters : array<string|int, mixed>
$config : SearchConfig

Return values

RepoResourceGeneratorPromise

getSchema()

Returns the `Schema` object defining repository entities to RDF property mappings.


    public
                    getSchema() : Schema

Return values

Schema

inTransaction()

Checks if there is an active transaction.


    public
                    inTransaction() : bool

Return values

bool

map()

A wrapper function for parallel repository requests execution.


    public
                    map(iterable<string|int, mixed> $iter, callable $func[, int $concurrency = 1 ][, int $rejectAction = self::REJECT_SKIP ]) : array<string|int, mixed>

It calls $func for every element of $iter to generate a set of promises, executes all of them and returns their results.

Parameters

$iter : iterable<string|int, mixed>: collection of values to iterate over.
$func : callable: function to apply to each $iter element with signature f(mixed $iterElement, Repo $thisRepoObject): GuzzleHttp\Promise\PromiseInterface.
$concurrency : int = 1: number of promises executed in parallel
$rejectAction : int = self::REJECT_SKIP: what to do with rejected promises - one of Repo::REJECT_SKIP (skip them silently), Repo::REJECT_FAIL (throw an error) and Repo::REJECT_INCLUDE (include the rejection value in the results).

Return values

array<string|int, mixed>

prolong()

Prolongs the current transaction (started with `begin()`).


    public
                    prolong() : void

Every repository has a transaction timeout. If there are no calls to the repository

rollback()

Rolls back the current transaction (started with `begin()`).


    public
                    rollback() : void

All data modifications must be performed within a transaction.

sendRequest()

Sends an HTTP request to the repository.


    public
                    sendRequest(Request $request) : ResponseInterface

A low-level repository API method.

Handles most common errors which can be returned by the repository.

Parameters

$request : Request: a PSR-7 HTTP request

Return values

ResponseInterface

sendRequestAsync()

Asynchronous version of sendRequest()


    public
                    sendRequestAsync(Request $request) : ResponsePromise

Parameters

$request : Request

Return values

ResponsePromise

setQueryLog()

Sets a search queries logger


    public
                    setQueryLog(AbstractLogger $log) : void

Parameters

$log : AbstractLogger

extractResourcesFromGraph()

Extracts collection of RepoResource objects from the EasyRdf graph being parsed from a search response.


    private
                    extractResourcesFromGraph(Dataset $graph, SearchConfig $config) : Generator<string|int, RepoResourceInterface>

Parameters

$graph : Dataset: graph returned by the parseSearchResponse() method
$config : SearchConfig: search configuration object

Return values

Generator<string|int, RepoResourceInterface>

parseSearchResponse()

Parses search request response into the EasyRdf Graph.


    private
                    parseSearchResponse(ResponseInterface $resp, SearchConfig $config) : Dataset

Parameters

$resp : ResponseInterface: PSR-7 search request response
$config : SearchConfig: search configuration object

Return values

Dataset

sortMatchingResources()


    private
                    sortMatchingResources(array<string|int, DatasetNodeInterface> &$resources, NamedNode $searchOrderProp) : void

Parameters

$resources : array<string|int, DatasetNodeInterface>
$searchOrderProp : NamedNode

withReadHeaders()


    private
                    withReadHeaders(Request $request, string $mode, string|null $parentProperty) : Request

Parameters

$request : Request
$mode : string
$parentProperty : string|null

Return values

Request

Repo in package Application implements RepoInterface Uses RepoTrait

Tags

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

ARCHE_CORE_MIN_VERSION

REJECT_FAIL

REJECT_INCLUDE

REJECT_SKIP

Properties

$resourceClass

$baseUrl

$client

$headers

$queryLog

$schema

$txId

Methods

__construct()

Parameters

begin()

Tags

commit()

Tags

createResource()

Parameters

Return values

createResourceAsync()

Parameters

Tags

Return values

factory()

Parameters

Return values

factoryFromUrl()

Parameters

Return values

factoryInteractive()

Parameters

Return values

getBaseUrl()

Return values

getGraphBySearchTerms()

Parameters

Return values

getGraphBySearchTermsAsync()

Parameters

Tags

Return values

getGraphBySqlQuery()

Parameters

Return values

getGraphBySqlQueryAsync()

Parameters

Tags

Return values

getHeaderName()

Parameters

Return values

getResourceById()

Parameters

Return values

getResourceByIdAsync()

Parameters

Tags

Return values

getResourceByIds()

Parameters

Tags

Return values

getResourceByIdsAsync()

Parameters

Tags

Return values

getResourcesBySearchTerms()

Parameters

Return values

Repo
in package

Application

implements RepoInterface Uses RepoTrait