Skip to content

Commit 4db914d

Browse files
beqqrry-awsbeqqrry-aws
committed
Update php-tech to have split files
1 parent e7459ae commit 4db914d

File tree

8 files changed

+1674
-479
lines changed

8 files changed

+1674
-479
lines changed

‎steering_docs/php-tech.md‎

Lines changed: 0 additions & 479 deletions
This file was deleted.

‎steering_docs/php-tech/basics.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# PHP Interactive Scenario Generation
2+
3+
## MANDATORY: Knowledge Base Consultation (FIRST STEP)
4+
**🚨 CRITICAL - Must be completed BEFORE any code generation**
5+
6+
```bash
7+
# Step 1: List available knowledge bases
8+
ListKnowledgeBases()
9+
10+
# Step 2: Query coding standards (REQUIRED)
11+
QueryKnowledgeBases("coding-standards-KB", "PHP-code-example-standards")
12+
13+
# Step 3: Query implementation patterns (REQUIRED)
14+
QueryKnowledgeBases("PHP-premium-KB", "PHP implementation patterns structure")
15+
16+
# Step 4: AWS service research (REQUIRED)
17+
search_documentation("What is [AWS Service] and what are its key API operations?")
18+
read_documentation("https://docs.aws.amazon.com/[service]/latest/[relevant-page]")
19+
```
20+
21+
**FAILURE TO COMPLETE KNOWLEDGE BASE CONSULTATION WILL RESULT IN INCORRECT CODE STRUCTURE**
22+
23+
## Purpose
24+
Generate interactive scenarios that demonstrate complete workflows using multiple service operations in a guided, educational manner. Implementation must be based on the service SPECIFICATION.md file.
25+
26+
## Requirements
27+
- **Specification-Driven**: MUST read the `scenarios/basics/{service}/SPECIFICATION.md`
28+
- **Interactive**: Use `testable_readline()` for user input and clear output
29+
- **Educational**: Break complex workflows into logical phases
30+
- **Comprehensive**: Cover setup, demonstration, examination, and cleanup
31+
- **Error Handling**: Graceful error handling with user-friendly messages
32+
- **Service Classes**: MUST use service wrapper classes for all operations
33+
- **Runner Pattern**: MUST implement interactive Runner.php pattern
34+
35+
## File Structure
36+
```
37+
example_code/{service}/
38+
├── Runner.php # Interactive menu runner
39+
├── {Service}Service.php # Service wrapper class
40+
├── composer.json
41+
├── README.md
42+
└── tests/
43+
├── {Service}Test.php
44+
└── phpunit.xml
45+
```## MA
46+
NDATORY Pre-Implementation Steps
47+
48+
### Step 1: Read Service Specification
49+
**CRITICAL**: Always read `scenarios/basics/{service}/SPECIFICATION.md` first to understand:
50+
- **API Actions Used**: Exact operations to implement
51+
- **Proposed Example Structure**: Setup, demonstration, examination, cleanup phases
52+
- **Error Handling**: Specific error codes and handling requirements
53+
- **Scenario Flow**: Step-by-step workflow description
54+
55+
### Step 2: Extract Implementation Requirements
56+
From the specification, identify:
57+
- **Setup Phase**: What resources need to be created/configured
58+
- **Demonstration Phase**: What operations to demonstrate
59+
- **Examination Phase**: What data to display and how to filter/analyze
60+
- **Cleanup Phase**: What resources to clean up and user options
61+
62+
## Runner Pattern Structure
63+
**MANDATORY for most services:**
64+
65+
```php
66+
<?php
67+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
68+
// SPDX-License-Identifier: Apache-2.0
69+
70+
require 'vendor/autoload.php';
71+
72+
use {Service}\{Service}Service;
73+
74+
echo "Welcome to the {AWS Service} examples!\n";
75+
echo "Choose an option:\n";
76+
echo "1. Hello {Service}\n";
77+
echo "2. Run {Service} Basics Scenario\n";
78+
echo "3. List {Resources}\n";
79+
echo "4. Create {Resource}\n";
80+
echo "5. Delete {Resource}\n";
81+
echo "0. Exit\n";
82+
83+
$choice = testable_readline("Enter your choice: ");
84+
85+
switch ($choice) {
86+
case '1':
87+
require 'Hello{Service}.php';
88+
break;
89+
case '2':
90+
$service = new {Service}Service();
91+
runBasicsScenario($service);
92+
break;
93+
case '3':
94+
$service = new {Service}Service();
95+
$service->list{Resources}();
96+
break;
97+
case '4':
98+
$service = new {Service}Service();
99+
$resourceName = testable_readline("Enter resource name: ");
100+
$service->create{Resource}($resourceName);
101+
break;
102+
case '5':
103+
$service = new {Service}Service();
104+
$resourceId = testable_readline("Enter resource ID: ");
105+
$service->delete{Resource}($resourceId);
106+
break;
107+
case '0':
108+
echo "Goodbye!\n";
109+
break;
110+
default:
111+
echo "Invalid choice\n";
112+
}
113+
```
114+
115+
## Scenario Phase Structure (Based on Specification)
116+
117+
### Setup Phase
118+
- **Read specification Setup section** for exact requirements
119+
- Check for existing resources as specified
120+
- Create necessary resources using service methods
121+
- Configure service settings per specification
122+
- Verify setup completion as described
123+
124+
### Demonstration Phase
125+
- **Follow specification Demonstration section** exactly
126+
- Perform core service operations using service methods
127+
- Generate sample data if specified in the specification
128+
- Show service capabilities as outlined
129+
- Provide educational context from specification
130+
131+
### Examination Phase
132+
- **Implement specification Examination section** requirements
133+
- List and examine results using service methods
134+
- Filter and analyze data as specified
135+
- Display detailed information per specification format
136+
- Allow user interaction as described in specification
137+
138+
### Cleanup Phase
139+
- **Follow specification Cleanup section** guidance
140+
- Offer cleanup options with warnings from specification
141+
- Handle cleanup errors gracefully using service methods
142+
- Provide alternative management options as specified
143+
- Confirm completion per specification
144+
145+
## User Interaction Patterns
146+
147+
### Input Handling
148+
```php
149+
// Yes/No questions
150+
$useExisting = testable_readline("Use existing resource? (y/n): ");
151+
$isYes = strtolower($useExisting) === 'y';
152+
153+
// Text input
154+
$resourceName = testable_readline("Enter resource name: ");
155+
156+
// Numeric input with validation
157+
do {
158+
$count = testable_readline("How many items? ");
159+
} while (!is_numeric($count) || $count < 1);
160+
```
161+
162+
### Information Display
163+
```php
164+
// Progress indicators
165+
echo "✓ Operation completed successfully\n";
166+
echo "⚠ Warning message\n";
167+
echo "✗ Error occurred\n";
168+
169+
// Formatted output
170+
echo str_repeat('-', 60) . "\n";
171+
echo "Found " . count($items) . " items:\n";
172+
foreach ($items as $item) {
173+
echo " • {$item['name']}\n";
174+
}
175+
```
176+
177+
## Runner Requirements
178+
- ✅ **ALWAYS** read and implement based on `scenarios/basics/{service}/SPECIFICATION.md`
179+
- ✅ **ALWAYS** provide interactive menu for multiple examples
180+
- ✅ **ALWAYS** include hello scenario as first option
181+
- ✅ **ALWAYS** handle user input gracefully using `testable_readline()`
182+
- ✅ **ALWAYS** include proper error handling
183+
- ✅ **ALWAYS** provide clear output and feedback
184+
- ✅ **ALWAYS** use service wrapper classes for all AWS operations
185+
- ✅ **ALWAYS** implement proper cleanup in finally block
186+
- ✅ **ALWAYS** break scenario into logical phases per specification
187+
- ✅ **ALWAYS** include error handling per specification's Errors section
188+
- ✅ **ALWAYS** provide educational context and explanations from specification

