Institusion token support added

.gitattributes

@@ -0,0 +1,9 @@
+# Keep the distributed package to the code consumers actually need.
+# Without this, `composer require` pulls the whole generated docs site
+# (~120 HTML files), the test suite and the CI config into vendor/.
+/docs             export-ignore
+/tests            export-ignore
+/.github          export-ignore
+/phpunit.xml.dist export-ignore
+/.gitattributes   export-ignore
+/.gitignore       export-ignore

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version: ['7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5']
+        dependencies: ['highest']
+        include:
+          # Guzzle 8 wins on every supported PHP, so without this leg the
+          # ^7.15.2 half of the guzzle constraint is never exercised.
+          - php-version: '7.4'
+            dependencies: 'lowest'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php-version }}
+        coverage: none
+        tools: composer:v2
+
+    - name: Validate composer.json
+      run: composer validate --strict
+
+    - name: Install dependencies
+      run: composer update --prefer-dist --no-progress ${{ matrix.dependencies == 'lowest' && '--prefer-lowest' || '' }}
+
+    - name: Lint PHP files
+      run: find src tests -name "*.php" -print0 | xargs -0 -n1 php -l
+
+    - name: Run tests
+      run: vendor/bin/phpunit

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Docs
+
+# CI is the only thing that generates docs/. That is deliberate: ApiGen lists
+# implementing classes in filesystem order without sorting them, so the same
+# source produces different output on macOS and Linux. Keeping generation on one
+# platform makes the result reproducible; regenerating by hand reintroduces the
+# churn. docs/** is not a trigger, so the commit below cannot retrigger this.
+on:
+  push:
+    branches: [ "master" ]
+    paths:
+      - 'src/**'
+      - 'composer.json'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs
+  cancel-in-progress: false
+
+jobs:
+  regenerate:
+    name: Regenerate API documentation
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.3'
+        coverage: none
+        tools: composer:v2
+
+    - name: Install dependencies
+      run: composer update --prefer-dist --no-progress
+
+    - name: Download ApiGen
+      run: curl -sSfL -o apigen.phar https://github.com/ApiGen/ApiGen/releases/download/v7.0.0-alpha.6/apigen.phar
+
+    - name: Regenerate
+      # --workers 1 is required: the parallel scheduler crashes when ApiGen runs
+      # from a PHAR.
+      run: |
+        php apigen.phar --workers 1 --output docs \
+          --title "Scopus API for PHP" \
+          --base-url "https://grinchenkoedu.github.io/scopus-api-php/" \
+          src
+
+    - name: Commit if it changed
+      run: |
+        if git diff --quiet -- docs; then
+          echo "docs/ is already up to date."
+          exit 0
+        fi
+        git config user.name  "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git add docs
+        git commit -m "docs: regenerate API documentation"
+        git push
+        echo "Regenerated docs/ and pushed."

.gitignore

@@ -2,4 +2,6 @@ composer.phar
 composer.lock
 composer-test.lock
 vendor/
-.idea
+.idea
+.tasks/
+.claude/

CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.5.0] - 2026-09-02
+
+### Added
+- PHPUnit test suite covering the API client, the query builder, the response DTOs and the XML
+  utility, using Guzzle's `MockHandler` so no test touches the network.
+- GitHub Actions CI running the suite on PHP 7.4 through 8.5.
+- `.gitattributes`, so the distributed package no longer ships `docs/`, `tests/` and the CI config.
+
+### Changed
+- The minimum PHP version is now 7.4, up from 7.2, and the constraint is bounded at
+  `^7.4 || ^8.0`. PHP 7.2 and 7.3 reached end of life in November 2020 and December 2021.
+  Supporting them forced `require-dev` to span PHPUnit 8.5 to 11 and split the dependency graph
+  across two Guzzle majors. No public API changed: projects still on PHP 7.2 or 7.3 keep
+  resolving to 1.4.1 rather than failing to install.
+
+### Removed
+- `docs/`, `tests/` and the CI configuration are no longer part of the distributed package, and
+  the manual `test/test.php` script is gone. Nothing under `vendor/` should have referenced them,
+  but the paths do disappear.
+
+### Fixed
+- `XmlUtil::toArray()` no longer calls `each()`, which was removed in PHP 8.
+- XML parse failures no longer emit raw PHP warnings, and no longer crash when
+  `libxml_get_last_error()` returns `false`.
+- Getters in `Scopus\Response` return `null` for a missing key instead of raising
+  `Undefined array key`; Scopus routinely omits fields.
+- Nullable parameters are declared explicitly, clearing the PHP 8.4 deprecation.
+
+## [1.4.2] - 2026-09-01
+
+Maintenance release on the `1.4.x` branch, for PHP 7.2 and 7.3, which cannot install 1.5.0.
+Same fixes as 1.5.0, cut before the PHP requirement moved to 7.4.
+
+## [1.4.1] - 2026-09-01
+
+### Changed
+- Prepared for Packagist: updated package name to `grinchenkoedu/scopus-search-api`.
+- Added Yevhen Matasar to the authors list.
+- Upgraded Composer autoloading to PSR-4.
+
+### Security
+- Fixed SSRF vulnerability by updating the `guzzlehttp/guzzle` requirement to `^7.15.2 || ^8.0.1`.
+
+## [1.4.0] - 2023-05-14
+
+### Added
+- Added institution token support.
+
+### Changed
+- Updated `guzzlehttp/guzzle` to the latest version (7.6).
+- Restored `retrieve` and `query` methods back to `public` visibility.
+
+## [1.3.0] - 2022-05-01
+
+### Added
+- Added Abstract Citations Count API.
+
+## [1.2.0] - 2021-11-14
+
+### Added
+- Added `hasError` method for better error handling.
+
+### Changed
+- Bumped `guzzlehttp/guzzle` version constraint to `>=6.3`.
+
+### Fixed
+- Fixed year parsing in the `getYear` method.
+
+## [1.1.0] - 2020-05-19
+
+### Added
+- Added Search Author API.
+- Added Citation Overview API (including fetching multiple documents).
+- Added `openaccessFlag` to the `Entry` class.
+- Created a support function to retrieve documents of a specific author easily.
+- Generated initial API documentation using ApiGen.
+
+### Changed
+- Updated various classes (`AbstractCitations`, `Source`, etc.) for better compatibility.
+
+[Unreleased]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.5.0...HEAD
+[1.5.0]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.4.2...1.5.0
+[1.4.2]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.4.1...1.4.2
+[1.4.1]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.4.0...1.4.1
+[1.4.0]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.3.0...1.4.0
+[1.3.0]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.2.0...1.3.0
+[1.2.0]: https://github.com/grinchenkoedu/scopus-api-php/compare/1.1.0...1.2.0
+[1.1.0]: https://github.com/grinchenkoedu/scopus-api-php/releases/tag/1.1.0

README.md

@@ -1,8 +1,13 @@
-# Scopus API for PHP (Unofficial)
+# Scopus API for PHP
 
