release: 0.1.0

.github/workflows/release-doctor.yml

@@ -0,0 +1,22 @@
+name: Release Doctor
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  release_doctor:
+    name: release doctor
+    runs-on: ubuntu-latest
+    if: github.repository == 'ScrapeGraphAI/scrapegraphai-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
+
+      - name: Check release environment
+        run: |
+          bash ./bin/check-release-environment
+        env:
+          PACKAGIST_USERNAME: ${{ secrets.SCRAPEGRAPHAI_PACKAGIST_USERNAME || secrets.PACKAGIST_USERNAME }}
+          PACKAGIST_SAFE_KEY: ${{ secrets.SCRAPEGRAPHAI_PACKAGIST_SAFE_KEY || secrets.PACKAGIST_SAFE_KEY }}

.gitignore

@@ -1,11 +1,11 @@
-*.swo
-*.swp
+composer.lock
+docs/
 .idea/
 .php-cs-fixer.cache
 .php-cs-fixer.php
-.phpdoc/
 .phpunit.cache
-composer.lock
 phpunit.xml
 playground/
+*.swo
+*.swp
 vendor/

.php-cs-fixer.dist.php

@@ -7,5 +7,11 @@
 return (new Config())
     ->setParallelConfig(ParallelConfigFactory::detect())
     ->setFinder(Finder::create()->in([__DIR__.'/src', __DIR__.'/tests']))
-    ->setRules(['@PhpCsFixer' => true, 'phpdoc_align' => false, 'new_with_parentheses' => ['named_class' => false]])
+    ->setRules([
+        '@PhpCsFixer' => true,
+        'phpdoc_align' => false,
+        'new_with_parentheses' => ['named_class' => false],
+        'ordered_types' => ['null_adjustment' => 'always_last', 'sort_algorithm' => 'none'],
+        'phpdoc_types_order' => ['null_adjustment' => 'always_last', 'sort_algorithm' => 'none'],
+    ])
 ;

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.0.1"
+  ".": "0.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 15
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/scrapegraphai%2Fscrapegraphai-969ebada41127057e4cda129b2e7206224743b5c7fd33aa8ae062ff71b775ac9.yml
-openapi_spec_hash: 2b2c2c684e6f6885398efca5f2b1f854
-config_hash: 30d69c79e34a1ea6a0405573ce30d927
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/scrapegraphai%2Fscrapegraphai-633fdeab6abaefbe666099e8f86ce6b2acc9dacff1c33a80813bb04e8e437229.yml
+openapi_spec_hash: f41ec90694ca8e7233bd20cc7ff1afbf
+config_hash: 6889576ba0fdc14f2c71cea09a60a0f6

CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.1.0 (2025-10-09)
+
+Full Changelog: [v0.0.1...v0.1.0](https://github.com/ScrapeGraphAI/scrapegraphai-php/compare/v0.0.1...v0.1.0)
+
+### ⚠ BREAKING CHANGES
+
+* expose services and service contracts
+* use builders for RequestOptions
+* rename errors to exceptions
+* pagination field rename, and basic streaming docs
+* **refactor:** namespacing cleanup
+* **refactor:** clean up pagination, errors, as well as request methods
+
+### Features
+
+* add files ([adb926e](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/adb926eb9cfb18594355fa39f642a41a76af19a8))
+* add files ([f728b05](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/f728b05e4bcd0b29355c77cf529d2f18b5cbce11))
+* **client:** add raw methods ([2c62976](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/2c62976824aa8bc2b4119990a4253bd5918852a3))
+* **client:** add streaming ([d191c29](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/d191c29f3e1889640e16911918041bd3850fd4e8))
+* **client:** improve error handling ([b3eab16](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/b3eab16fb85eafac7eba187d23d9fc9a5678fd15))
+* **client:** support raw responses ([7ea4904](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/7ea49045827081bda452412b5ef967924b61cd76))
+* **client:** use named parameters in methods ([2a938ad](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/2a938ad3e8e2658d53813570165fca69ebca554d))
+* **client:** use real enums ([196fd29](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/196fd2985d799749f11af3ef4df7e29f30a4455f))
+* **client:** use with for constructors ([d00f77a](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/d00f77a024ea0faa3f08b2fcdcac387b5c248c1a))
+* ensure `->toArray()` benefits from structural typing ([205ab97](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/205ab97f9f2bc8ca38e9847850163701827777dc))
+* expose services and service contracts ([fcb58d5](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/fcb58d5574acc36d7c2e0e41c2b973c7b6ff1613))
+* pagination field rename, and basic streaming docs ([d79ffc9](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/d79ffc9ea439c191f0ffed61f2752e7bfe47b00c))
+* **php:** differentiate null and omit ([f19a57a](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/f19a57af690dba72f269a940930da3efd35d4b2c))
+* **php:** rename internal types ([c55bbd7](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/c55bbd74aa39be1cf5ab1997fa140d4e92f96de3))
+* **refactor:** clean up pagination, errors, as well as request methods ([7135820](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/713582082c5123e8152bbdb5896926ae58496095))
+* **refactor:** namespacing cleanup ([8c75ed0](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/8c75ed0c279a15e9051ac891e69a5fa2c9e7be30))
+* rename errors to exceptions ([b568600](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/b568600fb25d39cbd315e98dc8654360383523fe))
+* use builders for RequestOptions ([c2300dc](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/c2300dcdc4d9370eb060b04ee25601572821f59c))
+
+
+### Bug Fixes
+
+* add create release workflow ([7361bd6](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/7361bd6438c71f72ca9e11290c008beeb04e390a))
+* basic pagination should work ([ecebf37](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/ecebf37bdf9a4b6ede506820789805c8d4ae4f9e))
+* **ci:** release doctor workflow ([1eb0061](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/1eb0061420ae6088f5d3323fd46a80a9c12d2783))
+* **client:** elide null named parameters ([7297553](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/7297553957c8444178ca2dce6c0c89fd743a0a1e))
+* minor bugs ([d905655](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/d90565586eb26ccf73f67961856133e9c0bc90fd))
+* remove inaccurate `license` field in composer.json ([1cfba5f](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/1cfba5fa543a792ecf6651259309247fa3ce726b))
+* streaming internals ([2516566](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/25165664e3d3c7fd4f11f72589f89baa1305eb56))
+
+
+### Chores
+
+* add additional php doc tags ([3a18c70](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/3a18c70daa9fa2d26264429cddd2b092bfcd5473))
+* cleanup streaming ([372bf28](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/372bf283cdd910023fd38ecbfb16570870450afd))
+* configure new SDK language ([57c78ba](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/57c78ba863893bb956cfc44b9a34037a52d7d4cf))
+* **docs:** update readme formatting ([ecf153b](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/ecf153b12a488ad416d25e3b494e523ffd08f2c8))
+* document parameter object usage ([707cff0](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/707cff08ced7c6f1da574965a81e4b30a531b391))
+* fix lints in UnionOf ([5e8ce6f](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/5e8ce6f7137f9ce2a2bf3fce709cd363f4b8c196))
+* improve model annotations ([585d282](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/585d282dfdc9c34081e6cb44c0c83256037be12f))
+* **internal:** refactor base client internals ([ec19244](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/ec1924477e3428e9bc066a7ef7473084f06a768c))
+* **internal:** refactored internal codepaths ([d3577db](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/d3577db6255af45ab790915545f4b8044e90c921))
+* intuitively order union types ([0cd048d](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/0cd048d4ce590110cdf01edc1649d4ef2e707a6d))
+* make more targeted phpstan ignores ([c33963e](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/c33963e7a8f9f8fbd461ca989e027974da1e8476))
+* readme improvements ([c38da93](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/c38da939ecdc0ee7a092a58faf41e63a92b61b11))
+* refactor methods ([ddd88d8](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/ddd88d881ca5924d6d2f25e6ae4e4656e7ff5722))
+* refactor request options ([3898066](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/389806624293626a1246486efa870095a959eca5))
+* **refactor:** simplify base page interface ([77b2f76](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/77b2f7692824f3d6d7ff151704174cfe550b1339))
+* remove `php-http/multipart-stream-builder` as a required dependency ([03a02b4](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/03a02b472282af3977cab5be1296edee8a8750ce))
+* remove type aliases ([586c954](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/586c9548945e0522a71f888803bc3c9e7804ccba))
+* simplify model initialization ([4a166fc](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/4a166fcc6584323b68d900e6809453a8d0eb1bcd))
+* update SDK settings ([f566b27](https://github.com/ScrapeGraphAI/scrapegraphai-php/commit/f566b27a274db61218c98bc775642fec51799888))

README.md

@@ -5,7 +5,7 @@
 >
 > 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/stainless-sdks/scrapegraphai-php/issues/new).
+> **We'd love your feedback!** Please share any suggestions, bug reports, feature requests, or general thoughts by [filing an issue](https://www.github.com/ScrapeGraphAI/scrapegraphai-php/issues/new).
 
 The Scrapegraphai PHP library provides convenient access to the Scrapegraphai REST API from any PHP 8.1.0+ application.
 
@@ -19,12 +19,14 @@ The REST API documentation can be found on [scrapegraphai.com](https://scrapegra
 
 To use this package, install via Composer by adding the following to your application's `composer.json`:
 
+<!-- x-release-please-start-version -->
+
 ```json
 {
   "repositories": [
     {
       "type": "vcs",
-      "url": "git@github.com:stainless-sdks/scrapegraphai-php.git"
+      "url": "git@github.com:ScrapeGraphAI/scrapegraphai-php.git"
     }
   ],
   "require": {
@@ -33,94 +35,99 @@ To use this package, install via Composer by adding the following to your applic
 }
 ```
 
+<!-- x-release-please-end -->
+
 ## Usage
 
+This library uses named parameters to specify optional arguments.
+Parameters with a default value must be set by name.
+
 ```php
 <?php
 
 use Scrapegraphai\Client;
-use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
 
 $client = new Client(
   apiKey: getenv("SCRAPEGRAPHAI_API_KEY") ?: "My API Key",
   environment: "environment_1",
 );
 
-$params = SmartscraperCreateParams::from(
+$completedSmartscraper = $client->smartscraper->create(
   userPrompt: "Extract the product name, price, and description"
 );
-$completedSmartscraper = $client->smartscraper->create($params);
 
 var_dump($completedSmartscraper->request_id);
 ```
 
+### Value Objects
+
+It is recommended to use the static `with` constructor `Dog::with(name: "Joey")`
+and named parameters to initialize value objects.
+
+However, builders are also provided `(new Dog)->withName("Joey")`.
+
 ### Handling errors
 
-When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Scrapegraphai\Errors\APIError` will be thrown:
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Scrapegraphai\Core\Exceptions\APIException` will be thrown:
 
 ```php
 <?php
 
-use Scrapegraphai\Errors\APIConnectionError;
-use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
+use Scrapegraphai\Core\Exceptions\APIConnectionException;
 
 try {
-    $params = SmartscraperCreateParams::from(
-      userPrompt: "Extract the product name, price, and description"
-    );
-    $Smartscraper = $client->smartscraper->create($params);
-} catch (APIConnectionError $e) {
-    echo "The server could not be reached", PHP_EOL;
-    var_dump($e->getPrevious());
+  $completedSmartscraper = $client->smartscraper->create(
+    userPrompt: "Extract the product name, price, and description"
+  );
+} catch (APIConnectionException $e) {
+  echo "The server could not be reached", PHP_EOL;
+  var_dump($e->getPrevious());
 } catch (RateLimitError $_) {
-    echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
+  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
 } catch (APIStatusError $e) {
-    echo "Another non-200-range status code was received", PHP_EOL;
-    var_dump($e->status);
+  echo "Another non-200-range status code was received", PHP_EOL;
+  echo $e->getMessage();
 }
 ```
 
 Error codes are as follows:
 
-| Cause            | Error Type                 |
-| ---------------- | -------------------------- |
-| HTTP 400         | `BadRequestError`          |
-| HTTP 401         | `AuthenticationError`      |
-| HTTP 403         | `PermissionDeniedError`    |
-| HTTP 404         | `NotFoundError`            |
-| HTTP 409         | `ConflictError`            |
-| HTTP 422         | `UnprocessableEntityError` |
-| HTTP 429         | `RateLimitError`           |
-| HTTP >= 500      | `InternalServerError`      |
-| Other HTTP error | `APIStatusError`           |
-| Timeout          | `APITimeoutError`          |
-| Network error    | `APIConnectionError`       |
+| Cause            | Error Type                     |
+| ---------------- | ------------------------------ |
+| HTTP 400         | `BadRequestException`          |
+| HTTP 401         | `AuthenticationException`      |
+| HTTP 403         | `PermissionDeniedException`    |
+| HTTP 404         | `NotFoundException`            |
+| HTTP 409         | `ConflictException`            |
+| HTTP 422         | `UnprocessableEntityException` |
+| HTTP 429         | `RateLimitException`           |
+| HTTP >= 500      | `InternalServerException`      |
+| Other HTTP error | `APIStatusException`           |
+| Timeout          | `APITimeoutException`          |
+| Network error    | `APIConnectionException`       |
 
 ### Retries
 
 Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
 Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
-You can use the `max_retries` option to configure or disable this:
+You can use the `maxRetries` option to configure or disable this:
 
 ```php
 <?php
 
 use Scrapegraphai\Client;
 use Scrapegraphai\RequestOptions;
-use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
 
 // Configure the default for all requests:
 $client = new Client(maxRetries: 0);
-$params = SmartscraperCreateParams::from(
-  userPrompt: "Extract the product name, price, and description"
-);
 
 // Or, configure per-request:
-$result = $client
-  ->smartscraper
-  ->create($params, new RequestOptions(maxRetries: 5));
+$result = $client->smartscraper->create(
+  userPrompt: "Extract the product name, price, and description",
+  requestOptions: RequestOptions::with(maxRetries: 5),
+);
 ```
 
 ## Advanced concepts
@@ -131,22 +138,16 @@ $result = $client
 
 You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
 
-Note: the `extra_` parameters of the same name overrides the documented parameters.
+Note: the `extra*` parameters of the same name overrides the documented parameters.
 
 ```php
 <?php
 
 use Scrapegraphai\RequestOptions;
-use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
 
-$params = SmartscraperCreateParams::from(
-  userPrompt: "Extract the product name, price, and description"
-);
-$completedSmartscraper = $client
-  ->smartscraper
-  ->create(
-  $params,
-  new RequestOptions(
+$completedSmartscraper = $client->smartscraper->create(
+  userPrompt: "Extract the product name, price, and description",
+  requestOptions: RequestOptions::with(
     extraQueryParams: ["my_query_parameter" => "value"],
     extraBodyParams: ["my_body_parameter" => "value"],
     extraHeaders: ["my-header" => "value"],
@@ -236,4 +237,4 @@ PHP 8.1.0 or higher.
 
 ## Contributing
 
-See [the contributing documentation](https://github.com/stainless-sdks/scrapegraphai-php/tree/main/CONTRIBUTING.md).
+See [the contributing documentation](https://github.com/ScrapeGraphAI/scrapegraphai-php/tree/main/CONTRIBUTING.md).

bin/check-release-environment

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+errors=()
+
+if [ -z "${PACKAGIST_USERNAME}" ]; then
+  errors+=("The PACKAGIST_USERNAME secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+fi
+
+if [ -z "${PACKAGIST_SAFE_KEY}" ]; then
+  errors+=("The PACKAGIST_SAFE_KEY secret has not been set. Please set it in either this repository's secrets or your organization secrets")
+fi
+
+lenErrors=${#errors[@]}
+
+if [[ lenErrors -gt 0 ]]; then
+  echo -e "Found the following errors in the release environment:\n"
+
+  for error in "${errors[@]}"; do
+    echo -e "- $error\n"
+  done
+
+  exit 1
+fi
+
+echo "The environment is ready to push releases!"

composer.json

@@ -1,9 +1,7 @@
 {
   "$schema": "https://getcomposer.org/schema.json",
   "autoload": {
-    "files": [
-      "src/Client.php"
-    ],
+    "files": ["src/Core.php", "src/Client.php"],
     "psr-4": {
       "Scrapegraphai\\": "src/"
     }
@@ -25,13 +23,11 @@
     "preferred-install": "dist",
     "sort-packages": true
   },
-  "license": "APACHE-2.0",
   "description": "Scrapegraphai PHP SDK",
   "name": "org-placeholder/scrapegraphai",
   "require": {
     "php": "^8.1",
     "php-http/discovery": "^1",
-    "php-http/multipart-stream-builder": "^1",
     "psr/http-client": "^1",
     "psr/http-client-implementation": "^1",
     "psr/http-factory-implementation": "^1",
@@ -48,6 +44,7 @@
     "symfony/http-client": "^7"
   },
   "scripts": {
+    "build:docs": "curl --etag-save ./vendor/ag.etags --etag-compare ./vendor/ag.etags --create-dirs --remote-name --output-dir ./vendor/bin --no-progress-meter -- https://github.com/ApiGen/ApiGen/releases/latest/download/apigen.phar && php ./vendor/bin/apigen.phar --output docs -- src",
     "lint": "./scripts/lint",
     "test": "./scripts/test"
   }

scripts/lint

@@ -5,4 +5,4 @@ set -e
 cd -- "$(dirname -- "$0")/.."
 
 echo "==> Running PHPStan"
-exec -- ./vendor/bin/phpstan analyse --memory-limit=1G
+exec -- ./vendor/bin/phpstan analyse --memory-limit=2G