PHPackages                             graywings/instantiate - 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. [Utility & Helpers](/categories/utility)
4. /
5. graywings/instantiate

ActiveLibrary[Utility & Helpers](/categories/utility)

graywings/instantiate
=====================

Instantiate json/stdClass library

0.0.1(1y ago)04MITPHPCI failing

Since Apr 3Pushed 1y agoCompare

[ Source](https://github.com/old-home/instantiate)[ Packagist](https://packagist.org/packages/graywings/instantiate)[ RSS](/packages/graywings-instantiate/feed)WikiDiscussions main Synced 1mo ago

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

Instantiate
===========

[](#instantiate)

Instantiate is a PHP library for creating objects from various data sources with proper type handling and validation. It supports creating objects from JSON strings, stdClass objects, and associative arrays, with automatic type conversion and nested object creation.

Installation
------------

[](#installation)

```
composer require graywings/instantiate
```

Features
--------

[](#features)

- Create objects from JSON strings, stdClass objects, or associative arrays
- Automatic type conversion based on constructor parameter types
- Support for nested objects and complex data structures
- Proper handling of default parameter values
- Type validation to ensure data integrity
- Support for nullable parameters
- Support for PHP 8.1 enum types (both backed and pure enums)
- Detailed exception messages for easier debugging

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
use Graywings\Instantiate\Instantiate;

// From JSON string
$json = '{"id": 1, "name": "John Doe", "email": "john@example.com"}';
$user = Instantiate::json(User::class, $json);

// From associative array
$array = ['id' => 1, 'name' => 'John Doe', 'email' => 'john@example.com'];
$user = Instantiate::array(User::class, $array);

// From stdClass object
$object = new stdClass();
$object->id = 1;
$object->name = 'John Doe';
$object->email = 'john@example.com';
$user = Instantiate::stdClass(User::class, $object);
```

### Nested Objects

[](#nested-objects)

Instantiate automatically handles nested objects:

```
$json = '
{
    "id": 1,
    "name": "John Doe",
    "address": {
        "street": "123 Main St",
        "city": "New York",
        "zipCode": "10001"
    }
}';

$user = Instantiate::json(User::class, $json);
// $user->getAddress() will be an Address object with the specified properties
```

### Type Conversion

[](#type-conversion)

Instantiate automatically converts values to the expected types:

```
$data = [
    'id' => '42',    // String will be converted to int
    'name' => 'John',
    'active' => 1    // Integer will be converted to boolean
];

$user = Instantiate::array(User::class, $data);
// $user->getId() will be an int (42)
// $user->isActive() will be a boolean (true)
```

### Enum Types

[](#enum-types)

Instantiate has full support for PHP 8.1 enums:

```
enum UserStatus: string {
    case ACTIVE = 'active';
    case INACTIVE = 'inactive';
    case PENDING = 'pending';
}

class User {
    public function __construct(
        private int $id,
        private string $name,
        private UserStatus $status
    ) { }

    // Getters...
}

// From string value matching the enum's backing value
$data1 = [
    'id' => 1,
    'name' => 'John',
    'status' => 'active' // Will be converted to UserStatus::ACTIVE
];

// From actual enum instance
$data2 = [
    'id' => 2,
    'name' => 'Jane',
    'status' => UserStatus::PENDING // Direct enum instance
];

$user1 = Instantiate::array(User::class, $data1);
$user2 = Instantiate::array(User::class, $data2);
```

### Default Values

[](#default-values)

Constructor default values are respected when the data doesn't include the parameter:

```
class User {
    public function __construct(
        private int $id,
        private string $name,
        private ?string $email = null,
        private int $age = 30,
        private bool $active = true
    ) { }

    // Getters...
}

$data = [
    'id' => 1,
    'name' => 'John'
    // email, age, and active are not specified
];

$user = Instantiate::array(User::class, $data);
// $user->getEmail() will be null
// $user->getAge() will be 30
// $user->isActive() will be true
```

Exception Handling
------------------

[](#exception-handling)

Instantiate throws detailed exceptions when there are issues with the data:

- `InstantiateArgumentsException`: Thrown when there are issues with the provided data, such as missing required parameters or invalid types.
- `InstantiateException`: Base exception class for all Instantiate-related exceptions.

```
use Graywings\Instantiate\Exception\InstantiateArgumentsException;
use Graywings\Instantiate\Exception\InstantiateException;

try {
    $user = Instantiate::json(User::class, $json);
} catch (InstantiateArgumentsException $e) {
    // Handle data validation issues
    echo "Data validation error: " . $e->getMessage();
} catch (InstantiateException $e) {
    // Handle other Instantiate-related errors
    echo "Instantiation error: " . $e->getMessage();
}
```

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- Reflection extension enabled

License
-------

[](#license)

This library is released under the MIT License.

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance46

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity27

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

411d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d0b09c43417447279cf821f67049badc7c743f1122b822aa60dc11f9791f1614?d=identicon)[taira-terashima](/maintainers/taira-terashima)

---

Top Contributors

[![t-terashima0815](https://avatars.githubusercontent.com/u/107980425?v=4)](https://github.com/t-terashima0815 "t-terashima0815 (2 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/graywings-instantiate/health.svg)

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

###  Alternatives

[geo-io/interface

Geo I/O base interfaces.

626.1M7](/packages/geo-io-interface)[psi/news4ward

A blogging / news system for Contao

131.4k13](/packages/psi-news4ward)

PHPackages © 2026

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