-PHP SDK for [Scopus APIs](https://dev.elsevier.com/scopus.html)
+[![CI](https://github.com/grinchenkoedu/scopus-api-php/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/grinchenkoedu/scopus-api-php/actions/workflows/ci.yml)
+[![Latest Stable Version](https://img.shields.io/packagist/v/grinchenkoedu/scopus-search-api)](https://packagist.org/packages/grinchenkoedu/scopus-search-api)
+[![PHP Version Require](https://img.shields.io/packagist/php-v/grinchenkoedu/scopus-search-api)](https://packagist.org/packages/grinchenkoedu/scopus-search-api)
+[![License](https://img.shields.io/packagist/l/grinchenkoedu/scopus-search-api)](https://packagist.org/packages/grinchenkoedu/scopus-search-api)
 
-Currently, supported APIs:
+A third party PHP SDK for [Scopus APIs](https://dev.elsevier.com/scopus.html).
+
+Currently supported APIs:
 - Scopus Search API
 - Abstract Retrieval API
 - Author Retrieval API
@@ -11,18 +16,28 @@ Currently, supported APIs:
     - Citation Overview API
 - Abstract Citations Count API
 
+## Requirements
+
+- PHP 7.4 – 8.x
+- `guzzlehttp/guzzle` ^7.15.2 || ^8.0.1
+
 ## Installation
 
-`composer require kasparsj/scopus-search-api` 
+Install the package via Composer:
 
-## Usage:
+```bash
+composer require grinchenkoedu/scopus-search-api
+```
+
+## Usage
 
 ```php
 use Scopus\ScopusApi;
+use Scopus\ScopusApiFactory;
 
 // replace with your API key
-$apiKey = "114ff0c3b57a0ec62e15efdedefd2e6f";
-$api = new ScopusApi($apiKey);
+$apiKey = "your-api-key-here";
+$api = (new ScopusApiFactory($apiKey))->createApiClient();
 
 // Scopus Search API
 $results = $api
@@ -56,15 +71,48 @@ foreach ($results->getEntries() as $entry) {
 
 ## API Docs
 
-https://kasparsj.github.io/scopus-api-php/
+Official API documentation:
+[https://grinchenkoedu.github.io/scopus-api-php/](https://grinchenkoedu.github.io/scopus-api-php/)
+
+## Development
+
+Install the development dependencies and run the test suite:
+
+```bash
+composer install
+vendor/bin/phpunit
+```
+
+Coverage is not configured in `phpunit.xml.dist`, because the source filter is
+spelled differently in PHPUnit 9 and PHPUnit 10+ and this package supports both.
+Request it on the command line instead:
+
+```bash
+vendor/bin/phpunit --coverage-text --coverage-filter src   # PHPUnit 10 and 11
+vendor/bin/phpunit --coverage-text --whitelist src         # PHPUnit 8.5 and 9
+```
+
+### API documentation
+
+`docs/` is generated output, published at the API Docs link above via GitHub Pages
+(`master` branch, `/docs` folder). **You do not need to regenerate it by hand** — the
+**Docs** workflow rebuilds it on every change to `src/` or `composer.json` and commits
+the result.
+
+Generation is kept on CI on purpose: ApiGen lists implementing classes in filesystem
+order without sorting them, so the same source produces different output on macOS and
+on Linux. Running it in one place keeps the result reproducible.
 
 ## Changelog
-- 01/05/2022 - v1.3
-  * Added Abstract Citations Count API
-- 14/11/2021 - v1.2
-  *  Bug fix
-- 19/05/2020 - v1.1
-  * Added Search Author API
-  * Added Citation Overview API
-  * Created a support function to retrieve Document of specific Author easly
-  * Updated classes
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+
+## Contributors
+
+Thanks to all the contributors who have helped build and maintain this package:
+
+![Contributors](https://contrib.rocks/image?repo=grinchenkoedu/scopus-api-php)
+
+## License
+
+This project is licensed under the MIT License.

composer.json

@@ -1,9 +1,24 @@
 {
-  "name": "kasparsj/scopus-search-api",
+  "name": "grinchenkoedu/scopus-search-api",
   "description": "Scopus API for PHP (Unofficial)",
+  "keywords": [
+    "scopus",
+    "elsevier",
+    "api",
+    "sdk",
+    "bibliometrics",
+    "citations",
+    "abstracts",
+    "research"
+  ],
+  "homepage": "https://github.com/grinchenkoedu/scopus-api-php",
+  "support": {
+    "issues": "https://github.com/grinchenkoedu/scopus-api-php/issues",
+    "source": "https://github.com/grinchenkoedu/scopus-api-php",
+    "docs": "https://grinchenkoedu.github.io/scopus-api-php/"
+  },
   "minimum-stability": "stable",
   "license": "MIT",
-  "version": "1.3",
   "authors": [
     {
       "name": "Kaspars Jaudzems",
@@ -12,14 +27,28 @@
     {
       "name": "Antonino Bonanno",
       "email": "nino.bonanno96@gmail.com"
+    },
+    {
+      "name": "Yevhen Matasar",
+      "email": "matasar.ei@gmail.com"
     }
   ],
   "require": {
-    "guzzlehttp/guzzle": ">=6.3.0"
+    "php": "^7.4 || ^8.0",
+    "guzzlehttp/guzzle": "^7.15.2 || ^8.0.1"
   },
   "autoload": {
-    "psr-0": {
-      "Scopus\\": "src/"
+    "psr-4": {
+      "Scopus\\": "src/Scopus/"
     }
-  }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Scopus\\Tests\\": "tests/"
+    }
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^9.5 || ^10.0 || ^11.0"
+  },
+  "type": "library"
 }