php/example_code/{service}/
├── README.md                   # Generated service README
├── composer.json               # Dependencies
└── {service}_metadata.yaml     # Metadata (in .doc_gen/metadata/)

cd .tools/readmes

# Create virtual environment
python -m venv .venv

# Activate environment (Linux/macOS)
source .venv/bin/activate

# Activate environment (Windows)
.venv\Scripts\activate

# Install dependencies
python -m pip install -r requirements_freeze.txt

# Generate README for specific service
python -m writeme --languages PHP:3 --services {service}

# {AWS Service} examples for the SDK for PHP

## Overview

This section contains examples demonstrating how to use the AWS SDK for PHP with {AWS Service}.

{AWS Service} is {brief service description and primary use cases}.

## ⚠ Important

* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/).
* Running the tests might result in charges to your AWS account.
* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).

## Prerequisites

For general prerequisites, see the [README](../../README.md#Prerequisites) in the `php` folder.

### PHP Version
* PHP 8.1 or later
* Composer for dependency management

### AWS SDK for PHP
* AWS SDK for PHP v3.209 or later

### AWS Credentials
Configure your AWS credentials using one of the following methods:
* AWS credentials file
* Environment variables
* IAM roles (for EC2 instances)
* AWS CLI configuration

## Setup

1. **Install dependencies**:
   ```bash
   composer install

php Hello{Service}.php

php Runner.php

# List resources
php -r "
require 'vendor/autoload.php';
use {Service}\{Service}Service;
\$service = new {Service}Service();
\$resources = \$service->listResources();
foreach (\$resources as \$resource) {
    echo \$resource['Name'] . \"\n\";
}
"

composer test-unit
# or
phpunit --group unit

composer test-integ
# or
phpunit --group integ

composer test
# or
phpunit

composer lint
# or
vendor/bin/phpcs --standard=../.github/linters/phpcs.xml --extensions=php --ignore=vendor ./

composer lint-fix
# or
vendor/bin/phpcbf --standard=../.github/linters/phpcs.xml --extensions=php --ignore=vendor ./

# Check PHP version
php --version

# Check required extensions
php -m | grep -E "(curl|json|mbstring|openssl|readline)"

# Update Composer
composer self-update

# Check AWS configuration
aws configure list

# Test credentials
aws sts get-caller-identity

# Set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "{service}:List*",
                "{service}:Get*",
                "{service}:Describe*",
                "{service}:Create*",
                "{service}:Update*",
                "{service}:Delete*"
            ],
            "Resource": "*"
        }
    ]
}

# Set debug environment variable
export AWS_DEBUG=1
php Hello{Service}.php

# Or enable in code
\$client = new {Service}Client([
    'region' => 'us-east-1',
    'version' => 'latest',
    'debug' => true
]);

## Documentation Dependencies

### Required Files for README Generation
- ✅ **Metadata file**: `.doc_gen/metadata/{service}_metadata.yaml`
- ✅ **Code files**: All referenced PHP files must exist
- ✅ **Snippet tags**: All snippet tags in metadata must exist in code
- ✅ **Composer file**: `composer.json` with dependencies

### Metadata Integration
The writeme tool uses metadata to:
- Generate example lists and descriptions
- Create links to specific code sections
- Include proper service information
- Format documentation consistently

## Troubleshooting README Generation

### Common Issues
- **Missing metadata**: Ensure metadata file exists and is valid
- **Broken snippet tags**: Verify all snippet tags exist in code
- **File not found**: Check all file paths in metadata
- **Invalid YAML**: Validate metadata YAML syntax

### Error Resolution
```bash
# Check for metadata errors
python -m writeme --languages PHP:3 --services {service} --verbose

# Validate specific metadata file
python -c "import yaml; yaml.safe_load(open('.doc_gen/metadata/{service}_metadata.yaml'))"

# Check for missing snippet tags
grep -r "snippet-start" php/example_code/{service}/

# In CI/CD pipeline, validate README is up-to-date
cd .tools/readmes
source .venv/bin/activate
python -m writeme --languages PHP:3 --services {service} --check

# Exit with error if README needs updates
if git diff --exit-code php/example_code/{service}/README.md; then
    echo "README is up-to-date"
else
    echo "README needs to be regenerated"
    exit 1
fi