Merge pull request #31 from kiwilan/develop

v1.0.2

CHANGELOG.md

@@ -2,16 +2,9 @@
 
 All notable changes to `php-opds` will be documented in this file.
 
-## v1.x.x - 2023-09-13
-
-- Update `OpdsJsonEngine` to use these options for OPDS 2.0 output - @todo OPDS 1.2 was not adapted in this PR
-- Add `properties` option for `OpdsEntryNavigation` to include extra properties (like numberOfItems for facets)
-- Add `relation` option for `OpdsEntryNavigation` to specify the relation to use (instead of `current`)
-- Add `identifier` option for `OpdsEntryBook` to specify the actual identifier to use (instead of `urn:isbn:...`)
-
 ## v1.0.1 - 2023-09-07
 
-- Add `useAutoPagination` option for `OpdsConfig` to enable/disable auto pagination (works only for `OpdsEntryBook`)
+-   Add `useAutoPagination` option for `OpdsConfig` to enable/disable auto pagination (works only for `OpdsEntryBook`)
 
 ## v1.0.0 - 2023-09-06
 
@@ -21,7 +14,7 @@ This version rework completely the library, it's not compatible with previous ve
 
 #### `Opds::class`
 
-- static method `response()` removed, now static method is `Opds::make()` and `get()` is a arrow method:
+-   static method `response()` removed, now static method is `Opds::make()` and `get()` is a arrow method:
 
 ```php
 $opds = Opds::make()
@@ -31,28 +24,28 @@ return $opds->send(); // `never` because send response
 
 
 ```
-- To add `entries`, you have to use `feeds()` arrow method   
-     
-  - `feeds()` accept `OpdsEntryBook[]` or `OpdsEntryNavigation[]` but also `OpdsEntryNavigation` or `OpdsEntryBook`   
-
-- To add `isSearch`, you have to use `isSearch()` arrow method   
-  
-- To add `title`, you have to use `title()` arrow method   
-  
-- To add `url`, you have to use `url()` arrow method (only for testing, URL is automatically generated)   
-  
-- OPDS version can be handle by query param `version`: `?version=2.0` or `?version=1.2`   
-  
-- To get generate response and keep `Opds::class` instance, you can use `get()` arrow method   
-  
-- To get response as XML or JSON, you can use `send()` arrow method   
-  
-- `asString` param removed, now you can use `get()` arrow method to debug response   
-  
-- To get response after `get()` you can use `getResponse()` arrow method (different that `send()` will return full content as `never` with headers)   
-  
-- Add fallback for old OPDS versions to v1.2   
-  
+
+-   To add `entries`, you have to use `feeds()` arrow method
+
+    -   `feeds()` accept `OpdsEntryBook[]` or `OpdsEntryNavigation[]` but also `OpdsEntryNavigation` or `OpdsEntryBook`
+
+-   To add `isSearch`, you have to use `isSearch()` arrow method
+
+-   To add `title`, you have to use `title()` arrow method
+
+-   To add `url`, you have to use `url()` arrow method (only for testing, URL is automatically generated)
+
+-   OPDS version can be handle by query param `version`: `?version=2.0` or `?version=1.2`
+
+-   To get generate response and keep `Opds::class` instance, you can use `get()` arrow method
+
+-   To get response as XML or JSON, you can use `send()` arrow method
+
+-   `asString` param removed, now you can use `get()` arrow method to debug response
+
+-   To get response after `get()` you can use `getResponse()` arrow method (different that `send()` will return full content as `never` with headers)
+
+-   Add fallback for old OPDS versions to v1.2
 
 ```php
 use Kiwilan\Opds\Opds;
@@ -70,87 +63,86 @@ $opds = Opds::make(new OpdsConfig()) // Accept `OpdsConfig::class`
 
 
 ```
+
 #### Misc
 
-- `OpdsConfig`   
-
-  - `usePagination` is now default to `false`   
-  - `forceJson` param allow to skip OPDS 1.2   
-  - `searchQuery` removed from `OpdsConfig` because query parameter is statically defined (`q` for OPDS 1.2, `query` for OPDS 2.0)   
-
-- `OpdsEntry` is now `OpdsEntryNavigation`   
-
-- `OpdsEngine` rewrite completely   
-
-- `OpdsResponse` can be debug with `getContents()` method to inspect response (accessible if you use `get()` method)   
-
-- `OpdsEntry` items have now `get` prefix for all getter   
-
-- remove modules system   
-
-- `OpdsEngine` property `xml` is now `contents`   
-
-  - `getXml()` is now `getContents()`   
-  - add setter `setContents()`   
-
+-   `OpdsConfig`
+
+    -   `usePagination` is now default to `false`
+    -   `forceJson` param allow to skip OPDS 1.2
+    -   `searchQuery` removed from `OpdsConfig` because query parameter is statically defined (`q` for OPDS 1.2, `query` for OPDS 2.0)
+
+-   `OpdsEntry` is now `OpdsEntryNavigation`
+
+-   `OpdsEngine` rewrite completely
+
+-   `OpdsResponse` can be debug with `getContents()` method to inspect response (accessible if you use `get()` method)
+
+-   `OpdsEntry` items have now `get` prefix for all getter
+
+-   remove modules system
+
+-   `OpdsEngine` property `xml` is now `contents`
+
+    -   `getXml()` is now `getContents()`
+    -   add setter `setContents()`
 
 ### Added
 
