Core Laravel Package

Getting Started

Start by installing the package with composer require "apimatic/core" — it’s a dependency for APIMatic-generated PHP SDKs but can be used directly for building robust HTTP clients. First, familiarize yourself with the core classes: RequestBuilder and Request for assembling requests, and ResponseHandler for managing responses and deserialization. A minimal workflow is:

use Apimatic\Core\Request\RequestBuilder;
use Apimatic\Core\Language\Http\Method;

$request = (new RequestBuilder())
    ->method(Method::GET)
    ->url('https://api.example.com/users')
    ->header('Authorization', 'Bearer token')
    ->build();

For response handling, chain a ResponseHandler to parse and validate the result:

use Apimatic\Core\Response\ResponseHandler;

$handler = new ResponseHandler($response);
$result = $handler->handle(); // Deserializes based on expected type

Review the README’s tables for parameter classes (QueryParam, FormParam, BodyParam, etc.) to attach typed parameters.

Implementation Patterns

Leverage the parameter classes to dynamically construct requests in a type-safe way, especially in Laravel services where API interactions are common. For example:

public function fetchUser(int $id)
{
    $query = new QueryParam('id', $id);
    $header = new HeaderParam('X-API-Key', config('services.api.key'));

    $request = (new RequestBuilder())
        ->method(Method::GET)
        ->url('https://api.example.com/users/:id')
        ->templateParam(new TemplateParam('id', $id))
        ->queryParam($query)
        ->headerParam($header)
        ->build();

    return $this->httpClient->send($request)->handle();
}

Use Additional*Params wrappers to append optional or context-aware parameters without reconstructing the core parameter lists — handy in middleware or OAuth flows. For testing, extend CoreTestCase and use matchers like KeysAndValuesBodyMatcher to assert against payloads:

public function testUserCreation()
{
    $this->assertRequestContains([
        'body' => $this->bodyContainsKeys(['name', 'email']),
        'status' => $this->statusCode(201),
    ]);
}

For production logging, inject ApiLogger with custom LoggingConfiguration — including NON_SENSITIVE_HEADERS exclusions — to automatically redact secrets in logs without cluttering business logic.

Gotchas and Tips

• Template params vs query/path params: Template params (used in URL interpolation like :id) must be set via templateParam(), while path segments like users/1 are not handled — always use URL templates + template params together.
• Nullable types: As of 0.3.11, null is supported in ResponseType, but deserialization fails silently if null is not explicitly declared — ensure models like ?User or ResponseMultiType with null branches are correctly defined.
• Auth validation gotcha: In 0.3.10, repetitive validation for auth params was added; avoid reusing the same HeaderParam instance across requests if params must mutate per call — clone or recreate instances.
• Logging redaction: Define NON_SENSITIVE_HEADERS carefully in your RequestConfiguration; even common headers like X-Forwarded-For can leak sensitive data if misconfigured.
• Testing edge case: RawBodyMatcher performs strict string comparison — avoid using it for JSON when order matters (e.g., associative arrays). Prefer KeysAndValuesBodyMatcher for robustness.
• Future-proofing: The package supports up to PHP 8.4 (as of 0.3.12), but Always pin to stable minor versions — the release notes show frequent BC breaks in dev (e.g., 0.3.x), so use ^0.3 cautiously and test upgrades thoroughly.