Fix PHP code examples in OpenAPI specifications #3
Conversation
WalkthroughRefactors PHP OpenAPI samples to use environment-driven configuration, introduces DTO-based request payloads and a MailtrapGeneralClient::contacts(accountId) account-scoped entrypoint, adds ResponseHelper for standardized response output, and updates many sample flows across contacts, email, general, and sandbox specs. Changes
Sequence Diagram(s)mermaid Dev->>Client: new MailtrapGeneralClient(Config($_ENV['MAILTRAP_API_KEY'])) Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: defaults Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🔇 Additional comments (5)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
specs/contacts.openapi.ymlspecs/email-api.openapi.ymlspecs/email-batch.openapi.ymlspecs/email-sending-bulk.openapi.ymlspecs/email-sending-transactional.openapi.ymlspecs/general.openapi.ymlspecs/sandbox.openapi.yml
🔇 Additional comments (44)
specs/email-sending-bulk.openapi.yml (2)
78-78: LGTM! ResponseHelper import added correctly.The import follows PHP conventions and aligns with the PR objective to standardize response handling across PHP examples.
97-97: LGTM! Standardized response output added.Using
ResponseHelper::toArray()provides consistent diagnostic output across all PHP examples.specs/email-sending-transactional.openapi.yml (2)
77-77: LGTM! ResponseHelper import added correctly.Consistent with the standardization across PHP examples in this PR.
94-94: LGTM! Response formatting consistent with PR pattern.specs/email-batch.openapi.yml (3)
96-96: LGTM! ResponseHelper import added.
107-114: LGTM! Enhanced Address usage with display names.Adding display names to the
Addressobjects makes the example more complete and demonstrates proper usage of the SymfonyAddressclass constructor.
117-118: LGTM! Standardized response output.specs/general.openapi.yml (6)
115-124: LGTM! Environment-driven configuration with general client pattern.The refactored example correctly:
- Uses environment variables for API key
- Initializes
MailtrapGeneralClientfor account operations- Uses
ResponseHelperfor standardized output
240-250: LGTM! Account-scoped user management with environment variables.The example properly demonstrates:
- Account ID from environment
- Account-scoped users() method
- Standardized response formatting
344-354: LGTM! Delete operation with appropriate status code output.The example correctly:
- Uses environment variables for resource IDs
- Performs delete operation via users client
- Outputs status code (appropriate for delete operations)
432-461: LGTM! Excellent DTO-based permissions management.This is a significant improvement that demonstrates:
- Proper DTO usage (
CreateOrUpdatePermission,DestroyPermission,Permissions)- Type-safe permission constants from
PermissionInterface- Environment-driven resource IDs
- Clear separation between create/update and destroy operations
The example now provides a much better reference for SDK users.
584-594: LGTM! Consistent resource listing pattern.
696-706: LGTM! Billing API usage follows established pattern.specs/email-api.openapi.yml (12)
78-90: LGTM! Environment-driven sending domain creation.
224-236: LGTM! Sending domains listing with environment configuration.
341-354: LGTM! Domain retrieval by ID with environment variables.
463-471: LGTM! Delete operation with status code output.
583-596: LGTM! Setup instructions sending with environment variables.
750-767: LGTM! Suppressions listing with optional search parameter.The example demonstrates both usage patterns:
- Getting all suppressions
- Filtering by specific email
911-919: LGTM! Suppression deletion with status code output.
1017-1030: LGTM! Email templates listing via general client.Correctly uses
MailtrapGeneralClientfor account-level email template operations.
1100-1122: LGTM! Excellent DTO usage for email template creation.The example demonstrates proper DTO pattern with
EmailTemplate::init(), which is much clearer and more type-safe than plain arrays. This provides:
- Clear parameter names and order
- Type safety
- Better IDE support
1226-1242: LGTM! Template retrieval with environment-driven ID.
1274-1300: LGTM! Template update with DTO pattern.Correctly demonstrates using
EmailTemplate::init()for update operations with all template fields.
1346-1361: LGTM! Template deletion with status code output.specs/contacts.openapi.yml (19)
127-145: LGTM!The PHP code sample correctly demonstrates the updated SDK patterns: environment-based configuration, DTO-based payload via
CreateContact::init(), and proper response handling withResponseHelper::toArray().
319-334: LGTM!The sample correctly demonstrates both
getContactByIdandgetContactByEmailmethods, providing clear examples for both retrieval patterns.
458-488: LGTM!Comprehensive example showing both
updateContactByIdandupdateContactByEmailwith the fullUpdateContact::init()signature including list management and unsubscribe flag.
586-597: LGTM!Appropriately uses
$response->getStatusCode()for the delete operation instead ofResponseHelper::toArray(), since DELETE returns 204 No Content with no body.
667-687: LGTM!The sample demonstrates
CreateContactEvent::init()with a variety of parameter types (integer, string, boolean, null), which aligns with the schema definition.
779-794: LGTM!Clear demonstration of
ContactExportFilter::init()with multiple filter types for export operations.
885-894: LGTM!Consistent pattern using environment variable for the export ID.
984-1007: LGTM!The sample uses PHP 8+ named arguments syntax for
ImportContact, which improves readability. The example demonstrates importing multiple contacts with fields and list management.
1107-1116: LGTM!Consistent pattern for retrieving import status.
1195-1207: LGTM!Good addition of try-catch block demonstrating error handling. The
getAllContactLists()method name aligns with the SDK conventions mentioned in the PR.
1278-1290: LGTM!Consistent pattern with try-catch error handling for list creation.
1369-1378: LGTM!Consistent pattern for retrieving a specific contact list.
1442-1451: LGTM!Consistent pattern for updating a contact list.
1529-1536: LGTM!Appropriately uses status code output for the delete operation, consistent with other delete samples.
1601-1608: LGTM!Consistent pattern for retrieving all contact fields.
1689-1696: LGTM!Correctly demonstrates
createContactFieldwith name, data_type, and merge_tag parameters.
1807-1815: LGTM!Consistent pattern for retrieving a specific contact field.
1883-1891: LGTM!Correctly demonstrates
updateContactFieldwith name and merge_tag parameters (data_type is not updatable per the API specification).
1991-1998: LGTM!Consistent pattern with other delete operations, using status code output.
yanchuk
requested review from
VladimirTaytor,
leonid-shevtsov,
mklocek and
yanchuk
2 participants
This PR fixes all PHP code examples across OpenAPI specification files to match the actual mailtrap-php SDK implementation. The examples were outdated and didn't reflect the correct SDK usage, which could confuse developers using the API documentation.
Motivation
The PHP code examples in the OpenAPI specs (specs/*.openapi.yml) were inconsistent with the official PHP SDK examples found in the mailtrap-php repository. This caused:
Key Improvements:
Added Missing Imports
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;
use Mailtrap\MailtrapGeneralClient;
use Mailtrap\Config;
use Mailtrap\Mime\MailtrapEmail;
use Symfony\Component\Mime\Address;
// + DTOs for requests
Fixed Client Initialization
// Before (missing)
$response = $mailtrap->send($email);
// After (with proper response handling)
$response = $mailtrap->send($email);
var_dump(ResponseHelper::toArray($response));
// Before (plain arrays)
$client->create(['email' => 'test@example.com', 'fields' => [...]])
// After (proper DTOs)
$contacts->createContact(
CreateContact::init(
'test@example.com',
['first_name' => 'John'],
[1, 2, 3]
)
);
Testing
All examples were verified against the reference implementations in:
Reference
Based on the official mailtrap-php SDK examples:
Impact
✅ Documentation examples now match actual SDK usage
✅ Developers can copy-paste examples and they will work correctly
✅ Consistent code style across all PHP examples
✅ Proper error handling and response processing demonstrated
Note: This PR only updates PHP code examples in OpenAPI specs. No API functionality or SDK code was changed.
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.