PHPackages                             yassinedabbous/laravel-jsonable-request - 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. yassinedabbous/laravel-jsonable-request

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

yassinedabbous/laravel-jsonable-request
=======================================

Build http requests from Array/Json

v1.0.0(11mo ago)011MITPHP

Since Dec 15Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/YassineDabbous/laravel-jsonable-request)[ Packagist](https://packagist.org/packages/yassinedabbous/laravel-jsonable-request)[ RSS](/packages/yassinedabbous-laravel-jsonable-request/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (4)Used By (0)

---

Laravel Jsonable Request
========================

[](#laravel-jsonable-request)

[![Latest Version on Packagist](https://camo.githubusercontent.com/5449582d567046d26141ff29eda37d782d8bc4e7512878d82e42b9cdc56c3b6f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f79617373696e65646162626f75732f6c61726176656c2d6a736f6e61626c652d726571756573742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/yassinedabbous/laravel-jsonable-request)[![License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

Seamlessly build and send dynamic HTTP requests within your Laravel application using structured array/JSON templates. Define your API calls once, and inject variable data on the fly.

✨ Features
----------

[](#-features)

- **Template-driven Requests:** Define HTTP requests (endpoint, method, headers, body, auth) as reusable PHP arrays.
- **Dynamic Data Interpolation:** Substitute placeholders (`{{key}}`) in your templates with runtime data, supporting nested arrays and preserving original data types (e.g., `int`, `bool`, `array`).
- **Flexible Body Formats:** Automatically handles `query` parameters for GET requests and `json` bodies for others by default, with options for explicit control.
- **Authentication Support:** Out-of-the-box support for Basic, Digest, and Bearer Token authentication.
- **Built-in Validation:** Ensures your request templates are well-formed before processing.

🚀 Installation
--------------

[](#-installation)

You can install the package via Composer:

```
composer require yassinedabbous/laravel-jsonable-request
```

The package will automatically register its service provider.

📖 Usage
-------

[](#-usage)

The `RequestBuilder` class is the core of this package. You can resolve it from the Laravel container or instantiate it directly.

```
use YassineDabbous\JsonableRequest\RequestBuilder;

// Option 1: Instantiate directly
$builder = new RequestBuilder();

// Option 2: Resolve from container (if you've configured binding in your service provider)
// $builder = app(YassineDabbous\JsonableRequest\RequestBuilderContract::class);
```

### Basic GET Request

[](#basic-get-request)

Define a template and provide the dynamic data:

```
$template = [
    'endpoint' => 'https://jsonplaceholder.typicode.com/posts/{{postId}}',
    'method' => 'GET',
    'data' => [ // Data for query parameters in GET requests
        'comments' => '{{includeComments}}'
    ]
];

$data = [
    'postId' => 1,
    'includeComments' => 'true' // Example: can be 'true' or 'false'
];

$response = $builder->send($template, $data);

if ($response->ok()) {
    $post = $response->json();
    // ... handle post data
}
```

### POST Request with JSON Body

[](#post-request-with-json-body)

The package defaults to a `json` body format for `POST` requests if not specified. Data types provided in `$data` will be preserved in the JSON body.

```
$template = [
    'endpoint' => 'https://jsonplaceholder.typicode.com/posts',
    'method' => 'POST',
    'headers' => [
        'X-Request-ID' => '{{requestId}}'
    ],
    'data' => [ // Data for JSON body in POST requests
        'title' => '{{postTitle}}',
        'body' => '{{postContent}}',
        'userId' => '{{authorId}}',
        'tags' => ['coding', '{{dynamicTag}}'],
        'is_published' => '{{publishedStatus}}'
    ],
    'body_format' => 'json' // Explicitly set, though 'json' is default for POST
];

$data = [
    'requestId' => uniqid('req_'),
    'postTitle' => 'My First Dynamic Post',
    'postContent' => 'This content was generated dynamically.',
    'authorId' => 123, // This integer will be preserved
    'dynamicTag' => 'laravel',
    'publishedStatus' => true // This boolean will be preserved
];

$response = $builder->send($template, $data);

if ($response->created()) {
    $newPost = $response->json();
    // ...
}
```

### Authentication

[](#authentication)

You can specify authentication details in the `auth` key.

#### Basic Authentication

[](#basic-authentication)

```
$template = [
    'endpoint' => 'https://api.example.com/secure/data',
    'method' => 'GET',
    'auth' => [
        'type' => 'basic',
        'username' => '{{apiUser}}',
        'password' => '{{apiPass}}'
    ]
];
$data = ['apiUser' => 'admin', 'apiPass' => 'super_secret'];
$response = $builder->send($template, $data);
```

#### Bearer Token Authentication

[](#bearer-token-authentication)

```
$template = [
    'endpoint' => 'https://api.example.com/auth/resource',
    'method' => 'GET',
    'auth' => [
        'type' => 'token', // Uses withToken() in Laravel Http Client
        'token' => '{{accessToken}}'
    ]
];
$data = ['accessToken' => 'your_jwt_token_here'];
$response = $builder->send($template, $data);
```

#### Digest Authentication

[](#digest-authentication)

```
$template = [
    'endpoint' => 'https://api.example.com/digest/auth',
    'method' => 'GET',
    'auth' => [
        'type' => 'digest',
        'username' => '{{digestUser}}',
        'password' => '{{digestPass}}'
    ]
];
$data = ['digestUser' => 'digest_user', 'digestPass' => 'digest_secret'];
$response = $builder->send($template, $data);
```

### Understanding `parse()` and `send()`

[](#understanding-parse-and-send)

The `RequestBuilder` provides two public methods:

- `parse(array $template, array $data): array`

    - This method takes a raw template and your dynamic data, performing all the interpolation and validation.
    - It returns the fully prepared template array.
    - Use this if you need to inspect or modify the template *after* interpolation but *before* sending the request.
- `send(array $template, ?array $data = null): Response`

    - This is the primary method for dispatching requests.
    - If `$data` is provided (recommended), it first calls `parse()` internally to prepare the template, then sends the request.
    - If `$data` is `null`, it assumes the provided `$template` is already parsed and validated, and proceeds to send the request directly. This is useful if you manually called `parse()` beforehand.

```
// Common usage: parse and send in one go
$response = $builder->send($yourTemplate, $yourData);

// Advanced usage: Parse, modify, then send
$parsedTemplate = $builder->parse($yourTemplate, $yourData);
// Example: Add an extra header dynamically after parsing
$parsedTemplate['headers']['X-App-Version'] = '1.0.0';
$response = $builder->send($parsedTemplate); // No $data needed here
```

Template Structure Reference
----------------------------

[](#template-structure-reference)

The `$template` array supports the following keys:

- `endpoint` (string, **required**): The full URL for the request.
- `method` (string, default: `'POST'`): The HTTP method (e.g., `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Case-insensitive.
- `headers` (array, default: `[]`): An associative array of custom headers.
- `data` (array, default: `[]`):
    - For `GET` requests (`body_format: 'query'`): This data will be appended as URL query parameters.
    - For `POST`/`PUT`/`PATCH` requests (`body_format: 'json'` or `'form_params'`): This data will form the request body.
    - Supports deeply nested interpolation.
- `body_format` (string, default: `'query'` for `GET` methods, `'json'` for others):
    - `'query'`: Data sent as URL query parameters.
    - `'json'`: Data sent as a JSON request body (`Content-Type: application/json`).
    - `'form_params'`: Data sent as `x-www-form-urlencoded` (`Content-Type: application/x-www-form-urlencoded`).
    - (Future: May support `'multipart'` for file uploads).
- `auth` (array, default: `[]`): Authentication details.
    - `type` (string): `'basic'`, `'digest'`, or `'token'`.
    - For `'basic'` or `'digest'`: requires `username` (string) and `password` (string).
    - For `'token'`: requires `token` (string).

Placeholder Interpolation Details
---------------------------------

[](#placeholder-interpolation-details)

Placeholders are defined using **double braces `{{key}}`** to distinguish them from Laravel's route parameters.

The interpolation logic is robust:

- **Exact Match:** If a string in your template is *exactly* `{{key}}` (e.g., `data => ['user_id' => '{{id}}']`), it will be replaced by the corresponding value from `$data` while **preserving its original PHP data type** (e.g., `int`, `bool`, `array`, `float`). This is crucial for correctly forming JSON bodies.
    - Example: `data = ['user_id' => '{{user_id}}']`, `data_vars = ['user_id' => 123]`. Result: `['user_id' => 123]` (integer).
- **Partial Match:** If a string contains a placeholder along with other text (e.g., `'Hello {{name}}'`, or `'User ID: {{id}}'`), the placeholder will be replaced by the **string representation** of its corresponding value from `$data`.
    - **Important Note:** If the corresponding value in `$data` for a placeholder in a *partial string* is an `array` or `object`, that placeholder **will NOT be replaced** and will remain in the string, as arrays/objects cannot be directly embedded into strings.
    - Example: `data = ['message' => 'Hello {{name}}']`, `data_vars = ['name' => 'Alice']`. Result: `['message' => 'Hello Alice']`.
    - Example: `data = ['details' => 'Items: {{item_list}}']`, `data_vars = ['item_list' => ['apple', 'banana']]`. Result: `['details' => 'Items: {{item_list}}']` (placeholder remains).

🛡️ Validation & Error Handling
----------------------------------

[](#️-validation--error-handling)

The `RequestBuilder` includes built-in validation to ensure template integrity:

- Throws `InvalidArgumentException` if `endpoint` is missing.
- Throws `InvalidArgumentException` if `auth` type `basic` or `digest` is used but `username` or `password` are missing.
- Other validations (e.g., for unknown `method` or `body_format`) can be added.

🙌 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to open an issue or submit a pull request.

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

---

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance70

Regular maintenance activity

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 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 ~82 days

Total

3

Last Release

349d ago

Major Versions

v0.0.3 → v1.0.02025-05-28

### Community

Maintainers

![](https://www.gravatar.com/avatar/1d37e45493d8bb1909560f0565f6ed570aff351ae461eacadb1024c0b231a917?d=identicon)[YassineDabbous](/maintainers/YassineDabbous)

---

Top Contributors

[![YassineDabbous](https://avatars.githubusercontent.com/u/10944169?v=4)](https://github.com/YassineDabbous "YassineDabbous (15 commits)")

---

Tags

httprequestjsonlaravelGuzzle

### Embed Badge

![Health badge](/badges/yassinedabbous-laravel-jsonable-request/health.svg)

```
[![Health](https://phpackages.com/badges/yassinedabbous-laravel-jsonable-request/health.svg)](https://phpackages.com/packages/yassinedabbous-laravel-jsonable-request)
```

###  Alternatives

[graze/guzzle-jsonrpc

JSON-RPC 2.0 client for Guzzle

981.2M24](/packages/graze-guzzle-jsonrpc)[kozz/laravel-guzzle-provider

Guzzle 5/6 Service Provider for Laravel

621.1M2](/packages/kozz-laravel-guzzle-provider)[behamin/service-proxy

for proxy or sending requests to other services with useful utilities

102.2k](/packages/behamin-service-proxy)

PHPackages © 2026

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