Skip to content

Commit 2a938ad

Browse files
stainless-app[bot]stainless-app[bot]
committed
feat(client): use named parameters in methods
1 parent d191c29 commit 2a938ad

19 files changed

+222
-188
lines changed

‎README.md‎

Lines changed: 26 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -39,25 +39,33 @@ To use this package, install via Composer by adding the following to your applic
3939

4040
## Usage
4141

42+
This library uses named parameters to specify optional arguments.
43+
Parameters with a default value must be set by name.
44+
4245
```php
4346
<?php
4447

4548
use Scrapegraphai\Client;
46-
use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
4749

4850
$client = new Client(
4951
apiKey: getenv("SCRAPEGRAPHAI_API_KEY") ?: "My API Key",
5052
environment: "environment_1",
5153
);
5254

53-
$params = SmartscraperCreateParams::with(
55+
$completedSmartscraper = $client->smartscraper->create(
5456
userPrompt: "Extract the product name, price, and description"
5557
);
5658

57-
$completedSmartscraper = $client->smartscraper->create($params);
5859
var_dump($completedSmartscraper->request_id);
5960
```
6061

62+
## Value Objects
63+
64+
It is recommended to use the `with` constructor `Dog::with(name: "Joey")`
65+
and named parameters to initialize value objects.
66+
67+
However builders are provided as well `(new Dog)->withName("Joey")`.
68+
6169
### Handling errors
6270

6371
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:
@@ -66,21 +74,19 @@ When the library is unable to connect to the API, or if the API returns a non-su
6674
<?php
6775

6876
use Scrapegraphai\Errors\APIConnectionError;
69-
use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
7077

71-
$params = SmartscraperCreateParams::with(
72-
userPrompt: "Extract the product name, price, and description"
73-
);
7478
try {
75-
$Smartscraper = $client->smartscraper->create($params);
79+
$completedSmartscraper = $client->smartscraper->create(
80+
userPrompt: "Extract the product name, price, and description"
81+
);
7682
} catch (APIConnectionError $e) {
77-
echo "The server could not be reached", PHP_EOL;
78-
var_dump($e->getPrevious());
83+
echo "The server could not be reached", PHP_EOL;
84+
var_dump($e->getPrevious());
7985
} catch (RateLimitError $_) {
80-
echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
86+
echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
8187
} catch (APIStatusError $e) {
82-
echo "Another non-200-range status code was received", PHP_EOL;
83-
echo $e->getMessage();
88+
echo "Another non-200-range status code was received", PHP_EOL;
89+
echo $e->getMessage();
8490
}
8591
```
8692

@@ -113,17 +119,15 @@ You can use the `max_retries` option to configure or disable this:
113119

114120
use Scrapegraphai\Client;
115121
use Scrapegraphai\RequestOptions;
116-
use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
117122

118123
// Configure the default for all requests:
119124
$client = new Client(maxRetries: 0);
120-
$params = SmartscraperCreateParams::with(
121-
userPrompt: "Extract the product name, price, and description"
122-
);
123125

124-
// Or, configure per-request:$result = $client
125-
->smartscraper
126-
->create($params, new RequestOptions(maxRetries: 5));
126+
// Or, configure per-request:
127+
$result = $client->smartscraper->create(
128+
userPrompt: "Extract the product name, price, and description",
129+
new RequestOptions(maxRetries: 5),
130+
);
127131
```
128132

129133
## Advanced concepts
@@ -140,15 +144,9 @@ Note: the `extra_` parameters of the same name overrides the documented paramete
140144
<?php
141145

142146
use Scrapegraphai\RequestOptions;
143-
use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
144147

