SRU-AO is a PHP & Laravel package to facilitate the implementation of an archives-online.org compatible SRU interfaces to your archival database.
- Feed the archives-online.org query to the SruQuery::getQueryParams function and it will parse the query and return an array of fields and operators.
- Provide an array with query results to the SruResponse::composeSruResponse function and it will return a formatted an valid XML-Response you can serve to the archives-online.org query.
- Composer
Just require ritterg/sru-ao within your project
composer require ritterg/sru-ao
- make sure everything is OK by running the tests
phpunit
archives-online.org SRU queries come in a special format like
https://server.tld/SRU?operation=searchretrieve&version=1.2&query=Serverchoice%20all%20%22Switzerland%20Germany%22%20AND%20isad.date%20WITHIN%20%221000%202000%22&maximumRecords=50
The SruQuery class helps you to parse this query.
use Ritterg\SruAo\SruQuery;
$sruquery = new SruQuery;
$searchparams = $sruquery->getQueryParams($request, $allowedfields = null, $allowedoperators = null);
$searchparams
will be an array with all the sanitized and renamed query parameters from the sru query.
$request
is the array of input parameters from the query (i.e. $_GET).
$allowedfields
is an array of allowed query fields and the string they should be renamed to. Default values are
$allowedfields = [
'Serverchoice' => 'fulltext',
'isad.reference' => 'reference',
'isad.title' => 'title',
'isad.date' => 'date',
];
$allowedoperators
is an array of allowed operators and the string they should be rewritten to. Default values are
$allowedoperators = [
'all' => 'AND',
'any' => 'OR',
'adj' => 'ADJ',
'=' => 'LIKE',
'==' => 'LIKE',
'===' => '=',
'WITHIN' => '='
];
You can override these defaults with walues that best fit your database
The result is an array with all query parameters. For each parameter, there is another array with the value and the operator.
For the query above the result would be
$searchparams = [
"fulltext" => [
"value" => "Switzerland Germany"
"operator" => "AND"
]
"date_start" => [
"value" => "1000-01-01"
"operator" => ">="
]
"date_end" => [
"value" => "2000-12-31"
"operator" => "<="
]
"limit" => 50
]
Take these parameters and build the query for your database.
use Ritterg\SruAo\SruQuery;
$sruresponse = new SruResponse;
$xml = $sruresponse->composeSruResponse($results, $totalcount, $keys);
$xml
will be an XML string suitable to return to archives-online.org.
$results
is the array of records that you want to send to archives-online.org.
archives-online.org has 13 fields per record
- reference: the reference/signature of the archival unit
- title: the title of the archival unit
- date: the date string of the archival unit
- descriptionlevel: the level of description of the archival unit
- extent: the extent/size/count of the archival unit
- creator: the creator/author of the archival unit
- score: the relevance of the record regarding the search query (0 - 1)
- link: a direct link to the detail page for the archival unit
- beginDateISO: the start date of the archival unit in ISO format YYYY-MM-DD
- beginApprox: true if the start date is approximate, false if the date is exact
- endDateISO: the end date of the archival unit in ISO format YYYY-MM-DD
- endApprox: true if the start date is approximate, false if the date is exact
- hasDigitizedItems: true if the archival unit has digitized items attached, false otherwise (this field is optional)
$totalcount
is the number of total results in your database.
An SRU query contains a parameter "maximumRecords" to indicate how many results should be returned. If your query has more results, you can return the number of total results in $totalcount.
$keys
is an array of alternative array keys. If your results have different keys than the standard SRU keys, you can add an array of keys to match your keys with the standard keys.
If you have e.g. German keys in your results array, a $keys array could look like this:
$keys = [
'reference' => 'signatur',
'title' => 'titel',
'date' => 'datum',
'descriptionlevel' => 'stufe',
'extend' => 'umfang',
'creator' => 'autor',
'score' => 'relevanz',
'link' => 'url',
'beginDateISO' => 'anfangsdatum',
'beginApprox' => 'anfangca',
'endDateISO' => 'enddatum',
'endApprox' => 'endca',
'hasDigitizedItems' => 'digitalisate',
];
Check your XML-response with https://archives-online.org/srutest
To run the tests, run the following command from the project folder.
$ ./vendor/bin/phpunit
The MIT License (MIT). See the License File for more information.