Documentation

Repo
in package
implements RepoInterface Uses RepoTrait

A repository connection class.

Tags
author

zozlak

Table of Contents

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.
$baseUri  : string
$baseUrl  : string
$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()  : string
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

Constants

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

Properties

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

$baseUri

private string $baseUri

$baseUrl

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

Methods

__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() : string

All data modifications must be performed within a transaction.

Tags
see
rollback()
see
commit()
Return values
string —

transaction identifier

commit()

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

public commit() : void

All data modifications must be performed within a transaction.

Tags
see
begin()
see
rollback()

createResource()

Creates a repository resource.

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

resource metadata

$payload : BinaryPayload|null = null

resource binary payload (can be null)

$class : string|null = 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 = 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|null $payload = null ][, string|null $class = null ][, string $readMode = RepoResourceInterface::META_RESOURCE ][, string|null $parentProperty = null ]) : RepoResourcePromise
Parameters
$metadata : DatasetNodeInterface
$payload : BinaryPayload|null = null
$class : string|null = null
$readMode : string = RepoResourceInterface::META_RESOURCE
$parentProperty : string|null = null
Tags
see
createResource()
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|null &$realUrl = null ][, string|null $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 = null

if provided, the final resource URL will be stored in this variable.

$metaReadModeHeader : string|null = 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

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
Tags
see
getGraphBySqlQuery()
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

getResourceByIds()

Tries to find a single repository resource matching provided identifiers.

public getResourceByIds(array<string|int, string> $ids[, SearchConfig|null $config = 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)

$config : SearchConfig|null = null
Tags
throws
NotFound
throws
AmbiguousMatch
Return values
RepoResource

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>

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
Tags
see
begin()
see
rollback()
see
commit()
see
prolong()
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

Tags
see
begin()

rollback()

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

public rollback() : void

All data modifications must be performed within a transaction.

Tags
see
begin()
see
commit()

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

Tags
throws
Deleted
throws
NotFound
throws
RequestException
Return values
ResponseInterface

sendRequestAsync()

Asynchronous version of sendRequest()

public sendRequestAsync(Request $request) : ResponsePromise
Parameters
$request : Request
Tags
see
sendRequest()
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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results