2.0.0

Author: lachlan-00

.gitattributes

@@ -1,3 +1,10 @@
+/.github export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.php-cs-fixer.php export-ignore
 /examples export-ignore
 /nbproject export-ignore
+/phpstan.neon export-ignore
+/phpunit.xml export-ignore
+/tests export-ignore
 /tools export-ignore

CHANGELOG.md

@@ -14,13 +14,25 @@ This version supports Ampache 6.2.0 and newer.
   * `api_format` selects `xml` or `json` responses
   * `server_version` selects the api version to talk to, defaulting to 6
   * `timeout` sets the per-request timeout in seconds
-  * `api_secure` selects `https` or `http`
 
 ### Changed (2.0.0)
 
 * `send_command()` returns a `SimpleXMLElement` or a decoded json array as the server sent it, replacing the structure 1.x assembled
 * Commands are checked against the api version in use, so a method that version does not serve is refused before the request is sent
 * `tag`, `tags`, `tag_albums`, `tag_artists` and `tag_songs` are refused from API5 onwards, and `get_indexes`, `playlist_add_song` and `user_update` from API8, matching the versions that dropped them
+* `api_secure` is consulted only when it is passed; otherwise the scheme on `server` selects `https` or `http`, and `https` remains the fallback when neither says
+* `__construct()` requires a config array, where 1.x defaulted it to an empty one
+* `debug_callback` receives `AmpacheApi\AmpacheApi/<version>` as its first argument in place of the bare `AmpacheApi` 1.x sent
+
+### Removed (2.0.0)
+
+* The public methods 1.x used to assemble its own response structure, made redundant by `send_command()` handing back the decoded response
+  * `parse_response()`
+  * `get_response()`
+  * `XML_create_parser()`
+  * `XML_cdata()`
+  * `XML_start_element()`
+  * `XML_end_element()`
 
 ### Fixed (2.0.0)
 

README.md

@@ -4,14 +4,14 @@ Ampache API PHP Library.
 
 ## NEWS
 
-Version 2 of this library is underway.
+Version 2 is out, and it is not a drop-in replacement for 1.x.
 
-There are major changes to help support multiple purposes as well as both XML and JSON responses.
-
-The library will now return a SimpleXMLElement or a decoded JSON array instead of the frankenstein.
+`send_command()` returns a SimpleXMLElement or a decoded JSON array exactly as the server sent it, instead of the structure 1.x assembled, so `last_error()` is now how you tell a successful call from a failed one.
 
 This version of the library is supported from Ampache 6.2.0+ and talks to API versions 3, 4, 5, 6 and 8. (Ampache has no API 7.)
 
+See the [CHANGELOG](CHANGELOG.md) for everything that moved.
+
 ## License
 
 Ampache API PHP Library is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License v3 (AGPLv3) as published by the Free Software Foundation.
@@ -25,11 +25,11 @@ When creating an AmpacheApi object config is set using a config array.
 * Required
   * username: string - Your API username
   * password: string - Your API password, plain or already sha256 hashed
-  * server: string - Server address; an `http://` or `https://` prefix is stripped, and `api_secure` decides which is used
+  * server: string - Server address, with or without an `http://` or `https://` prefix
 * Optional
   * debug: bool - Enable debug mode which will echo debug messages (default: false)
   * debug_callback: callable - Function that receives debug messages; it is called whether or not `debug` is on (default: null)
-  * api_secure: bool - Set to false to use http (default: true)
+  * api_secure: bool - Set to false to use http; when omitted, a scheme on `server` decides and https is the fallback
   * api_format: string - Set API response format. xml, json (default: xml)
   * server_version: int - Set API response version. 3, 4, 5, 6, 8 (default: 6)
   * timeout: int - Per request timeout in seconds (default: PHP's `default_socket_timeout`)

src/AmpacheApi.php

@@ -51,7 +51,7 @@ class AmpacheApi
         6 => '6.9.1',
         8 => '8.0.0',
     ];
