FacturaScripts

Http
in package

Cliente HTTP minimalista basado en cURL con API fluida.

Se usa siempre a través de los factories estáticos Http::get(), Http::post(), Http::put(), Http::patch(), Http::delete() o Http::postJson(). La petición se construye de forma encadenable (setHeader(), setBearerToken(), setTimeout(), ...) y se ejecuta de manera perezosa: la primera llamada a un getter (body(), status(), headers(), json(), ...) dispara exec() y cachea el resultado en la propia instancia. Llamar a getters posteriores no lanza una nueva petición.

Notas relevantes:

  • Por defecto sigue redirecciones (CURLOPT_FOLLOWLOCATION) y timeout de 30 segundos.
  • Las cabeceras de respuesta se almacenan en minúsculas para que header() sea case-insensitive.
  • getPostFields() respeta el Content-Type: si es multipart/form-data se envía el array tal cual (cURL construye el body multipart); en otro caso se serializa con http_build_query.
  • ok() solo considera 200/201/202 como éxito; el resto (incluido 204 No Content) cuentan como fallo. Si necesitas otra interpretación, usa status() directamente.

Table of Contents

Properties

$error  : string
$body  : string
$data  : mixed
$method  : string
$url  : string
$curlOptions  : array<string|int, mixed>
$executed  : bool
$headers  : array<string|int, mixed>
$responseHeaders  : array<string|int, mixed>
$statusCode  : int

Methods

__construct()  : mixed
Construye una petición. Pensado para uso interno: en el código cliente, prefiérense los factories estáticos (`Http::get()`, `Http::post()`, ...) que dejan el método explícito.
body()  : string
Devuelve el cuerpo crudo de la respuesta, ejecutando la petición si aún no se había hecho.
delete()  : self
Crea una petición DELETE. Si `$data` es array, sus claves se añaden como query string en la URL (DELETE no lleva cuerpo). Si es string, se envía la URL tal cual y se ignora el dato.
errorMessage()  : string
Devuelve el mensaje de error de cURL (cadena vacía si no hubo error). Ejecuta la petición si hace falta.
failed()  : bool
Atajo de `!ok()`: true si la petición no terminó con un código 200/201/202.
get()  : self
Crea una petición GET. Si `$data` es un array no vacío, se concatena como query string a la URL al ejecutar la petición.
header()  : string
Devuelve el primer valor de la cabecera de respuesta `$key` (case-insensitive), o cadena vacía si no existe.
headers()  : array<string|int, mixed>
Devuelve todas las cabeceras de respuesta indexadas en minúsculas.
json()  : mixed
Decodifica el cuerpo de la respuesta como JSON.
notFound()  : bool
True si la respuesta tiene código 404. Ejecuta la petición si aún no se había ejecutado.
ok()  : bool
True si la respuesta tiene código 200, 201 o 202.
patch()  : self
Crea una petición PATCH; el cuerpo se construye igual que en POST.
post()  : self
Crea una petición POST. Si `$data` es array, se enviará como `application/x-www-form-urlencoded` salvo que se establezca un Content-Type distinto (multipart/form-data envía el array tal cual).
postJson()  : self
Atajo para POST con cuerpo JSON: serializa `$data` y fija la cabecera `Content-Type: application/json`.
put()  : self
Crea una petición PUT; el cuerpo se construye igual que en POST.
saveAs()  : bool
Guarda el cuerpo de la respuesta en `$filename`.
setBearerToken()  : self
Añade una cabecera `Authorization: Bearer <token>` para autenticación OAuth/JWT.
setCurlOption()  : self
Sobrescribe directamente una opción de cURL (constante `CURLOPT_*`). Usar con cuidado.
setHeader()  : self
Define una cabecera de la petición.
setHeaders()  : self
Sustituye por completo el conjunto de cabeceras de la petición.
setTimeout()  : self
Establece el timeout total de la petición en segundos (atajo de `CURLOPT_TIMEOUT`).
setToken()  : self
Añade una cabecera `Token: <token>` (autenticación específica de algunas APIs internas).
setUser()  : self
Configura autenticación HTTP Basic mediante `CURLOPT_USERPWD`.
setUserAgent()  : self
Sustituye el User-Agent por defecto (que es `FacturaScripts <version>`).
status()  : int
Devuelve el código HTTP de la respuesta. Ejecuta la petición si aún no se había hecho.
exec()  : void
Ejecuta la petición cURL y rellena `body`, `statusCode`, `error` y `responseHeaders`.
getPostFields()  : mixed
Prepara el cuerpo a enviar para POST/PUT/PATCH según el Content-Type configurado.