-- add ODPS 2.0 support partially
-- add setters to `OpdsEntry`
-- XML pagination is now supported
-- JSON pagination is now supported
-- rewrite documentation
-- `Opds` improve `send()` with new parameter `mock`, a boolean to send the response or not.
-- Move all `enum` to `Kiwilan\Opds\Enums` namespace.
-- Add new `OpdsPaginator` class to handle pagination
-- more tests
+-   add ODPS 2.0 support partially
+-   add setters to `OpdsEntry`
+-   XML pagination is now supported
+-   JSON pagination is now supported
+-   rewrite documentation
+-   `Opds` improve `send()` with new parameter `mock`, a boolean to send the response or not.
+-   Move all `enum` to `Kiwilan\Opds\Enums` namespace.
+-   Add new `OpdsPaginator` class to handle pagination
+-   more tests
 
 ## 0.3.12 - 2023-05-09
 
-- Change default pagination from `15` to `32`
-- Add more characters for `content` property of `OpdsEntryBook`
+-   Change default pagination from `15` to `32`
+-   Add more characters for `content` property of `OpdsEntryBook`
 
 ## 0.3.11 - 2023-05-09
 
-- `media` mime type fix
+-   `media` mime type fix
 
 ## 0.3.10 - 2023-05-09
 
-- `OpdsEntryBook` add `content` property with HTML
+-   `OpdsEntryBook` add `content` property with HTML
 
 ## 0.3.0 - 2023-05-09
 
-- add `OpdsVersionEnum` for `version`
-- `OpdsVersionOneDotTwoModule` is now `Opds1Dot2Module`
+-   add `OpdsVersionEnum` for `version`
+-   `OpdsVersionOneDotTwoModule` is now `Opds1Dot2Module`
 
 ## 0.2.0 - 2023-05-09
 
-- `OpdsApp` is now `OpdsConfig`   
-
-  - `Opds` property `app` is now `config`   
-
-- `OpdsEntry`, `OpdsEntryBook`, `OpdsEntryBookAuthor` has now namespace `Kiwilan\Opds\Entries`   
-
-- `OpdsXmlConverter` is has now one static method   
-
+-   `OpdsApp` is now `OpdsConfig`
+
+    -   `Opds` property `app` is now `config`
+
+-   `OpdsEntry`, `OpdsEntryBook`, `OpdsEntryBookAuthor` has now namespace `Kiwilan\Opds\Entries`
+
+-   `OpdsXmlConverter` is has now one static method
 
 ## 0.1.30 - 2023-05-09
 
-- add pagination feature, see `usePagination` and `maxItemsPerPage` in `OpdsConfig`
-- add `OpdsConfig` property: `iconUrl`
+-   add pagination feature, see `usePagination` and `maxItemsPerPage` in `OpdsConfig`
+-   add `OpdsConfig` property: `iconUrl`
 
 ## 0.1.21 - 2023-05-09
 
-- search template fixing
+-   search template fixing
 
 ## 0.1.20 - 2023-05-09
 
-- add `OpdsEntryBookAuthor`
+-   add `OpdsEntryBookAuthor`
 
 ## 0.1.10 - 2023-05-09
 
-- Add documentation
+-   Add documentation
 
 ## 0.1.0 - 2023-05-09
 

README.md