145-
$params = SmartscraperCreateParams::with(
146-
userPrompt: "Extract the product name, price, and description"
147-
);
148-
$completedSmartscraper = $client
149-
->smartscraper
150-
->create(
151-
$params,
148+
$completedSmartscraper = $client->smartscraper->create(
149+
userPrompt: "Extract the product name, price, and description",
152150
new RequestOptions(
153151
extraQueryParams: ["my_query_parameter" => "value"],
154152
extraBodyParams: ["my_body_parameter" => "value"],

‎src/Contracts/CrawlContract.php‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44

55
namespace Scrapegraphai\Contracts;
66

7-
use Scrapegraphai\Crawl\CrawlStartParams;
87
use Scrapegraphai\Crawl\CrawlStartParams\Rules;
98
use Scrapegraphai\RequestOptions;
109
use Scrapegraphai\Responses\Crawl\CrawlGetResultsResponse;
@@ -18,20 +17,26 @@ public function retrieveResults(
1817
): CrawlGetResultsResponse;
1918

2019
/**
21-
* @param array{
22-
* url: string,
23-
* depth?: int,
24-
* extractionMode?: bool,
25-
* maxPages?: int,
26-
* prompt?: null|string,
27-
* renderHeavyJs?: bool,
28-
* rules?: Rules,
29-
* schema?: mixed,
30-
* sitemap?: bool,
31-
* }|CrawlStartParams $params
20+
* @param string $url Starting URL for crawling
21+
* @param int $depth Maximum crawl depth from starting URL
22+
* @param bool $extractionMode Use AI extraction (true) or markdown conversion (false)
23+
* @param int $maxPages Maximum number of pages to crawl
24+
* @param null|string $prompt Extraction prompt (required if extraction_mode is true)
25+
* @param bool $renderHeavyJs Enable heavy JavaScript rendering
26+
* @param Rules $rules
27+
* @param mixed $schema Output schema for extraction
28+
* @param bool $sitemap Use sitemap for crawling
3229
*/
3330
public function start(
34-
array|CrawlStartParams $params,
35-
?RequestOptions $requestOptions = null
31+
$url,
32+
$depth = null,
33+
$extractionMode = null,
34+
$maxPages = null,
35+
$prompt = null,
36+
$renderHeavyJs = null,
37+
$rules = null,
38+
$schema = null,
39+
$sitemap = null,
40+
?RequestOptions $requestOptions = null,
3641
): CrawlStartResponse;
3742
}

‎src/Contracts/FeedbackContract.php‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,20 @@
44

55
namespace Scrapegraphai\Contracts;
66

7-
use Scrapegraphai\Feedback\FeedbackSubmitParams;
87
use Scrapegraphai\RequestOptions;
98
use Scrapegraphai\Responses\Feedback\FeedbackSubmitResponse;
109

1110
interface FeedbackContract
1211
{
1312
/**
14-
* @param array{
15-
* rating: int, requestID: string, feedbackText?: null|string
16-
* }|FeedbackSubmitParams $params
13+
* @param int $rating Rating score
14+
* @param string $requestID Request to provide feedback for
15+
* @param null|string $feedbackText Optional feedback comments
1716
*/
1817
public function submit(
19-
array|FeedbackSubmitParams $params,
18+
$rating,
19+
$requestID,
20+
$feedbackText = null,
2021
?RequestOptions $requestOptions = null,
2122
): FeedbackSubmitResponse;
2223
}

‎src/Contracts/GenerateSchemaContract.php‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44

55
namespace Scrapegraphai\Contracts;
66

7-
use Scrapegraphai\GenerateSchema\GenerateSchemaCreateParams;
87
use Scrapegraphai\RequestOptions;
98
use Scrapegraphai\Responses\GenerateSchema\GenerateSchemaGetResponse\CompletedSchemaGenerationResponse;
109
use Scrapegraphai\Responses\GenerateSchema\GenerateSchemaGetResponse\FailedSchemaGenerationResponse;
@@ -13,12 +12,12 @@
1312
interface GenerateSchemaContract
1413
{
1514
/**
16-
* @param array{
17-
* userPrompt: string, existingSchema?: mixed
18-
* }|GenerateSchemaCreateParams $params
15+
* @param string $userPrompt Natural language description of desired schema
16+
* @param mixed $existingSchema Existing schema to modify or extend
1917
*/
2018
public function create(
21-
array|GenerateSchemaCreateParams $params,
19+
$userPrompt,
20+
$existingSchema = null,
2221
?RequestOptions $requestOptions = null,
2322
): GenerateSchemaNewResponse;
2423

‎src/Contracts/MarkdownifyContract.php‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,20 @@
55
namespace Scrapegraphai\Contracts;
66

77
use Scrapegraphai\Markdownify\CompletedMarkdownify;
8-
use Scrapegraphai\Markdownify\MarkdownifyConvertParams;
98
use Scrapegraphai\RequestOptions;
109
use Scrapegraphai\Responses\Markdownify\MarkdownifyGetStatusResponse\FailedMarkdownifyResponse;
1110

1211
interface MarkdownifyContract
1312
{
1413
/**
15-
* @param array{
16-
* websiteURL: string, headers?: array<string, string>, steps?: list<string>
17-
* }|MarkdownifyConvertParams $params
14+
* @param string $websiteURL URL to convert to markdown
15+
* @param array<string, string> $headers
16+
* @param list<string> $steps Interaction steps before conversion
1817
*/
1918
public function convert(
20-
array|MarkdownifyConvertParams $params,
19+
$websiteURL,
20+
$headers = null,
21+
$steps = null,
2122
?RequestOptions $requestOptions = null,
2223
): CompletedMarkdownify;
2324

‎src/Contracts/SearchscraperContract.php‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,20 @@
77
use Scrapegraphai\RequestOptions;
88
use Scrapegraphai\Responses\Searchscraper\SearchscraperGetStatusResponse\FailedSearchScraperResponse;
99
use Scrapegraphai\Searchscraper\CompletedSearchScraper;
10-
use Scrapegraphai\Searchscraper\SearchscraperCreateParams;
1110

1211
interface SearchscraperContract
1312
{
1413
/**
15-
* @param array{
16-
* userPrompt: string,
17-
* headers?: array<string, string>,
18-
* numResults?: int,
19-
* outputSchema?: mixed,
20-
* }|SearchscraperCreateParams $params
14+
* @param string $userPrompt Search query and extraction instruction
15+
* @param array<string, string> $headers
16+
* @param int $numResults Number of websites to scrape from search results
17+
* @param mixed $outputSchema JSON schema for structured output
2118
*/
2219
public function create(
23-
array|SearchscraperCreateParams $params,
20+
$userPrompt,
21+
$headers = null,
22+
$numResults = null,
23+
$outputSchema = null,
2424
?RequestOptions $requestOptions = null,
2525
): CompletedSearchScraper;
2626

‎src/Contracts/SmartscraperContract.php‎

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,32 @@
77
use Scrapegraphai\RequestOptions;
88
use Scrapegraphai\Smartscraper\CompletedSmartscraper;
99
use Scrapegraphai\Smartscraper\FailedSmartscraper;
10-
use Scrapegraphai\Smartscraper\SmartscraperCreateParams;
1110

1211
interface SmartscraperContract
1312
{
1413
/**
15-
* @param array{
16-
* userPrompt: string,
17-
* cookies?: array<string, string>,
18-
* headers?: array<string, string>,
19-
* numberOfScrolls?: int,
20-
* outputSchema?: mixed,
21-
* renderHeavyJs?: bool,
22-
* steps?: list<string>,
23-
* totalPages?: int,
24-
* websiteHTML?: string,
25-
* websiteURL?: string,
26-
* }|SmartscraperCreateParams $params
14+
* @param string $userPrompt Extraction instruction for the LLM
15+
* @param array<string, string> $cookies Cookies to include in the request
16+
* @param array<string, string> $headers HTTP headers to include in the request
17+
* @param int $numberOfScrolls Number of infinite scroll operations to perform
18+
* @param mixed $outputSchema JSON schema defining the expected output structure
19+
* @param bool $renderHeavyJs Enable heavy JavaScript rendering
20+
* @param list<string> $steps Website interaction steps (e.g., clicking buttons)
21+
* @param int $totalPages Number of pages to process for pagination
22+
* @param string $websiteHTML HTML content to process (max 2MB, mutually exclusive with website_url)
23+
* @param string $websiteURL URL to scrape (mutually exclusive with website_html)
2724
*/
2825
public function create(
29-
array|SmartscraperCreateParams $params,
26+
$userPrompt,
27+
$cookies = null,
28+
$headers = null,
29+
$numberOfScrolls = null,
30+
$outputSchema = null,
31+
$renderHeavyJs = null,
32+
$steps = null,
33+
$totalPages = null,
34+
$websiteHTML = null,
35+
$websiteURL = null,
3036
?RequestOptions $requestOptions = null,
3137
): CompletedSmartscraper;
3238

‎src/Crawl/CrawlService.php‎

Lines changed: 31 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -38,25 +38,41 @@ public function retrieveResults(
3838
* Supports both AI extraction mode and markdown conversion mode.
3939
* Returns a task ID for async processing.
4040
*
41-
* @param array{
42-
* url: string,
43-
* depth?: int,
44-
* extractionMode?: bool,
45-
* maxPages?: int,
46-
* prompt?: null|string,
47-
* renderHeavyJs?: bool,
48-
* rules?: Rules,
49-
* schema?: mixed,
50-
* sitemap?: bool,
51-
* }|CrawlStartParams $params
41+
* @param string $url Starting URL for crawling
42+
* @param int $depth Maximum crawl depth from starting URL
43+
* @param bool $extractionMode Use AI extraction (true) or markdown conversion (false)
44+
* @param int $maxPages Maximum number of pages to crawl
45+
* @param null|string $prompt Extraction prompt (required if extraction_mode is true)
46+
* @param bool $renderHeavyJs Enable heavy JavaScript rendering
47+
* @param Rules $rules
48+
* @param mixed $schema Output schema for extraction
49+
* @param bool $sitemap Use sitemap for crawling
5250
*/
5351
public function start(
54-
array|CrawlStartParams $params,
55-
?RequestOptions $requestOptions = null
52+
$url,
53+
$depth = null,
54+
$extractionMode = null,
55+
$maxPages = null,
56+
$prompt = null,
57+
$renderHeavyJs = null,
58+
$rules = null,
59+
$schema = null,
60+
$sitemap = null,
61+
?RequestOptions $requestOptions = null,
5662
): CrawlStartResponse {
5763
[$parsed, $options] = CrawlStartParams::parseRequest(
58-
$params,
59-
$requestOptions
64+
[
65+
'url' => $url,
66+
'depth' => $depth,
67+
'extractionMode' => $extractionMode,
68+
'maxPages' => $maxPages,
69+
'prompt' => $prompt,
70+
'renderHeavyJs' => $renderHeavyJs,
71+
'rules' => $rules,
72+
'schema' => $schema,
73+
'sitemap' => $sitemap,
74+
],
75+
$requestOptions,
6076
);
6177
$resp = $this->client->request(
6278
method: 'post',

‎src/Feedback/FeedbackService.php‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,23 @@ public function __construct(private Client $client) {}
1717
/**
1818
* Submit feedback for a specific request.
1919
*
20-
* @param array{
21-
* rating: int, requestID: string, feedbackText?: null|string
22-
* }|FeedbackSubmitParams $params
20+
* @param int $rating Rating score
21+
* @param string $requestID Request to provide feedback for
22+
* @param null|string $feedbackText Optional feedback comments
2323
*/
2424
public function submit(
25-
array|FeedbackSubmitParams $params,
26-
?RequestOptions $requestOptions = null
25+
$rating,
26+
$requestID,
27+
$feedbackText = null,
28+
?RequestOptions $requestOptions = null,
2729
): FeedbackSubmitResponse {
2830
[$parsed, $options] = FeedbackSubmitParams::parseRequest(
29-
$params,
30-
$requestOptions
31+
[
32+
'rating' => $rating,
33+
'requestID' => $requestID,
34+
'feedbackText' => $feedbackText,
35+
],
36+
$requestOptions,
3137
);
3238
$resp = $this->client->request(
3339
method: 'post',

0 commit comments

Comments
 (0)