Download the PHP package browserbase/stagehand without Composer

The AI Browser Automation Framework

If you're looking for other languages, you can find them here

## What is Stagehand? Stagehand is a browser automation framework used to control web browsers with natural language and code. By combining the power of AI with the precision of code, Stagehand makes web automation flexible, maintainable, and actually reliable. ## Why Stagehand? Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language (and bridging the gap between the two) Stagehand is the natural choice for browser automations in production. 1. **Choose when to write code vs. natural language**: use AI when you want to navigate unfamiliar pages, and use code when you know exactly what you want to do. 2. **Go from AI-driven to repeatable workflows**: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens. 3. **Write once, run forever**: Stagehand's auto-caching combined with self-healing remembers previous actions, runs without LLM inference, and knows when to involve AI whenever the website changes and your automation breaks. # Stagehand PHP API library The Stagehand PHP library provides convenient access to the Stagehand REST API from any PHP 8.1.0+ application. It is generated with [Stainless](https://www.stainless.com/). ## Documentation The REST API documentation can be found on [docs.stagehand.dev](https://docs.stagehand.dev). ## Installation ## Usage This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name. Here's a comprehensive example demonstrating the full workflow: start session, navigate, observe, act, extract, execute agent, and end session. ### Running the Example Set the environment variables and run the example script: ### Value Objects It is recommended to use the static `with` constructor `Action::with(description: 'Click the submit button', ...)` and named parameters to initialize value objects. However, builders are also provided `(new Action)->withDescription('Click the submit button')`. ### Streaming We provide support for streaming responses using Server-Sent Events (SSE). Streaming requests are dispatched through a separate `streamingTransporter` PSR-18 HTTP client. When unset, the SDK uses the configured `transporter`. Some PSR-18 HTTP clients will by default try to read the entire response, so you may need to specify a streaming capable implementation. ### 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 `Stagehand\Core\Exceptions\APIException` will be thrown: Error codes are as follows: | 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 `maxRetries` option to configure or disable this: ## Advanced concepts ### Making custom or undocumented requests #### Undocumented properties 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. #### Undocumented request params If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above. #### Undocumented endpoints To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so: ## Versioning This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time. This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes. ## Requirements PHP 8.1.0 or higher. ## Contributing See [the contributing documentation](https://github.com/browserbase/stagehand-php/tree/main/CONTRIBUTING.md).