From 3af03b397946387ff109cf520dce0bf9ad24d2f7 Mon Sep 17 00:00:00 2001
From: Beatrycze Volk <beatrycze.volk@slub-dresden.de>
Date: Mon, 17 Jun 2024 12:31:15 +0200
Subject: [PATCH] Add functions to get first and last element to `ModsReader`

---
 src/Mods/ModsReader.php | 704 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 703 insertions(+), 1 deletion(-)

diff --git a/src/Mods/ModsReader.php b/src/Mods/ModsReader.php
index 29b467c..6718112 100644
--- a/src/Mods/ModsReader.php
+++ b/src/Mods/ModsReader.php
@@ -103,6 +103,45 @@ public function getAccessConditions(string $query = ''): array
         return $accessConditions;
     }
 
+    /**
+     * Get the the first matching <accessCondition> element.
+     * @see https://www.loc.gov/standards/mods/userguide/accesscondition.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?AccessCondition
+     */
+    public function getFirstAccessCondition(string $query = ''): ?AccessCondition
+    {
+        $elements = $this->getAccessConditions($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <accessCondition> element.
+     * @see https://www.loc.gov/standards/mods/userguide/accesscondition.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?AccessCondition
+     */
+    public function getLastAccessCondition(string $query = ''): ?AccessCondition
+    {
+        $elements = $this->getAccessConditions($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <classification> elements.
      * @see https://www.loc.gov/standards/mods/userguide/classification.html
@@ -124,6 +163,45 @@ public function getClassifications(string $query = ''): array
         return $classifications;
     }
 
+    /**
+     * Get the the first matching <classification> element.
+     * @see https://www.loc.gov/standards/mods/userguide/classification.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Classification
+     */
+    public function getFirstClassification(string $query = ''): ?Classification
+    {
+        $elements = $this->getClassifications($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <classification> element.
+     * @see https://www.loc.gov/standards/mods/userguide/classification.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Classification
+     */
+    public function getLastClassification(string $query = ''): ?Classification
+    {
+        $elements = $this->getClassifications($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <extension> elements.
      * @see https://www.loc.gov/standards/mods/userguide/extension.html
@@ -145,6 +223,45 @@ public function getExtensions(string $query = ''): array
         return $extensions;
     }
 
+    /**
+     * Get the the first matching <extension> element.
+     * @see https://www.loc.gov/standards/mods/userguide/extension.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Extension
+     */
+    public function getFirstExtension(string $query = ''): ?Extension
+    {
+        $elements = $this->getExtensions($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <extension> element.
+     * @see https://www.loc.gov/standards/mods/userguide/extension.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Extension
+     */
+    public function getLastExtension(string $query = ''): ?Extension
+    {
+        $elements = $this->getExtensions($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <genre> elements.
      * @see https://www.loc.gov/standards/mods/userguide/genre.html
@@ -166,6 +283,45 @@ public function getGenres(string $query = ''): array
         return $genres;
     }
 
+    /**
+     * Get the the first matching <genre> element.
+     * @see https://www.loc.gov/standards/mods/userguide/genre.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Genre
+     */
+    public function getFirstGenre(string $query = ''): ?Genre
+    {
+        $elements = $this->getGenres($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <genre> element.
+     * @see https://www.loc.gov/standards/mods/userguide/genre.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Genre
+     */
+    public function getLastGenre(string $query = ''): ?Genre
+    {
+        $elements = $this->getGenres($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <identifier> elements.
      * @see https://www.loc.gov/standards/mods/userguide/identifier.html
@@ -187,6 +343,45 @@ public function getIdentifiers(string $query = ''): array
         return $identifiers;
     }
 
+    /**
+     * Get the the first matching <identifier> element.
+     * @see https://www.loc.gov/standards/mods/userguide/identifier.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Identifier
+     */
+    public function getFirstIdentifier(string $query = ''): ?Identifier
+    {
+        $elements = $this->getIdentifiers($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <identifier> element.
+     * @see https://www.loc.gov/standards/mods/userguide/identifier.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Identifier
+     */
+    public function getLastIdentifier(string $query = ''): ?Identifier
+    {
+        $elements = $this->getIdentifiers($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the array of the <language> elements.
      * @see https://www.loc.gov/standards/mods/userguide/language.html
@@ -208,6 +403,45 @@ public function getLanguages(string $query = ''): array
         return $languages;
     }
 
+    /**
+     * Get the the first matching <language> element.
+     * @see https://www.loc.gov/standards/mods/userguide/language.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Language
+     */
+    public function getFirstLanguage(string $query = ''): ?Language
+    {
+        $elements = $this->getLanguages($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <language> element.
+     * @see https://www.loc.gov/standards/mods/userguide/language.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Language
+     */
+    public function getLastLanguage(string $query = ''): ?Language
+    {
+        $elements = $this->getLanguages($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <location> elements.
      * @see https://www.loc.gov/standards/mods/userguide/location.html
@@ -229,6 +463,45 @@ public function getLocations(string $query = ''): array
         return $locations;
     }
 
+    /**
+     * Get the the first matching <location> element.
+     * @see https://www.loc.gov/standards/mods/userguide/location.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Location
+     */
+    public function getFirstLocation(string $query = ''): ?Location
+    {
+        $elements = $this->getLocations($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <location> element.
+     * @see https://www.loc.gov/standards/mods/userguide/location.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Location
+     */
+    public function getLastLocation(string $query = ''): ?Location
+    {
+        $elements = $this->getLocations($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <name> elements.
      * @see https://www.loc.gov/standards/mods/userguide/name.html
@@ -250,6 +523,45 @@ public function getNames(string $query = ''): array
         return $names;
     }
 
+    /**
+     * Get the the first matching <name> element.
+     * @see https://www.loc.gov/standards/mods/userguide/name.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Name
+     */
+    public function getFirstName(string $query = ''): ?Name
+    {
+        $elements = $this->getNames($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <name> element.
+     * @see https://www.loc.gov/standards/mods/userguide/name.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Name
+     */
+    public function getLastName(string $query = ''): ?Name
+    {
+        $elements = $this->getNames($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <note> elements.
      * @see https://www.loc.gov/standards/mods/userguide/note.html
@@ -271,6 +583,45 @@ public function getNotes(string $query = ''): array
         return $notes;
     }
 
+    /**
+     * Get the the first matching <note> element.
+     * @see https://www.loc.gov/standards/mods/userguide/note.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Note
+     */
+    public function getFirstNote(string $query = ''): ?Note
+    {
+        $elements = $this->getNames($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <note> element.
+     * @see https://www.loc.gov/standards/mods/userguide/note.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Note
+     */
+    public function getLastNote(string $query = ''): ?Note
+    {
+        $elements = $this->getNotes($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
      /**
      * Get the the array of the <originInfo> elements.
      * @see https://www.loc.gov/standards/mods/userguide/origininfo.html
@@ -292,6 +643,45 @@ public function getOriginInfos(string $query = ''): array
         return $originInfos;
     }
 
+    /**
+     * Get the the first matching <originInfo> element.
+     * @see https://www.loc.gov/standards/mods/userguide/origininfo.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?OriginInfo
+     */
+    public function getFirstOriginInfo(string $query = ''): ?OriginInfo
+    {
+        $elements = $this->getOriginInfos($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <originInfo> element.
+     * @see https://www.loc.gov/standards/mods/userguide/origininfo.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?OriginInfo
+     */
+    public function getLastOriginInfo(string $query = ''): ?OriginInfo
+    {
+        $elements = $this->getOriginInfos($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <part> elements.
      * @see https://www.loc.gov/standards/mods/userguide/part.html
@@ -313,6 +703,45 @@ public function getParts(string $query = ''): array
         return $parts;
     }
 
+    /**
+     * Get the the first matching <part> element.
+     * @see https://www.loc.gov/standards/mods/userguide/part.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Part
+     */
+    public function getFirstPart(string $query = ''): ?Part
+    {
+        $elements = $this->getParts($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <part> element.
+     * @see https://www.loc.gov/standards/mods/userguide/part.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Part
+     */
+    public function getLastPart(string $query = ''): ?Part
+    {
+        $elements = $this->getParts($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <physicalDescription> elements.
      * @see https://www.loc.gov/standards/mods/userguide/physicaldescription.html
@@ -334,6 +763,45 @@ public function getPhysicalDescriptions(string $query = ''): array
         return $physicalDescriptions;
     }
 
+    /**
+     * Get the the first matching <physicalDescription> element.
+     * @see https://www.loc.gov/standards/mods/userguide/physicaldescription.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?PhysicalDescription
+     */
+    public function getFirstPhysicalDescription(string $query = ''): ?PhysicalDescription
+    {
+        $elements = $this->getPhysicalDescriptions($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <physicalDescription> element.
+     * @see https://www.loc.gov/standards/mods/userguide/physicaldescription.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?PhysicalDescription
+     */
+    public function getLastPhysicalDescription(string $query = ''): ?PhysicalDescription
+    {
+        $elements = $this->getPhysicalDescriptions($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <recordInfo> elements.
      * @see https://www.loc.gov/standards/mods/userguide/recordinfo.html
@@ -355,6 +823,45 @@ public function getRecordInfos(string $query = ''): array
         return $recordInfos;
     }
 
+    /**
+     * Get the the first matching <recordInfo> element.
+     * @see https://www.loc.gov/standards/mods/userguide/recordinfo.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?RecordInfo
+     */
+    public function getFirstRecordInfo(string $query = ''): ?RecordInfo
+    {
+        $elements = $this->getRecordInfos($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <recordInfo> element.
+     * @see https://www.loc.gov/standards/mods/userguide/recordinfo.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?RecordInfo
+     */
+    public function getLastRecordInfo(string $query = ''): ?RecordInfo
+    {
+        $elements = $this->getRecordInfos($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <relatedItem> elements.
      * @see https://www.loc.gov/standards/mods/userguide/relateditem.html
@@ -376,6 +883,45 @@ public function getRelatedItems(string $query = ''): array
         return $relatedItems;
     }
 
+    /**
+     * Get the the first matching <relatedItem> element.
+     * @see https://www.loc.gov/standards/mods/userguide/relateditem.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?RelatedItem
+     */
+    public function getFirstRelatedItem(string $query = ''): ?RelatedItem
+    {
+        $elements = $this->getRelatedItems($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <relatedItem> element.
+     * @see https://www.loc.gov/standards/mods/userguide/relateditem.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?RelatedItem
+     */
+    public function getLastRelatedItem(string $query = ''): ?RelatedItem
+    {
+        $elements = $this->getRelatedItems($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <subject> elements.
      * @see https://www.loc.gov/standards/mods/userguide/subject.html
@@ -397,6 +943,45 @@ public function getSubjects(string $query = ''): array
         return $subjects;
     }
 
+    /**
+     * Get the the first matching <subject> element.
+     * @see https://www.loc.gov/standards/mods/userguide/subject.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Subject
+     */
+    public function getFirstSubject(string $query = ''): ?Subject
+    {
+        $elements = $this->getSubjects($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <subject> element.
+     * @see https://www.loc.gov/standards/mods/userguide/subject.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?Subject
+     */
+    public function getLastSubject(string $query = ''): ?Subject
+    {
+        $elements = $this->getSubjects($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <tableOfContents> elements.
      * @see https://www.loc.gov/standards/mods/userguide/tableofcontents.html
@@ -418,6 +1003,45 @@ public function getTableOfContents(string $query = ''): array
         return $tableOfContents;
     }
 
+    /**
+     * Get the the first matching <tableOfContents> element.
+     * @see https://www.loc.gov/standards/mods/userguide/tableofcontents.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?TableOfContents
+     */
+    public function getFirstTableOfContents(string $query = ''): ?TableOfContents
+    {
+        $elements = $this->getTableOfContents($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <tableOfContents> element.
+     * @see https://www.loc.gov/standards/mods/userguide/tableofcontents.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?TableOfContents
+     */
+    public function getLastTableOfContents(string $query = ''): ?TableOfContents
+    {
+        $elements = $this->getTableOfContents($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <targetAudience> elements.
      * @see https://www.loc.gov/standards/mods/userguide/targetaudience.html
@@ -428,7 +1052,7 @@ public function getTableOfContents(string $query = ''): array
      *
      * @return TargetAudience[]
      */
-    public function getTargetAudience(string $query = ''): array
+    public function getTargetAudiences(string $query = ''): array
     {
         $targetAudiences = [];
         $xpath = './mods:targetAudience' . $query;
@@ -439,6 +1063,45 @@ public function getTargetAudience(string $query = ''): array
         return $targetAudiences;
     }
 
+    /**
+     * Get the the first matching <targetAudience> element.
+     * @see https://www.loc.gov/standards/mods/userguide/targetaudience.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?TargetAudience
+     */
+    public function getFirstTargetAudience(string $query = ''): ?TargetAudience
+    {
+        $elements = $this->getTargetAudiences($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <targetAudience> element.
+     * @see https://www.loc.gov/standards/mods/userguide/targetaudience.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?TargetAudience
+     */
+    public function getLastTargetAudience(string $query = ''): ?TargetAudience
+    {
+        $elements = $this->getTargetAudiences($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the the array of the <titleInfo> elements.
      * @see https://www.loc.gov/standards/mods/userguide/titleinfo.html
@@ -460,6 +1123,45 @@ public function getTitleInfos(string $query = ''): array
         return $titleInfos;
     }
 
+    /**
+     * Get the the first matching <titleInfo> element.
+     * @see https://www.loc.gov/standards/mods/userguide/titleinfo.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?TitleInfo
+     */
+    public function getFirstTitleInfo(string $query = ''): ?TitleInfo
+    {
+        $elements = $this->getTitleInfos($query);
+        if (count($elements) > 0) {
+            return $elements[0];
+        }
+        return null;
+    }
+
+    /**
+     * Get the the last matching <titleInfo> element.
+     * @see https://www.loc.gov/standards/mods/userguide/titleinfo.html
+     *
+     * @access public
+     *
+     * @param string $query The XPath query for metadata search
+     *
+     * @return ?TitleInfo
+     */
+    public function getLastTitleInfo(string $query = ''): ?TitleInfo
+    {
+        $elements = $this->getTitleInfos($query);
+        $count = count($elements);
+        if ($count > 0) {
+            return $elements[$count - 1];
+        }
+        return null;
+    }
+
     /**
      * Get the value of the <typeOfResource> element.
      * @see https://www.loc.gov/standards/mods/userguide/typeofresource.html