release: 0.4.0

.gitattributes

@@ -0,0 +1,16 @@
+*.php diff=php
+
+/.github                       export-ignore
+/bin                           export-ignore
+/scripts                       export-ignore
+/tests                         export-ignore
+
+/.gitattributes                export-ignore
+/.gitignore                    export-ignore
+/.php-cs-fixer.dist.php        export-ignore
+/.phpactor.json                export-ignore
+/.release-please-manifest.json export-ignore
+/.stats.yml                    export-ignore
+/phpstan.dist.neon             export-ignore
+/phpunit.xml.dist              export-ignore
+/release-please-config.json    export-ignore

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up PHP
         uses: 'shivammathur/setup-php@v2'
@@ -38,7 +38,7 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/moderation-api-php' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up PHP
         uses: 'shivammathur/setup-php@v2'

.github/workflows/publish-packagist.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Publish to Packagist
         run: |-

.github/workflows/release-doctor.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'moderation-api/sdk-php' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Check release environment
         run: |

.gitignore

@@ -1,4 +1,3 @@
-composer.lock
 docs/
 .idea/
 .php-cs-fixer.cache
@@ -9,3 +8,6 @@ playground/
 *.swo
 *.swp
 vendor/
+
+# do not edit! excludes generated files used internally
+.artifacts/

.php-cs-fixer.dist.php

@@ -4,7 +4,7 @@
 use PhpCsFixer\Finder;
 use PhpCsFixer\Runner\Parallel\ParallelConfigFactory;
 
