Doc

Author: lutzhelm

Diff for: README.md

@@ -1,10 +1,10 @@
 # IIIF Manifest Reader for PHP
 
-Read IIIF Presentation API resources into PHP objects that offer some convenient data extraction methods.
+Read [IIIF](https://iiif.io/) Presentation API resources into PHP objects that offer some convenient data extraction methods.
 
 Requires at least PHP 5.6.
 
-IIIF Presentation API support is primarily implemented for version 2.1, with some rudimentary support for Presentation API 3.0 and Metadata API 1.0.
+IIIF Presentation API support is primarily implemented for version [2.1](https://iiif.io/api/presentation/2.1/), with some rudimentary support for [Presentation API 3.0](https://iiif.io/api/presentation/3.0/) and [Metadata API 1.0](https://iiif.io/api/metadata/1.0/).
 
 ## Where to start
 

Diff for: composer.json

@@ -4,9 +4,10 @@
 	"type" : "library",
 	"keywords" : [
 		"iiif",
-		"presentation-api"
+		"iiif-presentation"
 	],
 	"require" : {
+		"php" : ">=5.6",
 		"flow/jsonpath" : ">=0.4.0"
 	},
 	"require-dev" : {

Diff for: src/Iiif/Context/IRI.php

@@ -86,6 +86,9 @@ class IRI {
      */
     protected $fragment;
 
+    /**
+     * @param string|IRI $iri A string representation to read into an IRI object or an IRI object to copy  
+     */
     public function __construct($iri = null) {
         if (is_string($iri) && self::isIri($iri)) {
             $this->iri = $iri;
@@ -139,7 +142,7 @@ public static function isCompactIri($iri, JsonLdContext $context) {
     }
 
     /**
-     * Checks if a string has the form of a IRI by matching the regex in https://tools.ietf.org/html/rfc3986#appendix-B
+     * Checks if a string has the form of an IRI by matching the regex in https://tools.ietf.org/html/rfc3986#appendix-B
      * @param string $iri
      * @return boolean
      * @link https://tools.ietf.org/html/rfc3986#appendix-B

Diff for: src/Iiif/Context/JsonLdContext.php

@@ -30,6 +30,7 @@
 
 class JsonLdContext {
 
+    // FIXME Context may have more than one IRI or none. 
     protected $contextIri = "";
 
     protected $baseIri = "";

Diff for: src/Iiif/Context/JsonLdProcessor.php

@@ -24,11 +24,9 @@
 
 /**
  * Implementation of the context processing algorithm of the JSON-LD API version 1.1.
- * Expansion, Compaction and Flattening algorithms are not implemented.
- *
- *
- * @author lutzhelm
- *        
+ * Expansion, Compaction and Flattening algorithms are not (yet) implemented.
+ * 
+ * @author Lutz Helm <[email protected]>
  */
 class JsonLdProcessor {
 
@@ -102,6 +100,15 @@ private function loadUnknownContext($context) {
         return IiifHelper::getRemoteContent($context);
     }
 
+    /**
+     * 
+     * @param string|array $localContext
+     * @param JsonLdContext $activeContext
+     * @param array $remoteContexts
+     * @throws \Exception
+     * @return \Ubl\Iiif\Context\JsonLdContext
+     * @link https://w3c.github.io/json-ld-api/#context-processing-algorithm
+     */
     public function processContext($localContext, JsonLdContext $activeContext, $remoteContexts = array()) {
         // Numbering as in draft https://w3c.github.io/json-ld-api/#algorithm on 2019-01-10
         // 1)
@@ -243,6 +250,15 @@ public function processContext($localContext, JsonLdContext $activeContext, $rem
         return $result;
     }
 
+    /**
+     * 
+     * @param JsonLdContext $activeContext
+     * @param array $localContext
+     * @param string $term
+     * @param array $defined
+     * @throws \Exception
+     * @link https://w3c.github.io/json-ld-api/#create-term-definition
+     */
     protected function createTermDefinition(JsonLdContext $activeContext, $localContext, $term, &$defined) {
         // Numbering as in draft https://w3c.github.io/json-ld-api/#algorithm-0 on 2019-01-10 
         // 1)
@@ -526,6 +542,7 @@ protected function createTermDefinition(JsonLdContext $activeContext, $localCont
      * @param array $localContext
      * @param array $defined
      * @return mixed
+     * @link https://w3c.github.io/json-ld-api/#iri-expansion
      */
     public function expandIRI(JsonLdContext $activeContext, $value, $documentRelative = false, $vocab = false, $localContext = null, $defined = null) {
         // Numbering as in draft https://w3c.github.io/json-ld-api/#algorithm-1 on 2019-01-10

Diff for: src/Iiif/Presentation/Common/Model/AbstractIiifEntity.php

@@ -61,6 +61,11 @@ abstract class AbstractIiifEntity {
      */
     protected $otherData;
 
+    /**
+     * 
+     * @param string|array $resource IRI, text content or array representation of IIIF document
+     * @return \Ubl\Iiif\Presentation\Common\Model\AbstractIiifEntity|NULL
+     */
     public static function loadIiifResource($resource) {
         if (is_string($resource) && IRI::isAbsoluteIri($resource)) {
             $resource = IiifHelper::getRemoteContent($resource);
@@ -90,6 +95,10 @@ public function getOriginalJsonArray() {
         return $this->originalJsonArray;
     }
 
+
+    /**
+     * @return string[] A map to get the right property name for a given IRI or JSON-LD keyword.
+     */
     protected function getPropertyMap() {
         return [
             "@id" => "id",
@@ -107,7 +116,7 @@ protected function getStringResources() {
     }
 
     /**
-     * Names of properties that resolve to AbstractIiifEntity but have not @type given.
+     * Names of properties that can be instantiated as AbstractIiifEntity but have not @type given.
      * Applies to "service" property.
      * Method has to be overridden by affected classes.
      *
@@ -239,6 +248,7 @@ protected function loadProperty($term, $value, JsonLdContext $context, &$allReso
             $property = substr($property, 1);
         }
         if (!property_exists($this, $property)) {
+            // Check if the property can be resolved to an IRI or a JSON-LD keyword
             $iriOrKeyword = null;
             if ($context->getTermDefinition($property) != null) {
                 $iriOrKeyword = $context->getTermDefinition($property)->getIriMapping();
@@ -247,6 +257,7 @@ protected function loadProperty($term, $value, JsonLdContext $context, &$allReso
             } elseif (Keywords::isKeyword($property) || IRI::isAbsoluteIri($property)) {
                 $iriOrKeyword = $property;
             }
+            // Check if there is a property for the IRI / keyword in the resource class
             $propertyMap = $this->getPropertyMap();
             if (array_key_exists($iriOrKeyword, $propertyMap)) {
                 $property = $propertyMap[$iriOrKeyword];

Diff for: src/Iiif/Presentation/Common/Model/Resources/IiifResourceInterface.php

@@ -96,9 +96,21 @@ public function getRequiredStatement();
     public function getRequiredStatementForDisplay($language = null, $joinChars = "; ", $options = IiifResourceInterface::SANITIZE_XML_ENCODE_NONHTML);
 
     public function getSeeAlso();
-    
+    /**
+     * Looks a matching format in all entries of seeAlso and returns their URLs
+     * @param string $format requested format
+     * @return string[] Array of URLs / @id s of all matching entries 
+     */
     public function getSeeAlsoUrlsForFormat($format);
-    
+
+    /**
+     * 
+     * @param string $profile Requested profile
+     * @param boolean $startsWith If true, a seeAlso entry matches if it's profile
+     * starts with $profile. For example, "http://example.org/service/version1" will
+     * then match "http://example.org/service/".
+     * @return Array of URLs / @id s of all matching entries
+     */
     public function getSeeAlsoUrlsForProfile($profile, $startsWith = false);
 
     /**

Diff for: src/Iiif/Tools/IiifHelper.php

@@ -28,7 +28,7 @@ class IiifHelper {
      * 
      * @param string|array $resource IIIF resource. Can be an IRI, the JSON document as string
      * or a dictionary in form of a PHP associative array 
-     * @return NULL|\Ubl\Iiif\Presentation\Common\Model\AbstractIiifEntity An instance of the IIIF 
+     * @return NULL|\Ubl\Iiif\Presentation\Common\Model\AbstractIiifEntity An instance of the IIIF resource 
      */
     public static function loadIiifResource($resource) {
         return AbstractIiifEntity::loadIiifResource($resource);