PHPackages                             lucinda/requester - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. lucinda/requester

ActiveLibrary[HTTP & Networking](/categories/http)

lucinda/requester
=================

Light weight complete object oriented cURL wrapper for HTTP/HTTPS requests

v2.0.10(1mo ago)122.2k↓63.6%21MITPHPPHP ^8.1

Since Oct 27Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/aherne/requester)[ Packagist](https://packagist.org/packages/lucinda/requester)[ RSS](/packages/lucinda-requester/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (3)Dependencies (2)Versions (31)Used By (1)

Lucinda URL Requester
=====================

[](#lucinda-url-requester)

Table of contents:

- [About](#about)
- [Running Single Requests](#running-single-requests)
    - [File Uploading](#file-uploading)
    - [File Downloading](#file-downloading)
- [Running Multiple Asynchronous Requests](#running-multiple-asynchronous-requests)
- [Running Cookie Sharing Synchronous Requests](#running-cookie-sharing-synchronous-requests)
    - [Working With HTTP Cookies](#working-with-http-cookies)
- [Working With Responses](#working-with-responses)
- [Examples](#examples)
    - [HTTP GET Request](#http-get-request)
    - [HTTP POST Request](#http-post-request)
    - [HTTP PUT Request](#http-put-request)
    - [HTTP DELETE Request](#http-delete-request)
- [Error Handling](#error-handling)

About
-----

[](#about)

This API is a light weight cURL wrapper aimed at completely hiding chaotic native library underneath through a full featured OOP layer that is easy and logical to work with. It is built as an antithesis of Guzzle, the "industry standard" today, by being:

- **self-reliant**: unlike Guzzle, which has no less than 40 dependencies, it depends only on 1 library for unit testing
- **very simple**: each class is designed to cover an aspect of a URL request and response processing, but only a limited number are relevant for developers
- **very fast**: all code inside is developed on "less is more" paradigm: no over abstraction, no line of code more than strictly needed

Library is 99% unit tested (some areas of cURL functionality have zero documentation), fully PSR-4 compliant, only requiring PHP8.1+ interpreter and cURL extension. For installation you just need to write this in console:

```
composer require lucinda/requester
```

Then use one of main classes provided:

- [Lucinda\\URL\\Request](https://github.com/aherne/requester/blob/master/src/Request.php): encapsulates a single HTTP/HTTPs request over cURL (covering curl\_\* functions)
    - [Lucinda\\URL\\FileUpload](https://github.com/aherne/requester/blob/master/src/FileUpload.php): specializes [Lucinda\\URL\\Request](https://github.com/aherne/requester/blob/master/src/Request.php) for file upload
    - [Lucinda\\URL\\FileDownload](https://github.com/aherne/requester/blob/master/src/FileDownload.php): specializes [Lucinda\\URL\\Request](https://github.com/aherne/requester/blob/master/src/Request.php) for file download
- [Lucinda\\URL\\MultiRequest](https://github.com/aherne/requester/blob/master/src/MultiRequest.php): encapsulates simultaneous multi HTTP/HTTPs requests over cURL (covering curl\_multi\_\* functions)
- [Lucinda\\URL\\SharedRequest](https://github.com/aherne/requester/blob/master/src/SharedRequest.php): encapsulates multi HTTP/HTTPs requests able to share cookies/session over cURL (covering curl\_share\_\* functions)

Each of above classes branches through its methods to deeper classes that become relevant depending on the complexity of request. The end result of every request is a [Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php) object, encapsulating all response information (headers, body, status).

Running single requests
-----------------------

[](#running-single-requests)

Performing a single HTTPs request is as simple as this:

```
$request = new Lucinda\URL\Request("https://www.lucinda-framework.com");
$response = $request->execute();
```

This automatically sends target host embedded CAINFO certificate along with URL in order to establish a TLS connection then receives a [Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php) object. The class in charge of single requests is [Lucinda\\URL\\Request](https://github.com/aherne/requester/blob/master/src/Request.php), defining following public methods:

MethodArgumentsReturnsDescription\_\_construct?string $url = nullvoidOpens a cURL handle and optionally sets target URLsetURLstring $urlvoidManually sets request URL
Throws [Lucinda\\URL\\RequestException](https://github.com/aherne/requester/blob/master/src/RequestException.php) if url is invalidsetMethod[Lucinda\\URL\\Request\\Method](https://github.com/aherne/requester/blob/master/src/Request/Method.php) $methodvoidSets request method as one of [Lucinda\\URL\\Request\\Method](https://github.com/aherne/requester/blob/master/src/Request/Method.php) enum values otherwise assumes GET!
Throws [Lucinda\\URL\\RequestException](https://github.com/aherne/requester/blob/master/src/RequestException.php) if request method is invalidsetParametersarray $parameters = \[\][Lucinda\\URL\\Request\\Parameters](https://github.com/aherne/requester/blob/master/src/Request/Parameters.php)Sets POST request parameters directly (by key and value) or delegates to specialized class.setRawstring $bodyvoidSets binary request parameters, available if request method is POST / GET / DELETE!
setHeadersvoid[Lucinda\\URL\\Request\\Headers](https://github.com/aherne/requester/blob/master/src/Request/Headers.php)Sets request headers by delegating to specialized classsetSSLstring $certificateAuthorityBundlePath[Lucinda\\URL\\Request\\SSL](https://github.com/aherne/requester/blob/master/src/Request/SSL.php)Sets custom certificate authority bundle to use in SSL requests and delegates to specialized class.
If not used, API will employ embedded **cacert.pem** file downloaded from [official site](https://curl.haxx.se/ca/cacert.pem)!setCustomOptionint $curlopt,
mixed $valuevoidSets a custom CURLOPT\_\* request option not covered by API already.
Throws [Lucinda\\URL\\RequestException](https://github.com/aherne/requester/blob/master/src/RequestException.php) if option is already covered.setReturnTransferbool $returnTransfervoidSets whether or not response body should be return (default **TRUE** if method not used)executeint $maxRedirectionsAllowed = 0,
int $timeout = 300000[Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php)Executes request and produces a response.
Throws [Lucinda\\URL\\RequestException](https://github.com/aherne/requester/blob/master/src/RequestException.php) if invalid request options combination was found.
Throws [Lucinda\\URL\\ResponseException](https://github.com/aherne/requester/blob/master/src/ResponseException.php) if response retrieval failed (eg: response exceeded timeout).### File Uploading

[](#file-uploading)

API comes with [Lucinda\\URL\\Request](https://github.com/aherne/requester/blob/master/src/Request.php) extensions specifically designed for file upload. To upload a file you must use [Lucinda\\URL\\FileUpload](https://github.com/aherne/requester/blob/master/src/FileUpload.php), which comes with following additional public methods:

MethodArgumentsReturnsDescription\_\_destructvoidvoidCloses file handles created by setFile method belowsetMethod[Lucinda\\URL\\Request\\Method](https://github.com/aherne/requester/blob/master/src/Request/Method.php) $methodvoidSpecializes parent method to only allow POST and PUT requestssetFilestring $pathvoidSets absolute location of file to upload, available if request method is PUT!
Throws [Lucinda\\URL\\FileNotFoundException](https://github.com/aherne/requester/blob/master/src/FileNotFoundException.php) if file isn't found.setRawstring $bodyvoidSets binary body of file to upload, available if request method is POST!
setProgressHandler[Lucinda\\URL\\Request\\Progress](https://github.com/aherne/requester/blob/master/src/Request/Progress.php) $progressHandlervoidSets handle to use in tracking upload progress.executeint $maxRedirectionsAllowed = 0,
int $timeout = 300000[Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php)Uploads file, updating response status accordingly.Example (uploads LOCAL\_FILE\_PATH to REMOTE\_FILE\_PATH):

```
$request = new Lucinda\URL\FileUpload(REMOTE_FILE_PATH);
$request->setMethod(Lucinda\URL\Request\Method::PUT);
$request->setFile(LOCAL_FILE_PATH);
$request->execute();
```

### File Downloading

[](#file-downloading)

API comes with [Lucinda\\URL\\Request](https://github.com/aherne/requester/blob/master/src/Request.php) extensions specifically designed for file download. To download a file you must use [Lucinda\\URL\\FileDownload](https://github.com/aherne/requester/blob/master/src/FileDownload.php), which comes with following additional public methods:

MethodArgumentsReturnsDescriptionsetMethod[Lucinda\\URL\\Request\\Method](https://github.com/aherne/requester/blob/master/src/Request/Method.php) $methodvoidSpecializes parent method to only allow GET requestssetFilestring $pathvoidSets absolute location where file will be downloaded (incl. file name and extension)!
Using this method is **mandatory**!setProgressHandler[Lucinda\\URL\\Request\\Progress](https://github.com/aherne/requester/blob/master/src/Request/Progress.php) $progressHandlervoidSets handle to use in tracking download progress.executeint $maxRedirectionsAllowed = 0,
int $timeout = 300000[Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php)Downloads file, updating response status accordingly.Example (downloads REMOTE\_FILE\_PATH into LOCAL\_FILE\_PATH):

```
$request = new Lucinda\URL\FileDownload(REMOTE_FILE_PATH);
$request->setMethod(Lucinda\URL\Request\Method::GET);
$request->setFile(LOCAL_FILE_PATH);
$request->execute();
```

Running multiple asynchronous requests
--------------------------------------

[](#running-multiple-asynchronous-requests)

Performing multiple requests at once it is no less simple:

```
$multiRequest = new Lucinda\URL\MultiRequest(Lucinda\URL\Request\Pipelining::HTTP2);
$multiRequest->add(new Lucinda\URL\Request("https://www.lucinda-framework.com/news"));
$multiRequest->add(new Lucinda\URL\Request("https://www.lucinda-framework.com/tutorials"));
$responses = $multiRequest->execute();
```

This executes two requests simultaneously using HTTP2 pipelining and receives a Response object array. The class in charge of single requests is [Lucinda\\URL\\MultiRequest](https://github.com/aherne/requester/blob/master/src/MultiRequest.php), defining following public methods:

MethodArgumentsReturnsDescription\_\_construct[Lucinda\\URL\\Request\\Pipelining](https://github.com/aherne/requester/blob/master/src/Request/Pipelining.php) $pipeliningOptionvoidInitiates a multi URL connection based on one of enum valuesaddRequest $requestvoidAdds request to execution pool.setCustomOptionint $curlMultiOpt,
mixed $valuevoidSets a custom CURLMOPT\_\* request option not covered by API already.
Throws [Lucinda\\URL\\RequestException](https://github.com/aherne/requester/blob/master/src/RequestException.php) if option is already coveredsetReturnTransferbool $returnTransfervoidSets whether or not response body should be return (default **TRUE** if method not used)executebool $returnTransfer = true,
int $maxRedirectionsAllowed = 0,
int $timeout = 300000[Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php) \[\]Validates requests in pool then executes them asynchronously in order to produce responses.
Throws [Lucinda\\URL\\RequestException](https://github.com/aherne/requester/blob/master/src/RequestException.php) if invalid request options combination was found.
Throws [Lucinda\\URL\\ResponseException](https://github.com/aherne/requester/blob/master/src/ResponseException.php) if response retrieval failed (eg: response exceeded timeout).Unlike native curl\_multi, responses will be received in the order requests were pooled! Execution will be performed depending on pipelining option (see constructor):

- *DISABLED*: connections are not pipelined
- *HTTP1*: attempts to pipeline HTTP/1.1 requests on connections that are already established
- *HTTP2*: attempts to multiplex the new transfer over an existing connection if HTTP/2
- *HTTP1\_HTTP2*: attempts pipelining and multiplexing independently of each other

Running cookie sharing synchronous requests
-------------------------------------------

[](#running-cookie-sharing-synchronous-requests)

To make multiple requests share cookies/dns, it is as simple as:

```
$sharedRequest = new Lucinda\URL\SharedRequest(Lucinda\URL\Request\ShareType::COOKIE);
$request1 = new Lucinda\URL\Request("http://www.example.com/page1");
$multiRequest->add($request1);
$request2 = new Lucinda\URL\Request("http://www.example.com/page1");
$multiRequest->add($request2);
$response1 = $request1->execute();
$response2 = $request2->execute();
```

This very poorly documented feature makes 2nd request able to see cookies in first request. The class in charge of cookie-sharing requests is [Lucinda\\URL\\SharedRequest](https://github.com/aherne/requester/blob/master/src/SharedRequest.php), defining following public methods:

MethodArgumentsReturnsDescription\_\_construct[Lucinda\\URL\\Request\\ShareType](https://github.com/aherne/requester/blob/master/src/Request/ShareType.php) $shareOptionvoidInitiates a shared URL connection based on one of enum valuesaddRequest $requestvoidAdds request to share pool.Unlike the other two classes of running requests, each request must be executed manually in order to produce a response! Cookie sharing will be performed depending on share type option (see constructor):

- *COOKIES*: connections will share HTTP cookies
- *DNS*: connections will share cached DNS hosts
- *SSL\_SESSION*: connections will share SSL session IDs

### Working with HTTP cookies

[](#working-with-http-cookies)

API comes with a number of classes for working with cookies, whose area is IN BETWEEN requests and responses:

- [Lucinda\\URL\\Cookies](https://github.com/aherne/requester/blob/master/src/Cookies.php): implements general cookies handling operations (based on cURL standards)
- [Lucinda\\URL\\Cookies\\Cookie](https://github.com/aherne/requester/blob/master/src/Cookies/Cookie.php): implements logic of individual cookie (based on HTTP set-cookie header standards)
- [Lucinda\\URL\\Cookies\\CookieParser](https://github.com/aherne/requester/blob/master/src/Cookies/CookieParser.php): interface defining blueprints for encapsulating/decapsulating cookies into/from
    - *headers*: via [Lucinda\\URL\\Cookies\\CookieHeader](https://github.com/aherne/requester/blob/master/src/Cookies/CookieHeader.php)
    - *files*: via [Lucinda\\URL\\Cookies\\CookieFile](https://github.com/aherne/requester/blob/master/src/Cookies/CookieFile.php)

They are rarely needed in everyday usage, so for more info click on their links to see documentation. To see how they can be used, please check respective unit tests!

Working with responses
----------------------

[](#working-with-responses)

The end result of every successful request (defined as one that received ANY response) is encapsulated into a [Lucinda\\URL\\Response](https://github.com/aherne/requester/blob/master/src/Response.php) object that includes:

- *response status*: HTTP status that came with response
- *response headers*: HTTP headers received along with response
- *response body*: actual contents of response (minus headers and status)
- *response statistics*: as supplied by API or cURL driver underneath (eg: total duration)

All this information can be queried via following public methods:

MethodArgumentsReturnsDescriptiongetDurationvoidintGets total response duration in millisecondsgetStatusCodevoidintGets response HTTP status codegetURLvoidstringGets url requestedgetBodyvoidstringGets response bodygetHeadersvoidstring\[string\]Gets response headers by name and valuegetCustomOptionint $curlinfomixedGets value of a custom CURLINFO\_\* response option not covered by API already.
Throws [Lucinda\\URL\\ResponseException](https://github.com/aherne/requester/blob/master/src/ResponseException.php) if option is already coveredExamples
--------

[](#examples)

### HTTP GET Request

[](#http-get-request)

```
# any request that doesn't *setMethod* is considered GET by default
$request = new Lucinda\URL\Request("https://www.example.com/?id=1");
$response = $request->execute();
```

### HTTP POST Request

[](#http-post-request)

```
# any POST request MUST *setParameters*
$request = new Lucinda\URL\Request("https://www.example.com/add");
$request->setMethod(\Lucinda\URL\Request\Method::POST);
$request->setParameters(["asd"=>"fgh", "qwe"=>"rty"]);
$response = $request->execute();
```

### HTTP PUT Request

[](#http-put-request)

```
# any PUT request MUST *setRaw* AND stringify parameters
$request = new Lucinda\URL\Request("https://www.example.com/edit");
$request->setMethod(\Lucinda\URL\Request\Method::PUT);
$request->setRaw(http_build_query(["id"=>1, "qwe"=>"tyu"]));
$response = $request->execute();
```

### HTTP DELETE Request

[](#http-delete-request)

```
# any DELETE request MUST *setRaw* AND stringify parameters
$request = new Lucinda\URL\Request("https://www.example.com/delete");
$request->setMethod(\Lucinda\URL\Request\Method::DELETE);
$request->setRaw(http_build_query(["id"=>1]));
$response = $request->execute();
```

Error handling
--------------

[](#error-handling)

Following exceptions may be thrown during request-response process by this API:

- [Lucinda\\URL\\Request\\Exception](https://github.com/aherne/requester/blob/master/src/Request/Exception.php): if an error has occurred in processing request (request is invalid) BEFORE request being sent. Thrown on logical errors defined by this API.
- [Lucinda\\URL\\Response\\Exception](https://github.com/aherne/requester/blob/master/src/Response/Exception.php): if an error has occurred in receiving response (eg: target host is not responding) AFTER request was sent (covering curl\_*err* and curl\_multi\_*err* functions)
- [Lucinda\\URL\\FileNotFoundException](https://github.com/aherne/requester/blob/master/src/FileNotFoundException.php): if request referenced a local file that doesn't exist.

A few observations:

- **No support for curl\_share\_*err* errors**, for whom there is zero documentation in both PHP cURL documentation as well as the C library it wraps
- **As long as response is received for a request, no exception is thrown!** API does not consider statuses such as 404 or 500 to be errors by default, so it is up to developers to decide how to handle them

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance91

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity74

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~68 days

Recently: every ~131 days

Total

30

Last Release

42d ago

Major Versions

v1.0.6 → v2.0.02021-12-28

v1.0.8 → v2.0.x-dev2022-01-09

v1.0.9 → v2.0.72022-09-01

v1.0.x-dev → v2.0.82024-10-30

PHP version history (3 changes)v1.0.0PHP ^7.1

v2.0.0PHP ^8.1

v1.0.8PHP ^7.1|^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3382770?v=4)[Lucian Gabriel Popescu](/maintainers/aherne)[@aherne](https://github.com/aherne)

---

Top Contributors

[![aherne](https://avatars.githubusercontent.com/u/3382770?v=4)](https://github.com/aherne "aherne (32 commits)")

---

Tags

httphttpscurlwrapper

### Embed Badge

![Health badge](/badges/lucinda-requester/health.svg)

```
[![Health](https://phpackages.com/badges/lucinda-requester/health.svg)](https://phpackages.com/packages/lucinda-requester)
```

###  Alternatives

[mashape/unirest-php

Unirest PHP

1.3k9.7M161](/packages/mashape-unirest-php)[rmccue/requests

A HTTP library written in PHP, for human beings.

3.6k34.5M258](/packages/rmccue-requests)[league/uri

URI manipulation library

1.1k206.4M277](/packages/league-uri)[league/uri-interfaces

Common tools for parsing and resolving RFC3987/RFC3986 URI

536204.9M23](/packages/league-uri-interfaces)[nategood/httpful

A Readable, Chainable, REST friendly, PHP HTTP Client

1.8k17.2M267](/packages/nategood-httpful)[react/http

Event-driven, streaming HTTP client and server implementation for ReactPHP

78026.4M414](/packages/react-http)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)