-return (new Config())
+return (new Config)
     ->setParallelConfig(ParallelConfigFactory::detect())
     ->setFinder(Finder::create()->in([__DIR__.'/src', __DIR__.'/tests']))
     ->setRules([

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.0"
+  ".": "0.4.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 27
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/moderation-api%2Fmoderation-api-3eaa6a0657e9f67ea196c65d3b604c71f5406108983981ec696642563fda0a93.yml
-openapi_spec_hash: c417a44bb9fa62a02eca68bbb307c712
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/moderation-api%2Fmoderation-api-d63cb4b89d39d82fa1d4600501ad5cedfddfbcf7a8806cac61634873b5211a9f.yml
+openapi_spec_hash: 5a8d51e52ea8e52681c77eed584fb21c
 config_hash: 6a52f6ae7d55cf3b4e91538cc7752aeb

CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.4.0 (2026-01-31)
+
+Full Changelog: [v0.3.0...v0.4.0](https://github.com/moderation-api/sdk-php/compare/v0.3.0...v0.4.0)
+
+### ⚠ BREAKING CHANGES
+
+* replace special flag type `omittable` with just `null`
+* use aliases for phpstan types
+* improve identifier renaming for names that clash with builtins
+
+### Features
+
+* add idempotency header support ([4b941bd](https://github.com/moderation-api/sdk-php/commit/4b941bd0c16b8fe812da9ad660d49a4cb24e936d))
+* **api:** api update ([4e4f842](https://github.com/moderation-api/sdk-php/commit/4e4f8424fce03d262c50b50b060b8103c41f4d0e))
+* **api:** api update ([859828f](https://github.com/moderation-api/sdk-php/commit/859828f8d807016ae945da409a699e399236640c))
+* **api:** api update ([c7142a7](https://github.com/moderation-api/sdk-php/commit/c7142a7b0a048a20c420d935420f9108b7546088))
+* improve identifier renaming for names that clash with builtins ([8028859](https://github.com/moderation-api/sdk-php/commit/8028859af7460243fc4c23f2e2541ff65ba542d6))
+* improved phpstan type annotations ([1e1c3c6](https://github.com/moderation-api/sdk-php/commit/1e1c3c6816b004ce6126a7d757a2c8c4cbf4c40f))
+* replace special flag type `omittable` with just `null` ([5294f9f](https://github.com/moderation-api/sdk-php/commit/5294f9fe1ceeb4443c20c709a6a6e1e7e269d53b))
+* simplify and make the phpstan types more consistent ([0735967](https://github.com/moderation-api/sdk-php/commit/07359676f9a4e714a1ea6e06cbd39a03563f7980))
+* support unwrapping envelopes ([50fbe5d](https://github.com/moderation-api/sdk-php/commit/50fbe5dfebbe02573f73df5c190512a0e566784d))
+* use aliases for phpstan types ([e17e879](https://github.com/moderation-api/sdk-php/commit/e17e879f4fd01c07356de5ed18f2021ad9e5e426))
+
+
+### Bug Fixes
+
+* a number of serialization errors ([4a43323](https://github.com/moderation-api/sdk-php/commit/4a4332385de4fd74a5b6d6499fc915d6ad3b5ade))
+* correctly serialize dates ([8b350ba](https://github.com/moderation-api/sdk-php/commit/8b350ba2b06ecf19174392a8b9b8bcc0b1a500c0))
+* support arrays in query param construction ([032b424](https://github.com/moderation-api/sdk-php/commit/032b424bd40e42f0ec67191d1c5a067d1dd84e2b))
+* typos in README.md ([edeefaf](https://github.com/moderation-api/sdk-php/commit/edeefaf7b79b4104fd9e8eacf93095720b840533))
+
+
+### Chores
+
+* add git attributes and composer lock file ([0ec3ea1](https://github.com/moderation-api/sdk-php/commit/0ec3ea12cfcb0f72172bb144d3adae63a6dd2082))
+* **internal:** add a basic client test ([36b8433](https://github.com/moderation-api/sdk-php/commit/36b8433b78f6f885049c83049a60add2368bb04d))
+* **internal:** codegen related update ([d600edc](https://github.com/moderation-api/sdk-php/commit/d600edc6cb485d3eb97c56682e75a5c800a0c717))
+* **internal:** codegen related update ([597bdf7](https://github.com/moderation-api/sdk-php/commit/597bdf718c72f298fd94157b21e9f64c17a2449d))
+* **internal:** codegen related update ([c26566d](https://github.com/moderation-api/sdk-php/commit/c26566d911dda034a275bef8a4ef280ee6a49255))
+* **internal:** codegen related update ([b2aba3e](https://github.com/moderation-api/sdk-php/commit/b2aba3e999c1375da44e8a8b9a6f0fdb7a649950))
+* **internal:** codegen related update ([5e43726](https://github.com/moderation-api/sdk-php/commit/5e4372642129cea14086a71f584d75ee3b52b5f8))
+* **internal:** codegen related update ([9b7c72f](https://github.com/moderation-api/sdk-php/commit/9b7c72f4df8838a5c2e5a597e95fccc625e828f5))
+* **internal:** codegen related update ([7cbad4c](https://github.com/moderation-api/sdk-php/commit/7cbad4c86abc4a9ac9dde0f97d4e9adc9f127c5e))
+* **internal:** codegen related update ([e6f45f4](https://github.com/moderation-api/sdk-php/commit/e6f45f4733e0da4e79072d7d76644e2bb8fc1f78))
+* **internal:** codegen related update ([b7631a0](https://github.com/moderation-api/sdk-php/commit/b7631a0f4a9fa10af3f6eda50be50fb78e66e222))
+* **internal:** codegen related update ([6171347](https://github.com/moderation-api/sdk-php/commit/6171347fc5833d947bf081bcac878e965555bf91))
+* **internal:** minor test script reformatting ([50ba7b7](https://github.com/moderation-api/sdk-php/commit/50ba7b776f4ef78948611ea7ecefcde18195dd73))
+* **internal:** refactor auth by moving concern from base client into client ([37eeb69](https://github.com/moderation-api/sdk-php/commit/37eeb691d9f06d91fa71e39e70ef335472621ee0))
+* **internal:** update `actions/checkout` version ([f3c6d09](https://github.com/moderation-api/sdk-php/commit/f3c6d09511b60b4d3b9fc5a01399a2eaaad3d76e))
+* **readme:** remove beta warning now that we're in ga ([dd62d54](https://github.com/moderation-api/sdk-php/commit/dd62d5463f2ff7c50e593a063f7db60fcaa6bcde))
+
 ## 0.3.0 (2025-12-10)
 
 Full Changelog: [v0.2.0...v0.3.0](https://github.com/moderation-api/sdk-php/compare/v0.2.0...v0.3.0)

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Moderation API
+   Copyright 2026 Moderation API
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,12 +1,5 @@
 # Moderation API PHP library
 
-> [!NOTE]
-> The Moderation API PHP API Library is currently in **beta** and we're excited for you to experiment with it!
->
-> This library has not yet been exhaustively tested in production environments and may be missing some features you'd expect in a stable release. As we continue development, there may be breaking changes that require updates to your code.
->
-> **We'd love your feedback!** Please share any suggestions, bug reports, feature requests, or general thoughts by [filing an issue](https://www.github.com/moderation-api/sdk-php/issues/new).
-
 The Moderation API PHP library provides convenient access to the Moderation API REST API from any PHP 8.1.0+ application.
 
 ## Documentation
@@ -18,7 +11,7 @@ The REST API documentation can be found on [docs.moderationapi.com](https://docs
 <!-- x-release-please-start-version -->
 
 ```
-composer require "moderation-api/sdk-php 0.3.0"
+composer require "moderation-api/sdk-php 0.4.0"
 ```
 
 <!-- x-release-please-end -->
@@ -57,6 +50,8 @@ When the library is unable to connect to the API, or if the API returns a non-su
 <?php
 
 use ModerationAPI\Core\Exceptions\APIConnectionException;
+use ModerationAPI\Core\Exceptions\RateLimitException;
+use ModerationAPI\Core\Exceptions\APIStatusException;
 
 try {
   $response = $client->content->submit(
@@ -65,9 +60,9 @@ try {
 } catch (APIConnectionException $e) {
   echo "The server could not be reached", PHP_EOL;
   var_dump($e->getPrevious());
-} catch (RateLimitError $e) {
+} catch (RateLimitException $e) {
   echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
-} catch (APIStatusError $e) {
+} catch (APIStatusException $e) {
   echo "Another non-200-range status code was received", PHP_EOL;
   echo $e->getMessage();
 }
@@ -101,15 +96,14 @@ You can use the `maxRetries` option to configure or disable this:
 <?php
 
 use ModerationAPI\Client;
-use ModerationAPI\RequestOptions;
 
 // Configure the default for all requests:
-$client = new Client(maxRetries: 0);
+$client = new Client(requestOptions: ['maxRetries' => 0]);
 
 // Or, configure per-request:
 $result = $client->content->submit(
   content: ['text' => 'x', 'type' => 'text'],
-  requestOptions: RequestOptions::with(maxRetries: 5),
+  requestOptions: ['maxRetries' => 5],
 );
 ```
 
@@ -126,15 +120,13 @@ Note: the `extra*` parameters of the same name overrides the documented paramete
 ```php
 <?php
 
-use ModerationAPI\RequestOptions;
-
 $response = $client->content->submit(
   content: ['text' => 'x', 'type' => 'text'],
-  requestOptions: RequestOptions::with(
-    extraQueryParams: ['my_query_parameter' => 'value'],
-    extraBodyParams: ['my_body_parameter' => 'value'],
-    extraHeaders: ['my-header' => 'value'],
-  ),
+  requestOptions: [
+    'extraQueryParams' => ['my_query_parameter' => 'value'],
+    'extraBodyParams' => ['my_body_parameter' => 'value'],
+    'extraHeaders' => ['my-header' => 'value'],
+  ],
 );
 ```
 

composer.json

@@ -3,8 +3,7 @@
   "license": "Apache-2.0",
   "autoload": {
     "files": [
-      "src/Core.php",
-      "src/Client.php"
+      "src/Version.php"
     ],
     "psr-4": {
       "ModerationAPI\\": "src/"
@@ -41,6 +40,7 @@
     "friendsofphp/php-cs-fixer": "^3",
     "nyholm/psr7": "^1",
     "pestphp/pest": "^3",
+    "php-http/mock-client": "^1",
     "phpstan/extension-installer": "^1",
     "phpstan/phpstan": "^2",
     "phpstan/phpstan-phpunit": "^2",