‎steering_docs/php-tech/hello.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# PHP Hello Examples Generation
2+
3+
## MANDATORY: Knowledge Base Consultation (FIRST STEP)
4+
**🚨 CRITICAL - Must be completed BEFORE any code generation**
5+
6+
```bash
7+
# Step 1: List available knowledge bases
8+
ListKnowledgeBases()
9+
10+
# Step 2: Query coding standards (REQUIRED)
11+
QueryKnowledgeBases("coding-standards-KB", "PHP-code-example-standards")
12+
13+
# Step 3: Query implementation patterns (REQUIRED)
14+
QueryKnowledgeBases("PHP-premium-KB", "PHP implementation patterns")
15+
16+
# Step 4: AWS service research (REQUIRED)
17+
search_documentation("What is [AWS Service] and what are its key API operations?")
18+
read_documentation("https://docs.aws.amazon.com/[service]/latest/[relevant-page]")
19+
```
20+
21+
**FAILURE TO COMPLETE KNOWLEDGE BASE CONSULTATION WILL RESULT IN INCORRECT CODE STRUCTURE**
22+
23+
## Purpose
24+
Generate simple "Hello" examples that demonstrate basic service connectivity and the most fundamental operation using direct AWS SDK for PHP client calls.
25+
26+
## Requirements
27+
- **MANDATORY**: Every AWS service MUST include a "Hello" scenario
28+
- **Simplicity**: Should be the most basic, minimal example possible
29+
- **Standalone**: Must work independently of other examples
30+
- **Direct Client**: Use AWS SDK for PHP client directly, no wrapper classes needed
31+
32+
## File Structure
33+
```
34+
example_code/{service}/
35+
├── Hello{Service}.php # Hello example file
36+
```
37+
38+
## Hello Scenario File Pattern
39+
**MANDATORY standalone hello file:**
40+
41+
```php
42+
<?php
43+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
44+
// SPDX-License-Identifier: Apache-2.0
45+
46+
require 'vendor/autoload.php';
47+
48+
use Aws\{Service}\{Service}Client;
49+
use Aws\Exception\AwsException;
50+
51+
echo "Hello {AWS Service}!\n";
52+
53+
try {
54+
$client = new {Service}Client([
55+
'region' => 'us-east-1',
56+
'version' => 'latest'
57+
]);
58+
59+
// Simple service operation
60+
$result = $client->someBasicOperation();
61+
echo "Successfully connected to {AWS Service}\n";
62+
// Display basic result
63+
64+
} catch (AwsException $e) {
65+
echo "Error: " . $e->getMessage() . "\n";
66+
}
67+
```
68+
69+
## Hello Examples by Service Type
70+
71+
### List-Based Services (S3, DynamoDB, etc.)
72+
- **Operation**: List primary resources (buckets, tables, etc.)
73+
- **Message**: Show count and names of resources
74+
75+
### Status-Based Services (GuardDuty, Config, etc.)
76+
- **Operation**: Check service status or list detectors/configurations
77+
- **Message**: Show service availability and basic status
78+
79+
### Compute Services (EC2, Lambda, etc.)
80+
- **Operation**: List instances/functions or describe regions
81+
- **Message**: Show available resources or regions
82+
83+
## Validation Requirements
84+
- ✅ **Must run without errors** (with proper credentials)
85+
- ✅ **Must handle credential issues gracefully**
86+
- ✅ **Must display meaningful output**
87+
- ✅ **Must use direct AWS SDK for PHP client calls**
88+
- ✅ **Must include proper copyright header**
89+
90+
## Common Patterns
91+
- Always use `new {Service}Client()` directly
92+
- Include comprehensive error handling with try-catch blocks
93+
- Provide user-friendly output messages using echo
94+
- Handle both service-specific and general exceptions
95+
- Keep it as simple as possible - no additional classes or complexity
96+
- Use appropriate AWS SDK for PHP v3 patterns

0 commit comments

Comments
 (0)