Download the PHP package pocketmine/netresearch-jsonmapper without Composer

On this page you can find all versions of the php package pocketmine/netresearch-jsonmapper. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package netresearch-jsonmapper


JsonMapper - map nested JSON structures onto PHP classes

Takes data retrieved from a JSON web service and converts them into nested object and arrays - using your own model classes.

Starting from a base object, it maps JSON data on class properties, converting them into the correct simple types or objects.

It's a bit like the native SOAP parameter mapping PHP's SoapClient gives you, but for JSON. It does not rely on any schema, only your PHP class definitions.

Type detection works by parsing @var docblock annotations of class properties, as well as type hints in setter methods.

You do not have to modify your model classes by adding JSON specific code; it works automatically by parsing already-existing docblocks.

This library has no dependencies.

Keywords: deserialization, hydration


Pro & contra

Benefits

Drawbacks


Usage

Basic usage

  1. Register an autoloader that can load PSR-0 compatible classes.
  2. Create a JsonMapper object instance
  3. Call the map or mapArray method, depending on your data

Map a normal object:

Map an array of objects:

Instead of array() you may also use ArrayObject and descending classes as well as classes implementing ArrayAccess.

Example

JSON from an address book web service:

javascript

{ 'name':'Sheldon Cooper', 'address': { 'street': '2311 N. Los Robles Avenue', 'city': 'Pasadena' } }

Your local Contact class:

Your local Address class:

Your application code:

Property type mapping

JsonMapper uses several sources to detect the correct type of a property:

  1. The setter method (set + ucwords($propertyname)) is inspected. Underscores "_" and hyphens "-" make the next letter uppercase. Property foo_bar-baz leads to setter method setFooBarBaz.
    1. If it has a type hint in the method signature then its type used:: public function setPerson(Contact $person) {...}
    2. The method's docblock is inspected for @param $type annotations:: /**
      • @param Contact $person Main contact for this application */ public function setPerson($person) {...}
    3. If no type could be detected, the plain JSON value is passed to the setter method.
  2. Class property types (since PHP 7.4):: public Contact $person;
  3. Constructor property promotion types (since PHP 8.0):: public function __construct(protected Contact $person) {}
  4. @var $type docblock annotation of class properties:: /**
    • @var \my\application\model\Contact */ public $person; The property has to be public to be used directly. You may also use $bIgnoreVisibility to utilize protected and private properties. .. __: #prop-bignorevisibility If no type could be detected, the property gets the plain JSON value set. If a property can not be found, JsonMapper tries to find the property in a case-insensitive manner. A JSON property isempty would then be mapped to a PHP property isEmpty. .. note:: You have to provide the fully qualified namespace for the type to work. Relative class names are evaluated in the context of the current classes namespace, NOT respecting any imports that may be present. PHP does not provide the imports via Reflection; the comment text only contains the literal text of the type. For performance reasons JsonMapper does not parse the source code on its own to detect and expand any imports.

Supported type names

ArrayObjects and extending classes are treated as arrays.

Variables without a type or with type mixed will get the JSON value set directly without any conversion.

See phpdoc's type documentation for more information.

Simple type mapping

When an object shall be created but the JSON contains a simple type only (e.g. string, float, boolean), this value is passed to the classes' constructor. Example:

PHP code:

JSON:

js

{"date":"2014-05-15"}

This will result in new DateTime('2014-05-15') being called.

Class map

When variables are defined as objects of abstract classes or interfaces, JsonMapper would normally try to instantiate those directly and crash.

Using JsonMapper's $classMap property, you can specify which classes shall get instantiated instead:

This would create objects of type Bar when a variable is defined to be of type Foo.

It is also possible to use a callable in case the actual implementation class needs to be determined dynamically (for example in case of a union). The mapped class ('Foo' in the example below) and the Json data are passed as parameters into the call.

$jm = new JsonMapper(); $jm->classMap['Foo'] = $mapper; $jm->map(...);

Nullables

JsonMapper throws an exception when a JSON property is null, unless the PHP class property has a nullable type - e.g. Contact|null.

If your API contains many fields that may be null and you do not want to make all your type definitions nullable, set:

Logging

JsonMapper's setLogger() method supports all PSR-3 compatible logger instances.

Events that get logged:

Handling invalid or missing data

During development, APIs often change. To get notified about such changes, JsonMapper can be configured to throw exceptions in case of either missing or yet unknown data.

Unknown properties

When JsonMapper sees properties in the JSON data that are not defined in the PHP class, you can let it throw an exception by setting $bExceptionOnUndefinedProperty:

You may also choose to handle those properties yourself by setting a callable to $undefinedPropertyHandler:

Or if you would let JsonMapper handle the setter for you, you can return a string from the $undefinedPropertyHandler which will be used as property name.

Missing properties

Properties in your PHP classes can be marked as "required" by putting @required in their docblock:

When the JSON data do not contain this property, JsonMapper will throw an exception when $bExceptionOnMissingData is activated:

Option $bRemoveUndefinedAttributes causes JsonMapper to remove properties from the final object if they have not been in the JSON data:

Private properties and functions

You can allow mapping to private and protected properties and setter methods by setting $bIgnoreVisibility to true:

Simple types instead of objects

When a variable's type is a class and JSON data is a simple type like string, JsonMapper passes this value to the class' constructor.

If you do not want this, set $bStrictObjectTypeChecking to true:

An exception is then thrown in such cases.

Passing arrays to map()

You may wish to pass array data into map() that you got by calling

Post-mapping callback

JsonMapper is able to call a custom method directly on each object after mapping it is finished:

Now afterMapping() is called on each mapped object (if the class has that method).

You may pass additional arguments to the post-mapping callback:


Installation

Via Composer from Packagist:

$ composer require netresearch/jsonmapper

Related software

Alternatives


About JsonMapper

License

JsonMapper is licensed under the OSL 3.0.

Coding style

JsonMapper follows the PEAR Coding Standards.

Author

cweiske.de


All versions of netresearch-jsonmapper with dependencies

PHP Build Version
Package Version
Requires php Version >=7.1
ext-spl Version *
ext-json Version *
ext-pcre Version *
ext-reflection Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package pocketmine/netresearch-jsonmapper contains the following files

Loading the files please wait ....