ApiClient e ApiRequest · PHP MVC Framework

Construtor e verbos

$client = new ApiClient(
    'https://viacep.com.br/ws',
    defaultTimeout: 10
);
$response = $client->get('/01001000/json', ['throw_on_error' => false]);
if ($response['ok']) {
    $city = $response['json']['localidade'] ?? null;
}

Assinatura: __construct(string $baseUri='', array $defaultHeaders=[], int $defaultTimeout=30). Verbos: get, post, put, patch, delete. Requer extensão cURL.

Opções do request

Chave	Tipo	Uso
`headers`	array	Mesclados com headers padrão e da instância.
`query`	array	Query string.
`json`	array	Corpo JSON/Content-Type.
`form`	array	Form URL-encoded.
`token`	string	Bearer token.
`basic_auth`	[user,pass]	Basic auth.
`timeout`	int	Sobrepõe timeout padrão.
`throw_on_error`	bool	Default true; false retorna falha/status no array.

Retorno e exceções

Array de resposta contém status, headers, body, json (array ou null) e ok. Erro de conexão ou status fora de 2xx lança ApiException se throw_on_error estiver ativo. Métodos da exceção: statusCode(), responseBody(), responseJson(), isConnectionError(). Logs registram metadados sem headers/corpo que poderiam conter credenciais.

ApiRequest

Builder imutável: withPath(), withHeader(s), withQuery(), withJson(), withFormBody(), withBody(), withBearerToken(), withBasicAuth(), withTimeout(). ApiClient::send(ApiRequest $req, bool $throwOnError=true) executa request já montado.

Intermediário · falha tipada ou resultado inspecionável

Por padrão, resposta fora de 2xx e erro de conexão lançam ApiException. Capture a exceção junto à integração/Service: statusCode() diferencia HTTP, isConnectionError() identifica transporte, e responseJson()/responseBody() ajudam a interpretar sem expor credenciais ao cliente.

try {
    $response = $client->get('/01001000/json');
    $city = $response['json']['localidade'] ?? null;
} catch (\Framework\Http\Api\ApiException $e) {
    if ($e->isConnectionError()) {
        // falha de rede (status 0)
    } else {
        $status = $e->statusCode();
    }
}

Se definir `throw_on_error => false`, a chamada devolve o array de resposta mesmo em falha: `ok=false`, status HTTP (ou 0 para conexão), headers, body e json null/array. Escolha uma estratégia por chamada e sempre verifique `ok` nessa modalidade.

ApiRequest é descrição imutável, ApiClient executa

Use ApiRequest quando precisar construir uma base e derivar variações. Cada `with*()` retorna nova instância. A execução continua pertencendo ao ApiClient::send(); o builder não chama a rede por conta própria.

$base = (new \Framework\Http\Api\ApiRequest('GET', 'https://api.exemplo.com'))
    ->withBearerToken($token)
    ->withTimeout(10);

$request = $base->withPath('/users')->withQuery(['page' => 2]);
$response = $client->send($request);

A extensão cURL é necessária. O ApiClient registra método/URL/status/duração, mas deliberadamente não registra headers nem corpo bruto, que podem conter credenciais. Não coloque tokens em URLs nem logs de aplicação.