Core Interfaces Laravel Package

Getting Started

This package is an interface library for APIMatic’s PHP SDK ecosystem—not a standalone tool. Start by:

1. Installing it via composer require apimatic/core-interfaces to gain type contracts (no executable code).
2. Using it indirectly when working with APIMatic-generated SDKs (e.g., apimatic/core or custom SDKs).
3. Your first real task: If generating or extending an APIMatic-based SDK, implement the required interfaces (e.g., HttpClientInterface for custom HTTP clients or AuthInterface for new auth strategies).

Implementation Patterns

• SDK Extensibility: Implement HttpClientInterface to inject custom HTTP clients (e.g., Symfony HttpClient, Laravel’s Http client wrapper) into APIMatic SDKs without forking the core library.
• Authentication Swapping: Use AuthInterface to support OAuth, API keys, or JWT—swap implementations (e.g., ApiKeyAuth, BearerTokenAuth) via DI without touching SDK core.
• Structured Request Building: Leverage RequestInterface/RequestSetterInterface to inspect/manipulate requests (e.g., inject tracing IDs or rate-limit headers) before execution.
• Logging Interception: Implement ApiLoggerInterface to log requests/responses with context (e.g., correlation IDs, latency), ideal for debugging production integrations.
• Validation at the Edge: Chain ParamInterface → NonEmptyParamInterface → TypeValidatorInterface to enforce strict validation rules in SDK request builders (e.g., prevent empty strings in required path parameters).

Gotchas and Tips

• Interface-only: No classes to instantiate—this is pure abstraction. You’ll get fatal errors if implementations are missing required methods.
• PHP Version Compliance: Though it supports PHP 7.2–8.2, avoid native types in your implementations if targeting legacy PHP (use @return docblocks as in v0.1.3’s mixed fix).
• Enum Compatibility: AuthGroup and RequestMethod are classical enums (not BackedEnum), so avoid PHP 8.1+ enum methods like from() or cases().
• Break Glass with ContextInterface: When troubleshooting flaky API calls, dump ContextInterface—it persists the final request/response pair for post-mortem analysis.
• Version Lock: Pin ^0.1 in composer.json. Though low-dependency (0 dependents), versions must align with apimatic/core and SDKs—mismatched versions cause interface mismatch crashes.
• Debugging Silent Failures: Enable ApiLoggerInterface first—many issues (e.g., 401s, misconfigured base URLs) are visible in logged request headers/body without stepping into HTTP clients.