docs: align nullable-id casts, add ApifyClient methods table, clarify runnable guarantee

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rkZYoebybdnv7MFH9Ua6E

Author: claude

README.md

@@ -31,8 +31,9 @@ $client = new ApifyClient('my-api-token');
 // pass a value (e.g. 120) to bound the wait, or null to wait indefinitely (as here).
 $run = $client->actor('apify/hello-world')->call(null, null, null);
 
-// Read items from the run's default dataset.
-$items = $client->dataset($run->getDefaultDatasetId())->listItems();
+// Read items from the run's default dataset. getDefaultDatasetId() is ?string, so cast it
+// to satisfy dataset(string $id).
+$items = $client->dataset((string) $run->getDefaultDatasetId())->listItems();
 echo 'Item count: ' . $items->getCount() . PHP_EOL;
 ```
 

docs/README.md

@@ -42,6 +42,44 @@ PSR-7 `Psr\Http\Message\StreamInterface` (from the `psr/http-message` package),
 Methods that fetch a single resource return `null` when the resource does not exist, rather than
 throwing. API failures are thrown as `ApifyApiException` (see [error handling](../README.md#error-handling)).
 
+## ApifyClient methods
+
+`ApifyClient` is the entry point: construct one, then call an accessor to get a sub-client for a
+specific resource or collection. Single-resource accessors take an ID (or, where the API allows it,
+a name) and return that resource's client; collection accessors take no arguments and return a
+collection client for listing and creating. Method detail lives on the linked [resource
+pages](#resource-pages); the signatures below are the entry points.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `actor(string $id): ActorClient` | Actor client | Single Actor, by ID or `username/name`. |
+| `actors(): ActorCollectionClient` | Actor collection | List and create Actors. |
+| `build(string $id): BuildClient` | Build client | Single Actor build. |
+| `builds(): BuildCollectionClient` | Build collection | List builds across Actors. |
+| `run(string $id): RunClient` | Run client | Single Actor run. |
+| `runs(): RunCollectionClient` | Run collection | List runs across Actors. |
+| `dataset(string $id): DatasetClient` | Dataset client | Single dataset, by ID or name. |
+| `datasets(): DatasetCollectionClient` | Dataset collection | List and create datasets. |
+| `keyValueStore(string $id): KeyValueStoreClient` | Key-value store client | Single store, by ID or name. |
+| `keyValueStores(): KeyValueStoreCollectionClient` | Key-value store collection | List and create stores. |
+| `requestQueue(string $id, ?RequestQueueClientOptions $options = null): RequestQueueClient` | Request queue client | Single queue, by ID or name; optional client options (`clientKey`, per-request `timeoutSecs`). |
+| `requestQueues(): RequestQueueCollectionClient` | Request queue collection | List and create queues. |
+| `task(string $id): TaskClient` | Task client | Single task. |
+| `tasks(): TaskCollectionClient` | Task collection | List and create tasks. |
+| `schedule(string $id): ScheduleClient` | Schedule client | Single schedule. |
+| `schedules(): ScheduleCollectionClient` | Schedule collection | List and create schedules. |
+| `webhook(string $id): WebhookClient` | Webhook client | Single webhook. |
+| `webhooks(): WebhookCollectionClient` | Webhook collection | List and create webhooks. |
+| `webhookDispatch(string $id): WebhookDispatchClient` | Webhook dispatch client | Single webhook dispatch. |
+| `webhookDispatches(): WebhookDispatchCollectionClient` | Webhook dispatch collection | List webhook dispatches. |
+| `store(): StoreCollectionClient` | Store collection | Browse the public Apify Store. |
+| `log(string $buildOrRunId): LogClient` | Log client | Log for a build or run, by ID. |
+| `me(): UserClient` | User client | The authenticated user (`users/me`). |
+| `user(string $id): UserClient` | User client | A public user profile, by ID. |
+| `setStatusMessage(string $message, bool $isTerminal = false): ActorRun` | Updated run | Set the current run's status message; see [Setting single-resource status](#setting-single-resource-status). |
+| `getUserAgent(): string` | User-Agent string | The `User-Agent` the client sends. |
+| `getApiBaseUrl(): string` | Base URL | The resolved API base URL (with `/v2`). |
+
 ## Models and unmodeled data (`toArray`)
 
 Response models expose the commonly-used fields as typed getters (e.g. `$actor->getId()`). The

docs/examples.md

@@ -3,9 +3,11 @@
 Each snippet below assumes a configured `$client` and that the types it uses are imported with the
 appropriate `use` statements (see [Namespaces](README.md#namespaces)); the first
 [complete program](#a-complete-standalone-program) shows the full scaffolding the shorter snippets
-omit for brevity. The same programs live under [`tests/Examples/`](../tests/Examples) and are executed
-end-to-end against the live API by the `Test examples` CI step (see `ExamplesTest`), so they are
-guaranteed to stay runnable.
+omit for brevity. The complete programs on this page live under
+[`tests/Examples/`](../tests/Examples) and are executed end-to-end against the live API by the
+`Test examples` CI step (see `ExamplesTest`), so those programs are guaranteed to stay runnable.
+Inline snippets on the other documentation pages are not executed: they are only syntax-checked with
+`php -l` by `DocSnippetsTest`, which catches parse errors but does not resolve classes or check types.
 
 ## A complete, standalone program
 
@@ -30,8 +32,9 @@ try {
     // Run a public store Actor and wait up to 120s for it to finish.
     $run = $client->actor('apify/hello-world')->call(null, null, 120);
 
-    // Read the items the run produced into its default dataset.
-    $items = $client->dataset($run->getDefaultDatasetId())->listItems();
+    // Read the items the run produced into its default dataset. getDefaultDatasetId() is
+    // ?string, so cast it to satisfy dataset(string $id).
+    $items = $client->dataset((string) $run->getDefaultDatasetId())->listItems();
     echo 'Item count: ' . $items->getCount() . PHP_EOL;
 } catch (ApifyApiException $e) {
     echo 'API error ' . $e->getStatusCode() . ': ' . $e->getApiMessage() . PHP_EOL;
@@ -42,7 +45,8 @@ try {
 
 ```php
 $run = $client->actor('apify/hello-world')->call(null, null, 120);
-$items = $client->dataset($run->getDefaultDatasetId())->listItems();
+// getDefaultDatasetId() is ?string, so cast it to satisfy dataset(string $id).
+$items = $client->dataset((string) $run->getDefaultDatasetId())->listItems();
 echo 'Item count: ' . $items->getCount() . PHP_EOL;
 ```