Properties

$error

public string $error

Mensaje de error devuelto por curl_error(), vacío si no hubo fallo a nivel de transporte.

$body

protected string $body

Cuerpo crudo de la respuesta tras exec().

$data

protected mixed $data

Datos a enviar: array (se codifica según método y Content-Type) o string en bruto.

$method

protected string $method

Método HTTP de la petición (GET, POST, PUT, PATCH, DELETE).

$url

protected string $url

URL destino. Para GET/DELETE con $data array, los parámetros se añaden como query string al ejecutar.

$curlOptions

private array<string|int, mixed> $curlOptions

Mapa de opciones cURL que se aplicarán a la petición.

$executed

private bool $executed = false

Indica si la petición ya se ha ejecutado, para evitar dispararla varias veces.

$headers

private array<string|int, mixed> $headers = []

Cabeceras de la petición saliente, ya formateadas como "Clave: Valor".

$responseHeaders

private array<string|int, mixed> $responseHeaders = []

Cabeceras de respuesta indexadas en minúsculas, cada una con sus valores como array.

$statusCode

private int $statusCode = 0

Código HTTP de respuesta. 0 mientras no se haya ejecutado la petición.

Methods

__construct()

Construye una petición. Pensado para uso interno: en el código cliente, prefiérense los factories estáticos (`Http::get()`, `Http::post()`, ...) que dejan el método explícito.

public __construct(string $method, string $url[, mixed $data = [] ]) : mixed
Parameters
$method : string

método HTTP en mayúsculas

$url : string

URL destino

$data : mixed = []

array de campos o string en bruto a enviar

body()

Devuelve el cuerpo crudo de la respuesta, ejecutando la petición si aún no se había hecho.

public body() : string
Return values
string

delete()

Crea una petición DELETE. Si `$data` es array, sus claves se añaden como query string en la URL (DELETE no lleva cuerpo). Si es string, se envía la URL tal cual y se ignora el dato.

public static delete(string $url[, mixed $data = [] ]) : self
Parameters
$url : string
$data : mixed = []
Return values
self

errorMessage()

Devuelve el mensaje de error de cURL (cadena vacía si no hubo error). Ejecuta la petición si hace falta.

public errorMessage() : string
Return values
string

failed()

Atajo de `!ok()`: true si la petición no terminó con un código 200/201/202.

public failed() : bool
Return values
bool

get()

Crea una petición GET. Si `$data` es un array no vacío, se concatena como query string a la URL al ejecutar la petición.

public static get(string $url[, mixed $data = [] ]) : self
Parameters
$url : string
$data : mixed = []
Return values
self

header()

Devuelve el primer valor de la cabecera de respuesta `$key` (case-insensitive), o cadena vacía si no existe.

public header(string $key) : string

Si la cabecera apareció varias veces, se devuelve solo la primera ocurrencia. Para obtenerlas todas, usar headers().

Parameters
$key : string
Return values
string

headers()

Devuelve todas las cabeceras de respuesta indexadas en minúsculas.

public headers() : array<string|int, mixed>

Cada clave apunta a un array con todos los valores recibidos para esa cabecera (las que aparecen una sola vez se devuelven igualmente como array de un elemento).

Return values
array<string|int, mixed>

json()

Decodifica el cuerpo de la respuesta como JSON.

public json([bool $associative = true ]) : mixed

Si el cuerpo no es JSON válido, json_decode devuelve null sin lanzar excepción; el llamador es responsable de comprobar el resultado.

Parameters
$associative : bool = true

true (por defecto) para arrays asociativos, false para objetos

notFound()

True si la respuesta tiene código 404. Ejecuta la petición si aún no se había ejecutado.

public notFound() : bool
Return values
bool

ok()

True si la respuesta tiene código 200, 201 o 202.

public ok() : bool

Otros 2xx (204 No Content, 206 Partial Content...) y todos los 3xx/4xx/5xx se consideran fallo. Si tu integración necesita una interpretación distinta, usa status() directamente.

Return values
bool

patch()

