Remove ApiVersion::LATEST constant and require explicit version selection

lizkenyon · claude · lizkenyon · commit 93ea60c67eaf · 2025-10-15T11:50:16.000-05:00
Prevent semantic versioning violations where library updates automatically change API versions, potentially breaking production apps without developer awareness or control Breaking change: apiVersion parameter now required in Context::initialize() Migration: Developers must explicitly specify API version (e.g., '2025-10') Aligns with Ruby library PR #1411 and broader Shopify library strategy See BREAKING_CHANGES_FOR_V6.md for complete migration guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/BREAKING_CHANGES_FOR_V6.md b/BREAKING_CHANGES_FOR_V6.md
@@ -0,0 +1,84 @@
+# Breaking change notice for version 6.0.0
+
+## Removal of `ApiVersion::LATEST` constant
+
+The `ApiVersion::LATEST` constant has been removed to prevent semantic versioning (semver) breaking changes. Previously, this constant would automatically update every quarter when new API versions were released, causing unintended breaking changes for apps.
+
+### Migration Guide
+
+**If you were using the constant directly:**
+
+```php
+// Before (v5 and earlier)
+$apiVersion = ApiVersion::LATEST;
+
+// After (v6+)
+$apiVersion = '2025-07'; // Explicitly specify the version you want to use
+```
+
+**In your Context::initialize():**
+
+The `apiVersion` parameter is now **required** in `Context::initialize()`. You must explicitly specify which API version you want to use:
+
+```php
+// Before (v5 and earlier)
+Context::initialize(
+    apiKey: $_ENV['SHOPIFY_API_KEY'],
+    apiSecretKey: $_ENV['SHOPIFY_API_SECRET'],
+    scopes: $_ENV['SHOPIFY_APP_SCOPES'],
+    hostName: $_ENV['SHOPIFY_APP_HOST_NAME'],
+    sessionStorage: new FileSessionStorage('/tmp/php_sessions'),
+    // apiVersion was optional with default ApiVersion::LATEST
+);
+
+// After (v6+)
+Context::initialize(
+    apiKey: $_ENV['SHOPIFY_API_KEY'],
+    apiSecretKey: $_ENV['SHOPIFY_API_SECRET'],
+    scopes: $_ENV['SHOPIFY_APP_SCOPES'],
+    hostName: $_ENV['SHOPIFY_APP_HOST_NAME'],
+    sessionStorage: new FileSessionStorage('/tmp/php_sessions'),
+    apiVersion: '2025-07', // Now required - explicitly specify the version
+);
+```
+
+**Finding the right API version:**
+
+You can reference the available API versions in the `ApiVersion` class:
+
+```php
+use Shopify\ApiVersion;
+
+// Available constants (as of this release):
+ApiVersion::UNSTABLE      // "unstable"
+ApiVersion::JULY_2025     // "2025-07"
+ApiVersion::APRIL_2025    // "2025-04"
+ApiVersion::JANUARY_2025  // "2025-01"
+ApiVersion::OCTOBER_2024  // "2024-10"
+// ... and older versions
+```
+
+Or you can use string literals directly:
+
+```php
+Context::initialize(
+    // ... other parameters
+    apiVersion: '2025-07',
+);
+```
+
+**Why this change?**
+
+By requiring explicit version specification, apps can:
+- Control when they upgrade to new API versions
+- Test thoroughly before upgrading
+- Avoid unexpected breaking changes from automatic version updates
+- Follow semantic versioning principles more accurately
+
+**Recommended approach:**
+
+1. Review the [Shopify API release notes](https://shopify.dev/docs/api/release-notes) to understand changes between versions
+2. Choose the API version that best suits your app's needs
+3. Explicitly specify that version in your `Context::initialize()` call
+4. Test your app thoroughly with the chosen version
+5. Upgrade to newer versions on your own schedule after proper testing
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+- ⚠️ [Breaking] Remove `ApiVersion::LATEST` constant to prevent semver violations. The `apiVersion` parameter is now required in `Context::initialize()`. Developers must explicitly specify API versions. See the [migration guide](BREAKING_CHANGES_FOR_V6.md#removal-of-apiversionlatest-constant) for details.
 - [#425](https://github.com/Shopify/shopify-api-php/pull/425) [Patch] Add compliance webhook topics
 
 ## v5.11.0 - 2025-07-10
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -19,7 +19,7 @@ The first thing your app will need to do to use this library is to set up your c
 | `scopes`          | `string \| array` |    Yes    |      -       | App scopes                                                                                                                                                                           |
 | `hostName`        | `string`          |    Yes    |      -       | App host name e.g. `my-app.my-domain.ca`. You may optionally include `https://` or `http://` to determine which scheme to use                                                        |
 | `sessionStorage`  | `SessionStorage`  |    Yes    |      -       | Session storage strategy. Read our [notes on session handling](issues.md#notes-on-session-handling) for more information                                                             |
-| `apiVersion`      | `string`          |    No     | `ApiVersion::LATEST` | App API version, defaults to `ApiVersion::LATEST`                                                                                                                                                |
+| `apiVersion`      | `string`          |    Yes    |      -       | App API version. You must explicitly specify which API version to use (e.g., `'2025-07'`, `'2024-10'`, etc.)                                                                         |
 | `isEmbeddedApp`   | `bool`            |    No     |    `true`    | Whether the app is an embedded app                                                                                                                                                   |
 | `isPrivateApp`    | `bool`            |    No     |   `false`    | Whether the app is a private app                                                                                                                                                     |
 | `userAgentPrefix` | `string`          |    No     |      -       | Prefix for user agent header sent with a request                                                                                                                                     |
diff --git a/src/ApiVersion.php b/src/ApiVersion.php
@@ -66,8 +66,4 @@ class ApiVersion
      * @var string
      */
     public const JULY_2025 = "2025-07";
-    /**
-     * @var string
-     */
-    public const LATEST = self::JULY_2025;
 }
diff --git a/src/Context.php b/src/Context.php
@@ -60,7 +60,7 @@ class Context
      * @param string|array         $scopes                          App scopes
      * @param string               $hostName                        App host name e.g. www.google.ca. May include scheme
      * @param SessionStorage       $sessionStorage                  Session storage strategy
-     * @param string               $apiVersion                      App API key, defaults to unstable
+     * @param string               $apiVersion                      App API version
      * @param bool                 $isEmbeddedApp                   Whether the app is an embedded app, defaults to true
      * @param bool                 $isPrivateApp                    Whether the app is a private app, defaults to false
      * @param string|null          $privateAppStorefrontAccessToken The Storefront API Access Token for a private app
@@ -77,7 +77,7 @@ public static function initialize(
         $scopes,
         string $hostName,
         SessionStorage $sessionStorage,
-        string $apiVersion = ApiVersion::LATEST,
+        string $apiVersion,
         bool $isEmbeddedApp = true,
         bool $isPrivateApp = false,
         ?string $privateAppStorefrontAccessToken = null,
@@ -93,6 +93,7 @@ public static function initialize(
             'apiSecretKey' => $apiSecretKey,
             'scopes' => implode((array)$scopes),
             'hostName' => $hostName,
+            'apiVersion' => $apiVersion,
         ];
         $missing = array();
         foreach ($requiredValues as $key => $value) {
diff --git a/tests/BaseTestCase.php b/tests/BaseTestCase.php
@@ -32,6 +32,7 @@ public function setUp(): void
             scopes: ['sleepy', 'kitty'],
             hostName: 'www.my-friends-cats.com',
             sessionStorage: new MockSessionStorage(),
+            apiVersion: '2025-10',
         );
         Context::$RETRY_TIME_IN_SECONDS = 0;
         $this->version = require dirname(__FILE__) . '/../src/version.php';
diff --git a/tests/ContextTest.php b/tests/ContextTest.php
@@ -28,6 +28,7 @@ public function testCanCreateContext()
             scopes: ['sleepy', 'kitty'],
             hostName: 'my-friends-cats',
             sessionStorage: new MockSessionStorage(),
+            apiVersion: '2025-10',
         );
 
         $this->assertEquals('ash', Context::$API_KEY);
@@ -52,6 +53,7 @@ public function testCanUpdateContext()
             scopes: ['silly', 'doggo'],
             hostName: 'yay-for-doggos',
             sessionStorage: new MockSessionStorage(),
+            apiVersion: '2025-10',
         );
 
         $this->assertEquals('tuck', Context::$API_KEY);
@@ -64,14 +66,15 @@ public function testThrowsIfMissingArguments()
     {
         $this->expectException(MissingArgumentException::class);
         $this->expectExceptionMessage(
-            'Cannot initialize Shopify API Library. Missing values for: apiKey, apiSecretKey, scopes, hostName'
+            'Cannot initialize Shopify API Library. Missing values for: apiKey, apiSecretKey, scopes, hostName, apiVersion'
         );
         Context::initialize(
             apiKey: '',
             apiSecretKey: '',
             scopes: [],
             hostName: '',
             sessionStorage: new MockSessionStorage(),
+            apiVersion: '',
         );
     }
 
@@ -96,7 +99,7 @@ public function testThrowsIfPrivateApp()
             scopes: ['sleepy', 'kitty'],
             hostName: 'my-friends-cats',
             sessionStorage: new MockSessionStorage(),
-            apiVersion: 'unstable',
+            apiVersion: '2025-10',
             isPrivateApp: true,
         );
         $this->expectException(PrivateAppException::class);
@@ -223,6 +226,7 @@ public function testCanSetHostScheme($host, $expectedScheme, $expectedHost)
             scopes: ['sleepy', 'kitty'],
             hostName: $host,
             sessionStorage: new MockSessionStorage(),
+            apiVersion: '2025-10',
         );
 
         $this->assertEquals($expectedHost, Context::$HOST_NAME);
@@ -249,6 +253,7 @@ public function testFailsOnInvalidHost()
             scopes: ['sleepy', 'kitty'],
             hostName: 'not-a-host-!@#$%^&*()',
             sessionStorage: new MockSessionStorage(),
+            apiVersion: '2025-10',
         );
     }
 
@@ -262,7 +267,7 @@ public function testCanSetCustomShopDomains()
             scopes: ['sleepy', 'kitty'],
             hostName: 'my-friends-cats',
             sessionStorage: new MockSessionStorage(),
-            apiVersion: ApiVersion::LATEST,
+            apiVersion: '2025-07',
             isPrivateApp: false,
             customShopDomains: $domains,
         );

Original file line number	Diff line number	Diff line change
`@@ -66,8 +66,4 @@ class ApiVersion`
`66`	`66`	`* @var string`
`67`	`67`	`*/`
`68`	`68`	`public const JULY_2025 = "2025-07";`
`69`		`- /**`
`70`		`- * @var string`
`71`		`- */`
`72`		`- public const LATEST = self::JULY_2025;`
`73`	`69`	`}`