Download the PHP package scrapingisnotacrime/sdk without Composer

ScrapingIsNotACrime PHP SDK

Official PHP SDK for the ScrapingIsNotACrime public data API — typed access to Instagram, TikTok, YouTube, the App Store, GitHub, Hacker News, Bluesky, Twitch and Linktree.

Install

The SDK talks over any PSR-18 HTTP client and any PSR-17 request factory. It declares those as virtual *-implementation requirements, so Composer's php-http/discovery plugin installs a PSR-18 client and PSR-17 factories for you if your project has none yet — Composer asks once whether to allow the plugin to run; answer yes. With either Symfony HttpClient or Guzzle (guzzlehttp/guzzle) present, the SDK builds its own client from whichever one it finds and configures its timeout and turns off redirects on it — but only for that client. With some other PSR-18 client already in your project, the SDK uses it as found via discovery, and that client's own timeout and redirect behavior apply instead (see Bring your own client to configure one yourself).

The explicit alternative, if you'd rather pick the implementation yourself:

If no PSR-18 client or no PSR-17 factory can be found at all, the constructor throws \LogicException with a composer require hint.

Requires PHP 8.2+.

Quick start

new Client() with no arguments also reads the API key from the SCRAPINGISNOTACRIME_API_KEY environment variable. Get a key at scrapingisnotacrime.com/dashboard/api-keys. Keys start with sinac_.

Configuration

Bring your own client

Pass httpClient to use a client you configure yourself — for tests, proxies or connection pooling. The SDK never modifies it, so set its own timeout and turn off redirects (the SDK does this automatically only for the client it builds itself).

Guzzle:

Symfony HttpClient:

Methods

Client groups its methods under a property per platform: $client->instagram, $client->tiktok, $client->youtube, $client->appstore, $client->github, $client->hackernews, $client->bluesky, $client->twitch, $client->linktree. Every method returns the response envelope's data, decoded into a typed Types\* object; a method marked Page returns a Page instead (see Pagination). Response objects are built by the SDK; construct them with X::fromArray() if you need one in tests — constructor parameters may be reordered in minor releases.

since (trending's argument) accepts a GithubTrendingSince case (GithubTrendingSince::Daily/Weekly/Monthly) or its string value; feed (feed's argument) accepts a HackernewsFeed case (HackernewsFeed::Top/New/Best/Ask/Show/Job) or its string value — an unrecognized string throws \InvalidArgumentException. Every optional argument defaults to null, meaning "use the API's default". Path arguments (username, handle, shortcode, …) are validated before any request: an empty string, "." or ".." throws \InvalidArgumentException, and the value is percent-encoded the way JavaScript's encodeURIComponent would encode it.

Pagination

Methods marked Page return a ScrapingIsNotACrime\Page:

hasMore is true exactly when next() will fetch another page (an empty final page, or an announced next page/cursor with no items, both leave it false).

Walk pages one at a time with next(). Each page fetched is one billed request, so bound the loop:

Or iterate every item with foreach, which fetches later pages lazily. Iterating fetches every remaining page; each page is one billed request, so bound the loop:

$page->data is the current page's typed page object (e.g. GithubUserPage), so fields such as ->total stay reachable.

Errors

Every failure the SDK raises is an exception under ScrapingIsNotACrime\Exception, all extending ScrapingIsNotACrimeException (itself a \RuntimeException) with ->status (the HTTP status, or null for network errors) and ->requestId (the X-Request-Id header, when the API sends one). An invalid argument — a bad path segment or an unrecognized enum string — throws \InvalidArgumentException instead, before any request is made. Numeric options such as limit, count or page are not range-checked client-side: an out-of-range value is sent to the API, which answers with a 400 and the SDK raises BadRequestException.

Retries

RateLimitException (429), UpstreamException (502) and ConnectionException (network failure or per-attempt timeout) are retried automatically, up to maxRetries additional attempts (default 2). These failures don't consume credits, so retrying them costs you nothing.

The delay before each retry uses the Retry-After header when the API sends one (seconds or an HTTP date); otherwise it's exponential backoff with full jitter, starting around 500 ms and doubling per attempt. Every wait is capped at 10 seconds. Set maxRetries: 0 to disable retries entirely.

Releases and changelog

Every merge to main is released automatically: the version comes from the commit messages since the last release, following Conventional Commits. The pipeline tags vX.Y.Z and publishes the GitHub Release with the notes — the tag is the release, and Packagist's GitHub hook picks up the new version, no separate publish step. The changelog is the Releases page.

Merge PRs with a merge commit or rebase so each Conventional Commit is analysed; if you squash, the PR title must be a Conventional Commit (e.g. feat: ...).

Links

• Docs: https://scrapingisnotacrime.com/docs
• Pricing: https://scrapingisnotacrime.com/#pricing
• Releases: https://github.com/ScrapingIsNotACrime/sdk-php/releases
• Go SDK: https://github.com/ScrapingIsNotACrime/sdk-go
• Python SDK: https://github.com/ScrapingIsNotACrime/sdk-python
• Node.js SDK: https://github.com/ScrapingIsNotACrime/sdk-nodejs
• MCP server: https://github.com/ScrapingIsNotACrime/mcp
• License: MIT