Crea una petición PATCH; el cuerpo se construye igual que en POST.

public static patch(string $url[, mixed $data = [] ]) : self
Parameters
$url : string
$data : mixed = []
Return values
self

post()

Crea una petición POST. Si `$data` es array, se enviará como `application/x-www-form-urlencoded` salvo que se establezca un Content-Type distinto (multipart/form-data envía el array tal cual).

public static post(string $url[, mixed $data = [] ]) : self
Parameters
$url : string
$data : mixed = []
Return values
self

postJson()

Atajo para POST con cuerpo JSON: serializa `$data` y fija la cabecera `Content-Type: application/json`.

public static postJson(string $url[, array<string|int, mixed> $data = [] ]) : self
Parameters
$url : string
$data : array<string|int, mixed> = []
Return values
self

put()

Crea una petición PUT; el cuerpo se construye igual que en POST.

public static put(string $url[, mixed $data = [] ]) : self
Parameters
$url : string
$data : mixed = []
Return values
self

saveAs()

Guarda el cuerpo de la respuesta en `$filename`.

public saveAs(string $filename) : bool

Sólo escribe si el código de respuesta es exactamente 200; para 201/202 no guarda nada y devuelve false. Devuelve también false si file_put_contents falla.

Parameters
$filename : string
Return values
bool

setBearerToken()

Añade una cabecera `Authorization: Bearer <token>` para autenticación OAuth/JWT.

public setBearerToken(string $token) : self
Parameters
$token : string
Return values
self

setCurlOption()

Sobrescribe directamente una opción de cURL (constante `CURLOPT_*`). Usar con cuidado.

public setCurlOption(int $option, mixed $value) : self
Parameters
$option : int
$value : mixed
Return values
self

setHeader()

Define una cabecera de la petición.

public setHeader(string $key, string $value) : self

Internamente se almacena ya formateada ("Clave: Valor") e indexada por el nombre original de la cabecera, por lo que llamar dos veces con la misma clave (mismo case) sustituye el valor anterior, pero usar otro case crearía una entrada distinta.

Parameters
$key : string
$value : string
Return values
self

setHeaders()

Sustituye por completo el conjunto de cabeceras de la petición.

public setHeaders(array<string|int, mixed> $headers) : self

Espera el array ya en el formato interno (["Clave" => "Clave: Valor"]); si vas a fijarlas una a una, usa setHeader().

Parameters
$headers : array<string|int, mixed>
Return values
self

setTimeout()

Establece el timeout total de la petición en segundos (atajo de `CURLOPT_TIMEOUT`).

public setTimeout(int $timeout) : self
Parameters
$timeout : int
Return values
self

setToken()

Añade una cabecera `Token: <token>` (autenticación específica de algunas APIs internas).

public setToken(string $token) : self
Parameters
$token : string
Return values
self

setUser()

Configura autenticación HTTP Basic mediante `CURLOPT_USERPWD`.

public setUser(string $user, string $password) : self
Parameters
$user : string
$password : string
Return values
self

setUserAgent()

Sustituye el User-Agent por defecto (que es `FacturaScripts <version>`).

public setUserAgent(string $userAgent) : self
Parameters
$userAgent : string
Return values
self

status()

Devuelve el código HTTP de la respuesta. Ejecuta la petición si aún no se había hecho.

public status() : int
Return values
int

exec()

Ejecuta la petición cURL y rellena `body`, `statusCode`, `error` y `responseHeaders`.

protected exec() : void

Se invoca de forma perezosa la primera vez que se llama a un getter; las llamadas posteriores no relanzan la petición porque el flag executed queda a true incluso si cURL devuelve error. Las cabeceras de respuesta se capturan mediante CURLOPT_HEADERFUNCTION y se indexan en minúsculas, almacenando todos los valores cuando una cabecera aparece varias veces (típico en Set-Cookie).

getPostFields()

Prepara el cuerpo a enviar para POST/PUT/PATCH según el Content-Type configurado.

protected getPostFields() : mixed

Si la cabecera Content-Type es multipart/form-data, se devuelven los datos sin codificar para que cURL construya el cuerpo multipart automáticamente (necesario para subir ficheros con CURLFile). Si no, los arrays se codifican con http_build_query y los strings se envían tal cual (caso típico al enviar JSON ya serializado, como hace postJson()).

On this page

Search results