feat: add files

Author: VinciGit00

examples/README.md

@@ -0,0 +1,126 @@
+# ScrapeGraphAI PHP SDK Examples
+
+This directory contains comprehensive examples demonstrating how to use the ScrapeGraphAI PHP SDK for various web scraping and data extraction tasks.
+
+## Prerequisites
+
+Before running the examples, make sure you have:
+
+1. **PHP 8.1+** installed
+2. **Composer** installed
+3. **ScrapeGraphAI API Key** - Get one from [scrapegraphai.com](https://scrapegraphai.com)
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   composer install
+   ```
+
+2. Set your API key as an environment variable:
+   ```bash
+   export SCRAPEGRAPHAI_API_KEY="your-api-key-here"
+   ```
+
+   Or create a `.env` file in the examples directory:
+   ```
+   SCRAPEGRAPHAI_API_KEY=your-api-key-here
+   ```
+
+## Examples Overview
+
+### Basic Examples
+- **[basic-smartscraper.php](basic/basic-smartscraper.php)** - Simple web page scraping
+- **[basic-markdownify.php](basic/basic-markdownify.php)** - Convert web pages to Markdown
+- **[basic-searchscraper.php](basic/basic-searchscraper.php)** - Search and scrape multiple websites
+- **[basic-crawl.php](basic/basic-crawl.php)** - Website crawling
+- **[basic-schema.php](basic/basic-schema.php)** - Generate JSON schemas
+- **[basic-credits.php](basic/basic-credits.php)** - Check API credits
+- **[basic-validate.php](basic/basic-validate.php)** - Validate API key
+
+### Advanced Examples
+- **[advanced-smartscraper.php](advanced/advanced-smartscraper.php)** - Advanced scraping with custom schemas
+- **[advanced-crawl.php](advanced/advanced-crawl.php)** - Complex crawling with rules and filters
+- **[advanced-error-handling.php](advanced/advanced-error-handling.php)** - Comprehensive error handling
+- **[advanced-pagination.php](advanced/advanced-pagination.php)** - Handle paginated content
+- **[advanced-javascript.php](advanced/advanced-javascript.php)** - Scrape JavaScript-heavy sites
+
+### Real-World Use Cases
+- **[ecommerce-scraper.php](use-cases/ecommerce-scraper.php)** - E-commerce product scraping
+- **[news-aggregator.php](use-cases/news-aggregator.php)** - News article extraction
+- **[social-media.php](use-cases/social-media.php)** - Social media content scraping
+- **[job-listings.php](use-cases/job-listings.php)** - Job board scraping
+- **[real-estate.php](use-cases/real-estate.php)** - Real estate listing scraping
+
+## Running Examples
+
+To run any example:
+
+```bash
+cd examples
+php basic/basic-smartscraper.php
+```
+
+## Common Patterns
+
+### 1. Basic Client Setup
+```php
+<?php
+require_once '../vendor/autoload.php';
+
+use Scrapegraphai\Client;
+
+$client = new Client(
+    apiKey: getenv('SCRAPEGRAPHAI_API_KEY')
+);
+```
+
+### 2. Error Handling
+```php
+use Scrapegraphai\Errors\APIError;
+use Scrapegraphai\Errors\RateLimitError;
+
+try {
+    $result = $client->smartscraper->create($params);
+} catch (RateLimitError $e) {
+    echo "Rate limit exceeded. Please wait before retrying.\n";
+} catch (APIError $e) {
+    echo "API Error: " . $e->getMessage() . "\n";
+}
+```
+
+### 3. Async Operations
+Many operations are asynchronous. You'll need to poll for results:
+
+```php
+// Start the operation
+$response = $client->smartscraper->create($params);
+$requestId = $response->request_id;
+
+// Poll for completion
+do {
+    sleep(2);
+    $result = $client->smartscraper->retrieve($requestId);
+} while ($result->status === 'processing');
+```
+
+## Tips
+
+- Always handle errors appropriately
+- Use structured output schemas for consistent data extraction
+- Be mindful of rate limits
+- Cache results when possible to save credits
+- Use the most specific scraper for your use case:
+  - **SmartScraper**: Single page extraction
+  - **SearchScraper**: Search and extract from multiple sources  
+  - **Crawler**: Full website crawling
+  - **Markdownify**: Convert to clean Markdown format
+
+## Support
+
+If you encounter issues with these examples:
+
+1. Check your API key is correctly set
+2. Ensure you have sufficient credits
+3. Review the [official documentation](https://scrapegraphai.com)
+4. File an issue on [GitHub](https://github.com/stainless-sdks/scrapegraphai-php/issues)