Skip to content

Commit 77f8947

Browse files
GrazulexGrazulex
authored
Merge pull request #40 from Grazulex/copilot/fix-39
🔄 Complete documentation and examples update for production readiness
2 parents f1a9810 + 8be5f21 commit 77f8947

File tree

7 files changed

+337
-8
lines changed

7 files changed

+337
-8
lines changed

‎README.md‎

Lines changed: 137 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,45 @@ $result = Flowpipe::make()
8282
// Result: "HELLO-WORLD!"
8383
```
8484

85+
### <span style="color: #88C600;">🎯 Factory Methods</span>
86+
87+
**<span style="color: #D2D200;">Laravel Flowpipe</span>** provides convenient factory methods for creating instances with specific tracers:
88+
89+
```php
90+
use Grazulex\LaravelFlowpipe\Flowpipe;
91+
92+
// Create with debug tracing (logs to file or console)
93+
$debugFlow = Flowpipe::debug(true, 'flowpipe'); // logToFile=true, channel='flowpipe'
94+
$result = $debugFlow
95+
->send($data)
96+
->through($steps)
97+
->thenReturn();
98+
99+
// Create with performance tracing
100+
$perfFlow = Flowpipe::performance();
101+
$result = $perfFlow
102+
->send($data)
103+
->through($steps)
104+
->thenReturn();
105+
106+
// Create with database tracing
107+
$dbFlow = Flowpipe::database('custom_traces_table');
108+
$result = $dbFlow
109+
->send($data)
110+
->through($steps)
111+
->thenReturn();
112+
113+
// Create with test tracing (for unit tests)
114+
$testFlow = Flowpipe::test();
115+
$result = $testFlow
116+
->send($data)
117+
->through($steps)
118+
->thenReturn();
119+
120+
// Standard make method (no tracing by default)
121+
$flow = Flowpipe::make(); // or Flowpipe::make($customTracer)
122+
```
123+
85124
### <span style="color: #D2D200;">🛡️ Error Handling with Retry</span>
86125

87126
```php
@@ -508,6 +547,82 @@ $result = Flowpipe::make()
508547
->thenReturn();
509548
```
510549

550+
### <span style="color: #88C600;">🔧 Built-in Step Types</span>
551+
552+
**<span style="color: #00B470;">Laravel Flowpipe</span>** includes various specialized step types for common operations:
553+
554+
```php
555+
use Grazulex\LaravelFlowpipe\Flowpipe;
556+
557+
// Cache step - cache expensive operations
558+
$result = Flowpipe::make()
559+
->send($userData)
560+
->cache('user_profile_' . $userData['id'], 3600) // Cache for 1 hour
561+
->through([
562+
fn($data, $next) => $next(fetchUserProfile($data)),
563+
])
564+
->thenReturn();
565+
566+
// Transform step - transform data structure
567+
$result = Flowpipe::make()
568+
->send($rawData)
569+
->transform(function ($data) {
570+
return [
571+
'name' => strtoupper($data['name']),
572+
'email' => strtolower($data['email']),
573+
'created_at' => now(),
574+
];
575+
})
576+
->through([
577+
fn($data, $next) => $next(saveUser($data)),
578+
])
579+
->thenReturn();
580+
581+
// Validation step - validate data using Laravel validation
582+
$result = Flowpipe::make()
583+
->send($inputData)
584+
->validate([
585+
'name' => 'required|string|max:255',
586+
'email' => 'required|email|unique:users',
587+
'age' => 'required|integer|min:18',
588+
])
589+
->through([
590+
fn($data, $next) => $next(processValidData($data)),
591+
])
592+
->thenReturn();
593+
594+
// Batch step - process data in batches
595+
$result = Flowpipe::make()
596+
->send($largeDataset)
597+
->batch(100) // Process 100 items at a time
598+
->through([
599+
fn($batch, $next) => $next(processBatch($batch)),
600+
])
601+
->thenReturn();
602+
603+
// Rate limiting step - prevent API abuse
604+
$result = Flowpipe::make()
605+
->send($apiRequest)
606+
->rateLimit('api_calls', 60, 1) // 60 calls per minute
607+
->through([
608+
fn($data, $next) => $next(callExternalAPI($data)),
609+
])
610+
->thenReturn();
611+
612+
// Combine multiple step types
613+
$result = Flowpipe::make()
614+
->send($complexData)
615+
->validate(['data' => 'required|array'])
616+
->transform(fn($data) => ['processed' => $data['data']])
617+
->cache('complex_operation', 1800)
618+
->batch(50)
619+
->rateLimit('processing', 30, 1)
620+
->through([
621+
fn($data, $next) => $next(performComplexOperation($data)),
622+
])
623+
->thenReturn();
624+
```
625+
511626
### <span style="color: #00B470;">Error Handling in Production Workflows</span>
512627

513628
```php
@@ -624,6 +739,19 @@ public function test_user_processing_flow()
624739
$this->assertEquals('JOHN', $result);
625740
$this->assertCount(1, $tracer->count());
626741
}
742+
743+
// Or use the factory method for cleaner tests:
744+
public function test_user_processing_flow_with_factory()
745+
{
746+
$result = Flowpipe::test()
747+
->send(['name' => 'John'])
748+
->through([
749+
fn($data, $next) => $next(strtoupper($data['name'])),
750+
])
751+
->thenReturn();
752+
753+
$this->assertEquals('JOHN', $result);
754+
}
627755
```
628756

629757
## <span style="color: #88C600;">⚡ Performance</span>
@@ -668,10 +796,15 @@ public function test_user_processing_flow()
668796

669797
### <span style="color: #88C600;">Static Methods</span>
670798

671-
- **<span style="color: #FF9900;">`group(string $name, array $steps)`</span>** - Define a reusable step group
672-
- **<span style="color: #D2D200;">`hasGroup(string $name)`</span>** - Check if a group exists
673-
- **<span style="color: #88C600;">`getGroups()`</span>** - Get all registered groups
674-
- **<span style="color: #00B470;">`clearGroups()`</span>** - Clear all registered groups (useful for testing)
799+
- **<span style="color: #FF9900;">`make(?Tracer $tracer = null)`</span>** - Create a new flowpipe instance
800+
- **<span style="color: #D2D200;">`debug(bool $logToFile = false, string $logChannel = 'default')`</span>** - Create instance with debug tracer
801+
- **<span style="color: #88C600;">`performance()`</span>** - Create instance with performance tracer
802+
- **<span style="color: #00B470;">`database(string $tableName = 'flowpipe_traces')`</span>** - Create instance with database tracer
803+
- **<span style="color: #FF9900;">`test()`</span>** - Create instance with test tracer (for testing)
804+
- **<span style="color: #D2D200;">`group(string $name, array $steps)`</span>** - Define a reusable step group
805+
- **<span style="color: #88C600;">`hasGroup(string $name)`</span>** - Check if a group exists
806+
- **<span style="color: #00B470;">`getGroups()`</span>** - Get all registered groups
807+
- **<span style="color: #FF9900;">`clearGroups()`</span>** - Clear all registered groups (useful for testing)
675808

676809
### <span style="color: #00B470;">Conditional Steps</span>
677810

‎examples/README.md‎

Lines changed: 45 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -222,23 +222,64 @@ php artisan flowpipe:export user-registration --format=md --output=docs/user-reg
222222

223223
## Step Groups
224224

225-
The examples demonstrate three types of reusable step groups:
225+
The examples demonstrate multiple types of reusable step groups organized by functionality:
226226

227-
### User Validation Group (`groups/user-validation.yaml`)
227+
### User-Related Groups
228+
229+
#### User Validation Group (`groups/user-validation.yaml`)
228230
- Email format validation
229231
- Password strength checking
230232
- Required field validation
231233
- User existence checking
232234
- Terms acceptance validation
233235

234-
### Order Processing Group (`groups/order-processing.yaml`)
236+
#### User Setup Group (`groups/user-setup.yaml`)
237+
- User ID generation
238+
- Password hashing
239+
- Profile creation
240+
- Default preferences setup
241+
- API key generation
242+
243+
#### User Notifications Group (`groups/user-notifications.yaml`)
244+
- Welcome email sending
245+
- Email verification dispatch
246+
- Admin notifications
247+
- Registration event logging
248+
- User statistics updates
249+
250+
### E-commerce Groups
251+
252+
#### Order Validation Group (`groups/order-validation.yaml`)
253+
- Order structure validation
254+
- Customer information validation
255+
- Item and quantity validation
256+
- Order total verification
257+
- Business rules checking
258+
259+
#### Inventory Management Group (`groups/inventory-management.yaml`)
260+
- Item availability checking
261+
- Inventory reservation
262+
- Shipping cost calculation
263+
- Inventory level updates
264+
- Inventory reporting
265+
266+
#### Order Notifications Group (`groups/order-notifications.yaml`)
267+
- Order confirmation emails
268+
- SMS notifications
269+
- Customer account updates
270+
- Warehouse notifications
271+
- Notification event logging
272+
273+
### General Processing Groups
274+
275+
#### Order Processing Group (`groups/order-processing.yaml`)
235276
- Order data validation
236277
- Inventory checking and reservation
237278
- Payment processing
238279
- Order record creation
239280
- Confirmation generation
240281

241-
### Notifications Group (`groups/notifications.yaml`)
282+
#### Notifications Group (`groups/notifications.yaml`)
242283
- Welcome email sending
243284
- Verification email dispatch
244285
- SMS notifications

‎examples/groups/inventory-management.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Example: Inventory Management Group
2+
# File: groups/inventory-management.yaml
3+
4+
group: inventory-management
5+
description: Manage inventory for e-commerce orders
6+
7+
steps:
8+
# Check item availability
9+
- type: closure
10+
action: check_item_availability
11+
description: Check if all items are available in requested quantities
12+
13+
# Reserve inventory items
14+
- type: closure
15+
action: reserve_items
16+
description: Reserve items for this order
17+
18+
# Calculate shipping costs
19+
- type: closure
20+
action: calculate_shipping
21+
description: Calculate shipping costs based on items and location
22+
23+
# Update inventory levels
24+
- type: closure
25+
action: update_inventory_levels
26+
description: Update inventory levels after reservation
27+
28+
# Generate inventory report
29+
- type: closure
30+
action: generate_inventory_report
31+
description: Generate inventory status report for this order

‎examples/groups/order-notifications.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Example: Order Notifications Group
2+
# File: groups/order-notifications.yaml
3+
4+
group: order-notifications
5+
description: Send notifications for e-commerce orders
6+
7+
steps:
8+
# Send order confirmation email
9+
- type: closure
10+
action: send_order_confirmation
11+
description: Send order confirmation email to customer
12+
13+
# Send SMS notification
14+
- type: closure
15+
action: send_sms_notification
16+
description: Send SMS notification if customer opted in
17+
18+
# Update customer account
19+
- type: closure
20+
action: update_customer_account
21+
description: Update customer's order history
22+
23+
# Notify warehouse
24+
- type: closure
25+
action: notify_warehouse
26+
description: Notify warehouse team about new order
27+
28+
# Log notification events
29+
- type: closure
30+
action: log_notifications
31+
description: Log all notification events for auditing

‎examples/groups/order-validation.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Example: Order Validation Group
2+
# File: groups/order-validation.yaml
3+
4+
group: order-validation
5+
description: Validate e-commerce order data and requirements
6+
7+
steps:
8+
# Validate order structure
9+
- type: closure
10+
action: validate_order_structure
11+
description: Ensure order contains required fields
12+
13+
# Validate customer information
14+
- type: closure
15+
action: validate_customer_info
16+
description: Validate customer name, email, and address
17+
18+
# Validate items and quantities
19+
- type: closure
20+
action: validate_items
21+
description: Validate item names, prices, and quantities
22+
23+
# Calculate and verify total
24+
- type: closure
25+
action: verify_order_total
26+
description: Calculate total and verify against provided total
27+
28+
# Check business rules
29+
- type: closure
30+
action: check_business_rules
31+
description: Apply business rules (minimum order, restrictions, etc.)

‎examples/groups/user-notifications.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Example: User Notifications Group
2+
# File: groups/user-notifications.yaml
3+
4+
group: user-notifications
5+
description: Send notifications for new user registration
6+
7+
steps:
8+
# Send welcome email
9+
- type: closure
10+
action: send_welcome_email
11+
description: Send welcome email with account details
12+
13+
# Send verification email
14+
- type: closure
15+
action: send_verification_email
16+
description: Send email verification link
17+
18+
# Send admin notification
19+
- type: closure
20+
action: notify_admin
21+
description: Notify administrators about new user registration
22+
23+
# Log registration event
24+
- type: closure
25+
action: log_registration
26+
description: Log user registration event for analytics
27+
28+
# Update user stats
29+
- type: closure
30+
action: update_user_stats
31+
description: Update application user statistics

0 commit comments

Comments
 (0)