-    private const LIB_VERSION = '2.0.0-develop';
+    private const LIB_VERSION = '2.0.0';
 
     /**
      * The api version each method was introduced in.
@@ -362,17 +362,24 @@ public function configure(array $config): bool
             $this->api_timeout = max(0, (int) $config['timeout']);
         }
 
+        $server = trim((string) $config['server']);
+        $scheme = (preg_match('#^(https?)://#i', $server, $matches) === 1)
+            ? strtolower($matches[1])
+            : '';
+
         if (isset($config['api_secure'])) {
             // This should be a boolean response
             $this->api_secure = (bool) $config['api_secure'];
+        } elseif ($scheme !== '') {
+            // nothing was asked for, so an address that names its scheme is the only instruction we have
+            $this->api_secure = ($scheme === 'https');
         }
         $protocol = $this->api_secure
             ? 'https://'
             : 'http://';
 
         // Strip whichever scheme the caller supplied; api_secure picks the one we use
-        $server        = (string) preg_replace('#^https?://#i', '', trim((string) $config['server']));
-        $server        = rtrim($server, '/');
+        $server        = rtrim((string) preg_replace('#^https?://#i', '', $server), '/');
         $this->api_url = $protocol . $server . '/server/' . $this->api_format . '.server.php';
 
         // See if we have enough to authenticate, if so change the state
@@ -452,12 +459,15 @@ public function connect(): bool
      */
     public function get_command_url(string $command, ?array $options = []): string
     {
+        if ($this->state() != 'READY' && $this->state() != 'CONNECTED') {
+            throw new Exception('AmpacheApi::get_command_url API in non-ready state, unable to build a url');
+        }
         $command = trim($command);
         if (!$command) {
-            throw new Exception('AmpacheApi::send_command no command specified');
+            throw new Exception('AmpacheApi::get_command_url no command specified');
         }
         if (!$this->validate_command($command)) {
-            throw new Exception('AmpacheApi::send_command Invalid/Unknown command ' . $command . ' issued');
+            throw new Exception('AmpacheApi::get_command_url Invalid/Unknown command ' . $command . ' issued');
         }
 
         $url = $this->api_url . '?action=' . urlencode($command);

tests/AmpacheApiTest.php

@@ -172,13 +172,25 @@ public function testOptionsAreUrlEncoded(): void
         self::assertStringContainsString('&rule_1_input=a+b%26c', $url);
     }
 
+    public function testSchemeInTheServerAddressDecidesWhenApiSecureIsNotAsked(): void
+    {
+        $api = $this->configured(['server' => 'http://localhost:8080']);
+
+        self::assertStringStartsWith('http://localhost:8080/server/', $api->get_command_url('ping'));
+    }
+
     public function testSchemeInTheServerAddressIsReplacedByTheOneApiSecureAsksFor(): void
     {
         $api = $this->configured(['server' => 'http://music.example', 'api_secure' => true]);
 
         self::assertStringStartsWith('https://music.example/server/', $api->get_command_url('ping'));
     }
 
+    public function testSchemelessAddressStaysOnHttps(): void
+    {
+        self::assertStringStartsWith('https://music.example/server/', $this->configured()->get_command_url('ping'));
+    }
+
     public function testStartsUnconfiguredAndBecomesReady(): void
     {
         $api = (new ReflectionClass(AmpacheApi::class))->newInstanceWithoutConstructor();
@@ -210,6 +222,14 @@ public function testUnknownCommandIsRefusedBeforeAnyRequest(): void
         $this->configured()->get_command_url('not_a_method');
     }
 
+    public function testUrlCannotBeBuiltBeforeTheClientIsConfigured(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('non-ready state');
+
+        (new ReflectionClass(AmpacheApi::class))->newInstanceWithoutConstructor()->get_command_url('ping');
+    }
+
     public function testUrlUsesTheFormatAsTheEndpoint(): void
     {
         self::assertStringStartsWith(