@@ -212,6 +212,7 @@ $config = new OpdsConfig(
   startUrl: 'https://example.com/opds', // Start URL, will be included in top navigation
   searchUrl: 'https://example.com/opds/search', // Search URL, will be included in top navigation
   versionQuery: 'version', // query parameter for version
+  paginationQuery: 'page', // query parameter for pagination
   updated: new DateTime(), // Last update of OPDS feed
   usePagination: false, // To enable pagination, default is false
   useAutoPagination: false, // To enable auto pagination, default is false, if `usePagination` is true, this option will be ignored
@@ -248,6 +249,10 @@ $entry = new OpdsEntryNavigation(
   summary: 'Authors, 1 available',
   media: 'https://user-images.githubusercontent.com/48261459/201463225-0a5a084e-df15-4b11-b1d2-40fafd3555cf.svg',
   updated: new DateTime(),
+  properties: [
+    'numberOfItems' => 1,
+  ], // to include extra properties (like numberOfItems for facets)
+  relation: 'current', // to specify the relation to use (instead of `current`)
 );
 ```
 
@@ -298,7 +303,8 @@ $entry = new OpdsEntryBook(
   volume: 1,
   serie: 'Earth\'s Children',
   language: 'English',
-  isbn: '9780553381672',
+  isbn: '9780553381672', // deprecated, use `identifier` instead
+  identifier: 'urn:isbn:9780553381672', // to specify the actual identifier to use (instead of `urn:isbn:...`)
   translator: 'translator',
   publisher: 'publisher',
 );

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "kiwilan/php-opds",
     "description": "PHP package to create OPDS feed for eBooks.",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "keywords": [
         "php",
         "ebook",

src/Engine/OpdsEngine.php

@@ -208,8 +208,13 @@ public static function addXmlLink(
         string $href = null,
         string $title = null,
         string $rel = null,
-        string $type = 'application/atom+xml;profile=opds-catalog;kind=acquisition',
+        string $type = 'application/atom+xml;profile=opds-catalog;kind=navigation',
+        bool $acquisition = false,
     ): array {
+        if ($acquisition) {
+            $type = 'application/atom+xml;profile=opds-catalog;kind=acquisition';
+        }
+
         return [
             '_attributes' => [
                 'rel' => $rel,
@@ -242,6 +247,10 @@ protected function route(?string $route): ?string
      */
     protected function paginate(array &$content, array &$feeds): void
     {
+        if (! $this->getOpds()->getConfig()->isUsePagination() && ! $this->getOpds()->getConfig()->isUseAutoPagination()) {
+            return;
+        }
+
         $this->paginator = OpdsPaginator::make($this)->paginate($content, $feeds);
     }
 }

src/Engine/OpdsJsonEngine.php

@@ -89,24 +89,18 @@ public function search(): self
 
     public function addNavigationEntry(OpdsEntryNavigation $entry): array
     {
-        $properties = $entry->getProperties();
-
-        if ($properties) {
-            return [
-                'href' => $this->route($entry->getRoute()),
-                'title' => $entry->getTitle(),
-                'type' => 'application/opds+json',
-                'rel' => $entry->getRelation() ?? 'current',
-                'properties' => $properties,
-            ];
-        }
-
-        return [
+        $item = [
             'href' => $this->route($entry->getRoute()),
             'title' => $entry->getTitle(),
             'type' => 'application/opds+json',
             'rel' => $entry->getRelation() ?? 'current',
         ];
+
+        if ($property = $entry->getProperties()) {
+            $item['properties'] = $property;
+        }
+
+        return $item;
     }
 
     public function addBookEntry(OpdsEntryBook $entry): array

src/Engine/OpdsPaginator.php

@@ -15,6 +15,7 @@ class OpdsPaginator
     protected function __construct(
         protected OpdsOutputEnum $output,
         protected string $versionQuery,
+        protected string $paginationQuery,
         protected string $url,
         protected array $query = [],
         protected bool $usePagination = false,
@@ -43,11 +44,13 @@ public static function make(OpdsEngine $engine): self
 
         $output = $engine->getOpds()->getOutput();
         $query = $engine->getOpds()->getQuery();
-        $page = $query['page'] ?? 1;
+        $pagination = $engine->getOpds()->getConfig()->getPaginationQuery();
+        $page = $query[$pagination] ?? 1;
 
         return new self(
             output: $output,
             versionQuery: $engine->getOpds()->getConfig()->getVersionQuery(),
+            paginationQuery: $pagination,
             url: $url,
             query: $query,
             usePagination: $engine->getOpds()->getConfig()->isUsePagination(),
@@ -196,24 +199,24 @@ private function json(array &$content): void
         if ($this->page !== 1) {
             $content['links'][] = OpdsEngine::addJsonLink(
                 rel: 'first',
-                href: $this->route($this->url, ['page' => 1]),
+                href: $this->route($this->url, [$this->paginationQuery => 1]),
             );
 
             $content['links'][] = OpdsEngine::addJsonLink(
                 rel: 'previous',
-                href: $this->route($this->url, ['page' => $this->page - 1]),
+                href: $this->route($this->url, [$this->paginationQuery => $this->page - 1]),
             );
         }
 
         if ($this->page !== $this->size) {
             $content['links'][] = OpdsEngine::addJsonLink(
                 rel: 'next',
-                href: $this->route($this->url, ['page' => $this->page + 1]),
+                href: $this->route($this->url, [$this->paginationQuery => $this->page + 1]),
             );
 
             $content['links'][] = OpdsEngine::addJsonLink(
                 rel: 'last',
-                href: $this->route($this->url, ['page' => $this->size]),
+                href: $this->route($this->url, [$this->paginationQuery => $this->size]),
             );
         }
     }

src/Entries/OpdsEntryBook.php

@@ -9,6 +9,7 @@ class OpdsEntryBook extends OpdsEntryNavigation
     /**
      * @param  string[]  $categories
      * @param  OpdsEntryBookAuthor[]  $authors
+     * @param  ?string  $isbn @deprecated Use `identifier` instead
      */
     public function __construct(
         protected string $id,