code-examples-template

Code Examples Template Generator

Generate effective code examples for documentation.

Example Principles

The Three Types

Type	Purpose	Length	Use When
Minimal	Show single concept	5-10 lines	Teaching one thing
Complete	Show full usage	20-50 lines	Production reference
Progressive	Build complexity	3+ examples	Tutorial style

Example Templates

Minimal Example

<?php

use Vendor\Package\Client;

$client = new Client();
$result = $client->process('data');

echo $result->status; // "success"

Characteristics:

• Single concept
• No error handling
• Shows expected output
• Copy-paste ready

Complete Example

<?php

declare(strict_types=1);

require 'vendor/autoload.php';

use Vendor\Package\Client;
use Vendor\Package\Config;
use Vendor\Package\Exception\ClientException;

// Configuration
$config = new Config(
    apiKey: getenv('API_KEY') ?: throw new RuntimeException('API_KEY required'),
    timeout: 30,
    retries: 3,
);

// Initialize client
$client = new Client($config);

try {
    // Make request
    $result = $client->process([
        'data' => 'input value',
        'options' => ['validate' => true],
    ]);

    // Handle success
    echo "Status: {$result->status}\n";
    echo "ID: {$result->id}\n";

} catch (ClientException $e) {
    // Handle error
    echo "Error: {$e->getMessage()}\n";
    exit(1);
}

/* Output:
Status: success
ID: res_abc123
*/

Characteristics:

• Full imports
• Error handling
• Configuration
• Comments for sections
• Expected output

Progressive Example

## Basic Usage

Start with the simplest case:

```php
$client = new Client();
$result = $client->ping();
// "pong"

With Configuration

Add configuration options:

$client = new Client([
    'timeout' => 30,
]);
$result = $client->ping();
// "pong"

With Authentication

Add authentication:

$client = new Client([
    'api_key' => 'your-key',
    'timeout' => 30,
]);
$result = $client->process('data');
// {"status": "success", "id": "..."}

Production Ready

Full example with error handling:

try {
    $client = new Client([
        'api_key' => getenv('API_KEY'),
        'timeout' => 30,
        'retries' => 3,
    ]);

    $result = $client->process('data');
    echo $result->status;

} catch (ClientException $e) {
    error_log($e->getMessage());
    exit(1);
}

## Example Patterns

### Before/After Pattern

```markdown
### Refactoring Example

**Before (Anti-pattern):**

```php
// ❌ Don't do this
$data = file_get_contents('data.json');
$json = json_decode($data);
if ($json === null) {
    die('Invalid JSON');
}

After (Recommended):

// ✅ Do this instead
use Vendor\Package\JsonLoader;

$loader = new JsonLoader();
$data = $loader->load('data.json');
// Throws JsonException on invalid data

### Input/Output Pattern

```markdown
### String Transformation

**Input:**
```php
$input = "Hello World";

Code:

$result = $transformer->slugify($input);

Output:

$result = "hello-world";

### Comparison Pattern

```markdown
### Framework Comparison

**Symfony:**
```php
use Symfony\Component\HttpFoundation\Response;

return new Response('Hello', 200);

Laravel:

return response('Hello', 200);

Native:

http_response_code(200);
echo 'Hello';

## Code Block Guidelines

### Language Tags

```markdown
```php      # PHP code
```bash     # Shell commands
```json     # JSON data
```yaml     # YAML config
```sql      # Database queries
```diff     # Code changes

Highlighting Important Parts

<?php

$client = new Client([
    // highlight-next-line
    'api_key' => 'your-key',  // <-- This is important
    'timeout' => 30,
]);

Showing Line Numbers

```php {1,3-5}
<?php                           // Line 1
                               // Line 2
$config = new Config();        // Line 3
$config->setTimeout(30);       // Line 4
$config->setRetries(3);        // Line 5

## Common Patterns

### CRUD Operations

```markdown
### Create

```php
$item = $client->items->create([
    'name' => 'New Item',
    'price' => 99.99,
]);
echo $item->id; // "item_abc123"

Read

$item = $client->items->get('item_abc123');
echo $item->name; // "New Item"

Update

$item = $client->items->update('item_abc123', [
    'price' => 79.99,
]);
echo $item->price; // 79.99

Delete

$client->items->delete('item_abc123');
// No return value, throws on error

List

$items = $client->items->list(['limit' => 10]);
foreach ($items as $item) {
    echo "{$item->name}: {$item->price}\n";
}

### Error Handling

```markdown
### Handling Errors

```php
use Vendor\Package\Exception\{
    NotFoundException,
    ValidationException,
    RateLimitException,
};

try {
    $result = $client->process($data);

} catch (NotFoundException $e) {
    // Resource doesn't exist
    echo "Not found: {$e->getMessage()}";

} catch (ValidationException $e) {
    // Invalid input
    foreach ($e->getErrors() as $field => $messages) {
        echo "{$field}: " . implode(', ', $messages) . "\n";
    }

} catch (RateLimitException $e) {
    // Too many requests
    sleep($e->getRetryAfter());
    // Retry...
}

### Async Operations

```markdown
### Async Processing

```php
// Start async job
$job = $client->jobs->create([
    'type' => 'export',
    'params' => ['format' => 'csv'],
]);

echo "Job started: {$job->id}\n";

// Poll for completion
while ($job->status !== 'completed') {
    sleep(5);
    $job = $client->jobs->get($job->id);
    echo "Status: {$job->status}\n";
}

// Get result
$result = $client->jobs->getResult($job->id);
file_put_contents('export.csv', $result->content);

## Quality Checklist

### Every Example Should

- [ ] Run without modification (except config)
- [ ] Show expected output
- [ ] Use realistic data (not foo/bar)
- [ ] Include necessary imports
- [ ] Follow PSR-12 style
- [ ] Match current API version

### Avoid

- [ ] Abstract examples that don't run
- [ ] Missing `<?php` tag when standalone
- [ ] Outdated syntax or deprecated methods
- [ ] Foo/Bar/Baz placeholder names
- [ ] Missing required configuration
- [ ] Unexplained magic values

## Generation Instructions

When generating code examples:

1. **Choose example type** based on purpose
2. **Use realistic data** (emails, names, prices)
3. **Include expected output** in comments
4. **Show imports** when needed
5. **Add error handling** in complete examples
6. **Test examples** actually run
7. **Match coding style** of the project