Skip to content

Commit c7fee02

Browse files
lizkenyonlizkenyon
authored
Merge branch 'main' into dependabot/github_actions/shivammathur/setup-php-2.35.5
2 parents 17f971e + f4089aa commit c7fee02

153 files changed

Lines changed: 30181 additions & 7 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎BREAKING_CHANGES_FOR_V6.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Breaking change notice for version 6.0.0
2+
3+
## Removal of `ApiVersion::LATEST` constant
4+
5+
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.
6+
7+
### Migration Guide
8+
9+
**If you were using the constant directly:**
10+
11+
```php
12+
// Before (v5 and earlier)
13+
$apiVersion = ApiVersion::LATEST;
14+
15+
// After (v6+)
16+
$apiVersion = '2025-07'; // Explicitly specify the version you want to use
17+
```
18+
19+
**In your Context::initialize():**
20+
21+
The `apiVersion` parameter is now **required** in `Context::initialize()`. You must explicitly specify which API version you want to use:
22+
23+
```php
24+
// Before (v5 and earlier)
25+
Context::initialize(
26+
apiKey: $_ENV['SHOPIFY_API_KEY'],
27+
apiSecretKey: $_ENV['SHOPIFY_API_SECRET'],
28+
scopes: $_ENV['SHOPIFY_APP_SCOPES'],
29+
hostName: $_ENV['SHOPIFY_APP_HOST_NAME'],
30+
sessionStorage: new FileSessionStorage('/tmp/php_sessions'),
31+
// apiVersion was optional with default ApiVersion::LATEST
32+
);
33+
34+
// After (v6+)
35+
Context::initialize(
36+
apiKey: $_ENV['SHOPIFY_API_KEY'],
37+
apiSecretKey: $_ENV['SHOPIFY_API_SECRET'],
38+
scopes: $_ENV['SHOPIFY_APP_SCOPES'],
39+
hostName: $_ENV['SHOPIFY_APP_HOST_NAME'],
40+
sessionStorage: new FileSessionStorage('/tmp/php_sessions'),
41+
apiVersion: '2025-07', // Now required - explicitly specify the version
42+
);
43+
```
44+
45+
**Finding the right API version:**
46+
47+
You can reference the available API versions in the `ApiVersion` class:
48+
49+
```php
50+
use Shopify\ApiVersion;
51+
52+
// Available constants (as of this release):
53+
ApiVersion::UNSTABLE // "unstable"
54+
ApiVersion::JULY_2025 // "2025-07"
55+
ApiVersion::APRIL_2025 // "2025-04"
56+
ApiVersion::JANUARY_2025 // "2025-01"
57+
ApiVersion::OCTOBER_2024 // "2024-10"
58+
// ... and older versions
59+
```
60+
61+
Or you can use string literals directly:
62+
63+
```php
64+
Context::initialize(
65+
// ... other parameters
66+
apiVersion: '2025-07',
67+
);
68+
```
69+
70+
**Why this change?**
71+
72+
By requiring explicit version specification, apps can:
73+
- Control when they upgrade to new API versions
74+
- Test thoroughly before upgrading
75+
- Avoid unexpected breaking changes from automatic version updates
76+
- Follow semantic versioning principles more accurately
77+
78+
**Recommended approach:**
79+
80+
1. Review the [Shopify API Changelog](https://shopify.dev/changelog) to understand changes between versions
81+
2. Choose the API version that best suits your app's needs
82+
3. Explicitly specify that version in your `Context::initialize()` call
83+
4. Test your app thoroughly with the chosen version
84+
5. Upgrade to newer versions on your own schedule after proper testing

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
66
and adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
77

88
## Unreleased
9+
- ⚠️ [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.
10+
- [#425](https://github.com/Shopify/shopify-api-php/pull/425) [Patch] Add compliance webhook topics
11+
- [#433](https://github.com/Shopify/shopify-api-php/pull/433) [Minor] Add support for 2025-10 API version
912

1013
## v5.11.0 - 2025-07-10
1114
- [#418](https://github.com/Shopify/shopify-api-php/pull/416) [Minor] Add support for 2025-07 API version

‎REST_RESOURCE.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Adding a New API Version to Shopify API PHP
2+
3+
## Overview
4+
This guide provides step-by-step instructions for adding a new API version to the Shopify API PHP library. This example uses the addition of the 2025-07 API version as a reference, but the process applies to any new API version.
5+
6+
## Prerequisites
7+
- Understanding of any breaking changes or removed resources in the new API version
8+
9+
## Step 1: Update API Version Constants
10+
11+
### Add New Version Constant
12+
Edit `src/ApiVersion.php` to add your new version:
13+
14+
```php
15+
// Add the new constant following the naming pattern
16+
public const JULY_2025 = "2025-07"; // Replace with your version
17+
18+
// If this is the latest version, update the LATEST constant
19+
public const LATEST = self::JULY_2025; // Update from previous latest
20+
```
21+
22+
**Naming Convention:**
23+
- Format: `{MONTH}_{YEAR}`
24+
- Examples: `APRIL_2025`, `JULY_2025`, `OCTOBER_2025`
25+
26+
## Step 2: Create Directory Structure
27+
28+
### Create Source Directory
29+
```bash
30+
mkdir src/Rest/Admin{YYYY_MM}/
31+
```
32+
Example: `src/Rest/Admin2025_07/`
33+
34+
### Create Test Directory
35+
```bash
36+
mkdir tests/Rest/Admin{YYYY_MM}/
37+
```
38+
Example: `tests/Rest/Admin2025_07/`
39+
40+
## Step 3: Copy and Update Resource Files
41+
42+
### Copy Previous Version's Files
43+
Copy all files from the most recent API version directory:
44+
45+
```bash
46+
# Copy source files
47+
cp -r src/Rest/Admin{PREVIOUS_VERSION}/* src/Rest/Admin{NEW_VERSION}/
48+
49+
# Copy test files
50+
cp -r tests/Rest/Admin{PREVIOUS_VERSION}/* tests/Rest/Admin{NEW_VERSION}/
51+
```
52+
53+
### Update Each Resource File
54+
For each PHP file in the new directory, update:
55+
56+
1. **Namespace**
57+
```php
58+
// From
59+
namespace Shopify\Rest\Admin{PREVIOUS_VERSION};
60+
61+
// To
62+
namespace Shopify\Rest\Admin{NEW_VERSION};
63+
```
64+
65+
2. **API Version String**
66+
```php
67+
// From
68+
public static string $API_VERSION = "{PREVIOUS_VERSION}";
69+
70+
// To
71+
public static string $API_VERSION = "{NEW_VERSION}";
72+
```
73+
74+
### Example Resource File Update
75+
76+
**Before (Admin2025_04/Article.php)**:
77+
```php
78+
namespace Shopify\Rest\Admin2025_04;
79+
80+
use Shopify\Auth\Session;
81+
use Shopify\Rest\Base;
82+
83+
class Article extends Base
84+
{
85+
public static string $API_VERSION = "2025-04";
86+
// ... rest of the file is identical
87+
}
88+
```
89+
90+
**After (Admin2025_07/Article.php)**:
91+
```php
92+
namespace Shopify\Rest\Admin2025_07;
93+
94+
use Shopify\Auth\Session;
95+
use Shopify\Rest\Base;
96+
97+
class Article extends Base
98+
{
99+
public static string $API_VERSION = "2025-07";
100+
// ... rest of the file is identical
101+
}
102+
```
103+
104+
## Step 4: Update Test Files
105+
106+
### Rename Test Files
107+
Update the naming convention for test files:
108+
```
109+
{ResourceName}{YYYYMM}Test.php
110+
```
111+
Example: `Article202504Test.php` → `Article202507Test.php`
112+
113+
### Update Test File Contents
114+
For each test file, update:
115+
116+
1. **Use Statement**
117+
```php
118+
// From
119+
use Shopify\Rest\Admin{PREVIOUS_VERSION}\Article;
120+
121+
// To
122+
use Shopify\Rest\Admin{NEW_VERSION}\Article;
123+
```
124+
125+
2. **Context API Version**
126+
```php
127+
// From
128+
Context::$API_VERSION = "{PREVIOUS_VERSION}";
129+
130+
// To
131+
Context::$API_VERSION = "{NEW_VERSION}";
132+
```
133+
134+
3. **URL Paths in Mock Requests**
135+
```php
136+
// From
137+
"https://test-shop.myshopify.io/admin/api/{PREVIOUS_VERSION}/..."
138+
139+
// To
140+
"https://test-shop.myshopify.io/admin/api/{NEW_VERSION}/..."
141+
```
142+
143+
## Step 5: Handle Breaking Changes
144+
145+
### Identify Removed or Modified Resources
146+
Check the Shopify API changelog for:
147+
- Removed resources (e.g., CustomerAddress in 2025-07)
148+
- Modified endpoints
149+
- Changed field names or types
150+
151+
### Remove Deprecated Resources
152+
If a resource is removed in the new API version:
153+
1. Delete the resource file from `src/Rest/Admin{NEW_VERSION}/`
154+
2. Delete the corresponding test file from `tests/Rest/Admin{NEW_VERSION}/`
155+
156+
### Update Modified Resources
157+
If a resource has changed:
158+
1. Update the resource class properties
159+
2. Modify the `$PATHS` array if endpoints changed
160+
3. Update method signatures if parameters changed
161+
4. Adjust test cases accordingly
162+
163+
164+
## Checklist
165+
166+
- [ ] Added new version constant to `src/ApiVersion.php`
167+
- [ ] Updated `LATEST` constant if applicable
168+
- [ ] Created `src/Rest/Admin{NEW_VERSION}/` directory
169+
- [ ] Created `tests/Rest/Admin{NEW_VERSION}/` directory
170+
- [ ] Copied all resource files from previous version
171+
- [ ] Updated namespaces in all resource files
172+
- [ ] Updated API_VERSION in all resource files
173+
- [ ] Renamed all test files with new version suffix
174+
- [ ] Updated test file imports and contexts
175+
- [ ] Updated all API URLs in test mocks
176+
- [ ] Removed deprecated resources
177+
- [ ] Updated modified resources
178+
- [ ] Run all tests successfully

‎docs/getting_started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ The first thing your app will need to do to use this library is to set up your c
1919
| `scopes` | `string \| array` | Yes | - | App scopes |
2020
| `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 |
2121
| `sessionStorage` | `SessionStorage` | Yes | - | Session storage strategy. Read our [notes on session handling](issues.md#notes-on-session-handling) for more information |
22-
| `apiVersion` | `string` | No | `ApiVersion::LATEST` | App API version, defaults to `ApiVersion::LATEST` |
22+
| `apiVersion` | `string` | Yes | - | App API version. You must explicitly specify which API version to use (e.g., `'2025-07'`, `'2024-10'`, etc.) |
2323
| `isEmbeddedApp` | `bool` | No | `true` | Whether the app is an embedded app |
2424
| `isPrivateApp` | `bool` | No | `false` | Whether the app is a private app |
2525
| `userAgentPrefix` | `string` | No | - | Prefix for user agent header sent with a request |

‎src/ApiVersion.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,5 +69,5 @@ class ApiVersion
6969
/**
7070
* @var string
7171
*/
72-
public const LATEST = self::JULY_2025;
72+
public const OCTOBER_2025 = "2025-10";
7373
}

‎src/Context.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ class Context
6060
* @param string|array $scopes App scopes
6161
* @param string $hostName App host name e.g. www.google.ca. May include scheme
6262
* @param SessionStorage $sessionStorage Session storage strategy
63-
* @param string $apiVersion App API key, defaults to unstable
63+
* @param string $apiVersion App API version
6464
* @param bool $isEmbeddedApp Whether the app is an embedded app, defaults to true
6565
* @param bool $isPrivateApp Whether the app is a private app, defaults to false
6666
* @param string|null $privateAppStorefrontAccessToken The Storefront API Access Token for a private app
@@ -77,7 +77,7 @@ public static function initialize(
7777
$scopes,
7878
string $hostName,
7979
SessionStorage $sessionStorage,
80-
string $apiVersion = ApiVersion::LATEST,
80+
string $apiVersion,
8181
bool $isEmbeddedApp = true,
8282
bool $isPrivateApp = false,
8383
?string $privateAppStorefrontAccessToken = null,
@@ -93,6 +93,7 @@ public static function initialize(
9393
'apiSecretKey' => $apiSecretKey,
9494
'scopes' => implode((array)$scopes),
9595
'hostName' => $hostName,
96+
'apiVersion' => $apiVersion,
9697
];
9798
$missing = array();
9899
foreach ($requiredValues as $key => $value) {

0 commit comments

Comments
 (0)