PHPackages robtimus/json-object-mapper - 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. [Parsing & Serialization](/categories/parsing) 4. / 5. robtimus/json-object-mapper AbandonedArchivedLibrary[Parsing & Serialization](/categories/parsing) robtimus/json-object-mapper =========================== A library to map objects to and from JSON 0.3.1(7y ago)0172Apache-2.0PHPPHP >=5.3.2 Since May 8Pushed 3y ago1 watchersCompare [ Source](https://github.com/robtimus/json-object-mapper)[ Packagist](https://packagist.org/packages/robtimus/json-object-mapper)[ Docs](https://robtimus.github.io/json-object-mapper)[ RSS](/packages/robtimus-json-object-mapper/feed)WikiDiscussions master Synced 3d ago READMEChangelog (4)Dependencies (3)Versions (5)Used By (0) JSON Object Mapper ================== [](#json-object-mapper) Converts objects to and from JSON (serialization and deserialization respectively). Although built upon [json\_encode](http://php.net/manual/en/function.json-encode.php) and [json\_decode](http://php.net/manual/en/function.json-decode.php), it supports any type of object, not just [stdClass](http://php.net/manual/en/reserved.classes.php). Basic usage ----------- [](#basic-usage) An `ObjectMapper` instance has two methods: - `toJSON` takes an object or array and serializes it to a JSON string. - `fromJSON` takes a JSON string and deserializes it to an object or array of objects. The type of object must be given, either as its fully qualified name, or as an [ReflectionClass](http://php.net/manual/en/class.reflectionclass.php) instance). Example: ``` $mapper = new ObjectMapper(); $json = $mapper->toJSON($object); $object = $mapper->fromJSON($json, '\MyClass'); ``` JSON Property mapping --------------------- [](#json-property-mapping) By default, all public properties, getters (both `get` and `is` prefixes are supported) and setters are included. These need to specify their types using [phpDocumenter](https://docs.phpdoc.org/) annotations. For instance: ``` class Person { /** * @var string */ public $firstName; private $lastName; /** * @return string */ public function getLastName() { return $this->lastName; } /** * @param string $value */ public function setLastName($value) { $this->lastName = $value; } } ``` The following are supported: - Scalar types (`boolean`, `bool`, `integer`, `int`, `float`, `double`, `string`). - Object types. - `\stdClass`. - Arrays of the above; append `[]` after the type. ### Including and excluding JSON properties [](#including-and-excluding-json-properties) Note: all of the below annotations are located in namespace `Robtimus\JSON\Mapper\Annotations`, and either need to be included with a `use` statement, or be used with their fully qualified class names. #### @JSONAccessorType [](#jsonaccessortype) A class can be annotated with `@JSONAccessorType("")` to change what is automatically included. The following are valid accessor types: - `METHOD`: all getters and setters are included, even if they are not public. - `PROPERTY`: all properties are included, even if they are not public. - `PUBLIC_MEMBER`: all public properties, getters and setters are included. - `NONE`: no properties, getters or setters are included unless explicitly included. Use this if you want to explicitly include JSON properties. #### @JSONProperty [](#jsonproperty) A single property, getter or setter can be explicitly included by annotating it with `@JSONProperty`, even if it would otherwise be excluded. This annotation can take an optional `name` property to override the default property name: `@JSONProperty(name = "name")`. If no explicit JSON property name is given it is determined as follows: - For properties, the property name. - For getters and setters, the getter/setter name with the leading `get`, `is` or `set` prefix and any underscores following it immediately removed, then the first character lowercased. If the method name after the prefix is all uppercase it will be considered an acronym and be completely lowercased (e.g. `getURL` => `url`). #### @JSONIgnore [](#jsonignore) A single property, getter or setter can be ignored by annotating it with `@JSONIgnore`, even if it would otherwise be included (this overrides `@JSONProperty`). #### @JSONReadOnly [](#jsonreadonly) A single property can be made read-only (i.e. it will be ignored during deserialization) by annotating it with `@JSONReadOnly`. The same can also be achieved by making the property private and only providing a getter, or by annotating the setter with `@JSONIgnore`. #### @JSONWriteOnly [](#jsonwriteonly) A single property can be made write-only (i.e. it will be ignored during serialization) by annotating it with `@JSONWriteOnly`. The same can also be achieved by making the property private and only providing a setter, or by annotating the getter with `@JSONIgnore`. #### @JSONAnyGetter [](#jsonanygetter) A single method that takes no arguments and returns an associative array, `stdClass` instance or an iterator can be annotated with `@JSONAnyGetter`. The keys and values of the return value will be added to the JSON string during serialization. #### Ignoring `null` values and/or empty arrays [](#ignoring-null-values-andor-empty-arrays) Set the `omitNullValues` property of an `ObjectMapper` instance to `true` to omit JSON properties with `null` values. Set the `omitEmptyArrays` property of an `ObjectMapper` instance to `true` to omit JSON properties with empty array values. ### JSON Property order [](#json-property-order) By default, JSON properties will have an undetermined order during serialization. A class can be annotated with `@JSONPropertyOrder` to create a specific order. This annotation can be used in two ways: - `@JSONPropertyOrder(alphabetical = true)` to use alphabetical ordering. - `@JSONPropertyOrder(properties = {"property1", "property2", ...})` to specify the desired order. Note that this list must include all JSON properties, including inherited JSON properties. Note that this property order does not include properties returned by methods annotated with `@JSONAnyGetter`. ### Handling unknown properties [](#handling-unknown-properties) By default, when deserializing a JSON string to an object, any JSON property that is not defined in the object will cause a `JSONParseException` to be thrown. This can be be prevented in one of two ways: - Set the `allowUndefinedProperties` property of the `ObjectMapper` instance to true. This will cause any undefined JSON property to be ignored. - Provide a single method that takes two arguments (for the JSON property name and its value), and annotate it with `@JSONAnySetter`. This method will be called for each unknown JSON property and its value. ### Custom serialization and deserialization [](#custom-serialization-and-deserialization) By default, scalar values are used as-is, and object are processed as described above. This behaviour can be changed by providing a custom serializer or deserializer. #### Custom serialization [](#custom-serialization) A custom serializer can be created by implementing `JSONSerializer`, and can be defined for a JSON property in two ways: - Annotate a property or getter with `@JSONSerialize(using = "")` to use a custom serializer for a single property or getter. - Call `setDefaultSerializer` on the `ObjectMapper` instance to use a custom serializer for all JSON properties of a specific type. For example, to use a `DateTimeJSONSerializer` with for all `DateTime` JSON properties: `$mapper->setDefaultSerializer('\DateTime', new DateTimeJSONSerializer(DateTime::RFC3339_EXTENDED));` #### Custom serialization [](#custom-serialization-1) A custom deserializer can be created by implementing `JSONDeserializer`, and can be defined for a JSON property in two ways: - Annotate a property or setter with `@JSONDeserialize(using = "")` to use a custom deserializer for a single property or setter. - Call `setDefaultDeserializer` on the `ObjectMapper` instance to use a custom deserializer for all JSON properties of a specific type. For example, to use a `DateTimeJSONDeserializer` with for all `DateTime` JSON properties: `$mapper->setDefaultDeserializer('\DateTime', new DateTimeJSONDeserializer(DateTime::RFC3339_EXTENDED));` ### Programmatic mapping [](#programmatic-mapping) Besides using annotations, mappings for a class can also be created programmatically by creating a `ClassDescriptor` and adding properties. It can then be added to an `ObjectMapper` instance using its `registerClass` method. The following is a mapping of annotations to the methods that replace them: - `@JSONAccessorType`: no replacement, as programmatic mapping replaces all automatic inclusion of JSON properties. - `@JSONProperty`: call `addProperty` or `ensureProperty` on a `ClassDescriptor` instance, these returns the added property as an instance of `PropertyDescriptor`. The name and type are required; the type can be relative to an optional third argument of type `ReflectionClass`. - `@JSONIgnore`: no replacement, as programmatic mapping only properties to include can be added. - `@JSONReadOnly`: do not call `withSetter` on an added property. - `@JSONWriteOnly`: do not call `withGetter` on an added property. - `@JSONAnyGetter`: call `withAnyGetter` on a `ClassDescriptor` instance. This method is additive, so it's possible to specify multiple methods. - `@JSONAnySetter`: call `withAnySetter` on a `ClassDescriptor` instance. - `@JSONPropertyOrder`: call `orderProperties` on a `ClassDescriptor` instance. Provide an array with the JSON properties to order on, or provide no arguments to use alphatical ordering. - `@JSONSerialize`: call `withSerializer` on an added property. - `@JSONDeserialize`: call `withDeserializer` on an added property. Note that all getters and setters are callables. This removes the requirement to use instance methods. An example: ``` $classDescriptor = new ClassDescriptor(new ReflectionClass('\Person')); $classDescriptor->addProperty('firstName', 'string') ->withGetter(array(new ReflectionProperty('\Person', 'firstName'), 'getValue')) ->withSetter(array(new ReflectionProperty('\Person', 'firstName'), 'setValue')); $classDescriptor->addProperty('lastName', 'string') ->withGetter(array(new ReflectionMethod('\Person', 'getLastName'), 'invoke')) ->withSetter(array(new ReflectionMethod('\Person', 'setLastName'), 'invoke')); $mapper->registerClass($classDescriptor); ``` Formatting ---------- [](#formatting) Similar to [json\_encode](http://php.net/manual/en/function.json-encode.php), the `toJSON` method of an `ObjectMapper` instance can take a bitmask of options. The same options are supported. ### Health Score 24 — LowBetter than 32% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity7 Limited adoption so far Community9 Small or concentrated contributor base Maturity51 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 ~25 days Total 4 Last Release 2852d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/ae572a8816c41da92fcdc2c0f6296dde938ffc0bd81a99225ad3be6e057483de?d=identicon)[robtimus](/maintainers/robtimus) --- Top Contributors [![robtimus](https://avatars.githubusercontent.com/u/7405731?v=4)](https://github.com/robtimus "robtimus (7 commits)") --- Tags jsonphpjson ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/robtimus-json-object-mapper/health.svg) ``` [![Health](https://phpackages.com/badges/robtimus-json-object-mapper/health.svg)](https://phpackages.com/packages/robtimus-json-object-mapper) ``` ### Alternatives [mtdowling/jmespath.php Declaratively specify how to extract elements from a JSON document 2.0k472.8M135](/packages/mtdowling-jmespathphp)[jms/serializer Library for (de-)serializing data of any complexity; supports XML, and JSON. 2.3k135.8M851](/packages/jms-serializer)[jms/serializer-bundle Allows you to easily serialize, and deserialize data of any complexity 1.8k89.3M627](/packages/jms-serializer-bundle)[colinodell/json5 UTF-8 compatible JSON5 parser for PHP 30422.2M45](/packages/colinodell-json5)[clue/ndjson-react Streaming newline-delimited JSON (NDJSON) parser and encoder for ReactPHP. 15267.7M16](/packages/clue-ndjson-react)[ergebnis/json-printer Provides a JSON printer, allowing for flexible indentation. 9138.2M24](/packages/ergebnis-json-printer) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)