README

从 JSON 网络服务获取数据，并将其转换为嵌套对象和数组 - 使用您的模型类。

从基本对象开始，它将 JSON 数据映射到类属性，将它们转换为正确的简单类型或对象。

这有点像 PHP 的 native SOAP 参数映射 SoapClient 提供的功能，但用于 JSON。它不依赖于任何模式，只依赖于您的 PHP 类定义。

类型检测通过解析类属性的 @var 文档注释以及设置方法中的类型提示来完成。

您不需要通过添加 JSON 特定代码来修改模型类；它通过解析现有的文档注释自动工作。

关键词：反序列化，活化

内容

• 优缺点
  • 优点
  • 缺点
• 用法
  • 基本用法
  • 示例
  • 属性类型映射
    • 支持的类型名称
    • 简单类型映射
    • 类映射
    • 可空
  • 日志记录
  • 处理无效或缺失数据
    • 未知属性
    • 缺失属性
    • 私有属性和函数
    • 简单类型而不是对象
    • 向 map() 传递数组
• 安装
  • 通过 Composer
  • 通过 PEAR
• 相关软件
• 关于 JsonMapper
  • 许可
  • 编码风格
  • 作者

优缺点

优点

• IDE 中的自动完成
• 很容易向数据模型类添加舒适方法
• 您的 JSON API 可能会改变，但您的模型可以保持不变 - 不破坏使用模型类的应用程序。

缺点

• 模型类需要手动编写

  由于 JsonMapper 不依赖于任何模式信息（例如，来自 json-schema），因此模型类不能自动生成。

用法

基本用法

1. 注册一个可以加载 PSR-0 兼容类的自动加载器。
2. 创建一个 JsonMapper 对象实例
3. 根据您的数据调用 map 或 mapArray 方法

映射一个普通对象

<?php
require 'autoload.php';
$mapper = new JsonMapper();
$contactObject = $mapper->map($jsonContact, new Contact());
?>

映射对象数组

<?php
require 'autoload.php';
$mapper = new JsonMapper();
$contactsArray = $mapper->mapArray(
    $jsonContacts, array(), 'Contact'
);
?>

除了 array() 之外，您还可以使用 ArrayObject 及其子类。

示例

来自地址簿网络服务的 JSON

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

您的本地 Contact 类

<?php
class Contact
{
    /**
     * Full name
     * @var string
     */
    public $name;

    /**
     * @var Address
     */
    public $address;
}
?>

您的本地 Address 类

<?php
class Address
{
    public $street;
    public $city;

    public function getGeoCoords()
    {
        //do something with $street and $city
    }
}
?>

您的应用程序代码

<?php
$json = json_decode(file_get_contents('http://example.org/sheldon.json'));
$mapper = new JsonMapper();
$contact = $mapper->map($json, new Contact());

echo "Geo coordinates for " . $contact->name . ": "
    . var_export($contact->address->getGeoCoords(), true);
?>

属性类型映射

JsonMapper 使用多个来源来检测属性的正确类型

1. 检查设置方法（set + ucwords($propertyname)）。

   下划线 "_" 和破折号 "-" 使下一个字母大写。属性 foo_bar-baz 导致设置方法 setFooBarBaz。

   1. 如果它在方法签名中有一个类型提示，则使用该类型。

      public function setPerson(Contact $person) {...}
      

   2. 检查方法的文档注释中的 @param $type 注释。

      /**
       * @param Contact $person Main contact for this application
       */
      public function setPerson($person) {...}
      

   3. 如果无法检测到类型，则将纯 JSON 值传递给设置方法。

2. 类属性的 @var $type 文档注释

   /**
    * @var \my\application\model\Contact
    */
   public $person;
   

   属性必须是公共的才能直接使用。受保护和私有的属性不能设置；您必须为它们提供设置方法。

   如果无法检测到类型，则将属性设置为纯 JSON 值。

   如果找不到属性，JsonMapper会尝试以不区分大小写的方式查找该属性。JSON属性isempty将被映射到PHP属性isEmpty。

支持的类型名称

• 简单类型
  • 字符串
  • bool，boolean
  • int，integer
  • double，float
  • 数组
  • 对象
• 类名，有和没有命名空间
  • Contact - 如果JSON值是null，则会抛出异常
• 简单类型和类名的数组
  • int[]
  • Contact[]
• 多维数组
  • int[][]
  • TreeDeePixel[][][]
• 简单类型和类名的ArrayObjects
  • ContactList[Contact]
  • NumberList[int]
• 可为空类型
  • int|null - 如果JSON中的值是null，则为null，否则为整数
  • Contact|null - 如果JSON中的值是null，则为null，否则为Contact类型的对象

ArrayObjects和扩展类被视为数组。

没有类型或类型为mixed的变量将直接设置JSON值，而不进行任何转换。

有关更多信息，请参阅phpdoc的类型文档。

简单类型映射

当需要创建一个对象，但JSON只包含简单类型（例如字符串、浮点数、布尔值）时，此值将被传递给类的构造函数。例如

PHP代码

/**
 * @var DateTime
 */
public $date;

JSON

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

这将导致调用new DateTime('2014-05-15')。

类映射

当变量被定义为抽象类或接口的对象时，JsonMapper通常会尝试直接实例化它们并崩溃。

使用JsonMapper的$classMap属性，您可以指定哪些类应当被实例化

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

这将创建类型为Bar的对象，当变量被定义为类型为Foo时。

可空

JsonMapper在JSON属性为null时抛出异常，除非PHP类属性有可为空类型 - 例如Contact|null。

如果您的API包含许多可能为null的字段，并且您不想使所有类型定义都可为空，请设置

$jm->bStrictNullTypes = false;

日志记录

JsonMapper的setLogger()方法支持所有PSR-3兼容的日志记录实例。

记录的事件

• JSON数据包含一个键，但该类没有相应的属性或setter方法。
• 由于它们是受保护的或私有的，因此无法从外部设置setter或属性

处理无效或缺失数据

在开发过程中，API经常发生变化。要通知此类更改，可以将JsonMapper配置为在缺少或未知数据时抛出异常。

未知属性

当JsonMapper看到JSON数据中的属性不在PHP类中定义时，您可以设置$bExceptionOnUndefinedProperty来让它抛出异常

$jm = new JsonMapper();
$jm->bExceptionOnUndefinedProperty = true;
$jm->map(...);

您也可以选择通过设置一个callable到$undefinedPropertyHandler来自行处理这些属性

/**
 * Handle undefined properties during JsonMapper::map()
 *
 * @param object $object    Object that is being filled
 * @param string $propName  Name of the unknown JSON property
 * @param mixed  $jsonValue JSON value of the property
 *
 * @return void
 */
function setUndefinedProperty($object, $propName, $jsonValue)
{
    $object->{'UNDEF' . $propName} = $jsonValue;
}

$jm = new JsonMapper();
$jm->undefinedPropertyHandler = 'setUndefinedProperty';
$jm->map(...);

缺失属性

您可以使用@required在PHP类的docblock中标记属性为"必需的"

/**
 * @var string
 * @required
 */
public $someDatum;

当JSON数据不包含此属性时，如果激活了$bExceptionOnMissingData，JsonMapper将抛出异常

$jm = new JsonMapper();
$jm->bExceptionOnMissingData = true;
$jm->map(...);

私有属性和函数

您可以通过设置$bIgnoreVisibility为true来允许映射到私有和受保护的属性及setter方法

$jm = new JsonMapper();
$jm->bIgnoreVisibility = true;
$jm->map(...);

简单类型而不是对象

当一个变量的类型是类，而JSON数据是简单类型如string时，JsonMapper会将此值传递给类的构造函数。

如果您不希望这样，请将$bStrictObjectTypeChecking设置为true

$jm = new JsonMapper();
$jm->bStrictObjectTypeChecking = true;
$jm->map(...);

在这种情况下将抛出异常。

向 map() 传递数组

您可能希望将通过调用获取的数组数据传递给map()，该数据是通过调用

json_decode($jsonString, true)

默认情况下，JsonMapper会因为map()函数的第一个参数需要一个对象而抛出异常。您可以通过将$bEnforceMapType设置为false来绕过这个问题。

$jm = new JsonMapper();
$jm->bEnforceMapType = false;
$jm->map(...);

安装

通过 Composer

来源：Packagist

$ composer require netresearch/jsonmapper

通过 PEAR

注意：

从版本1.0.0开始，JsonMapper转移到了PEAR通道https://zustellzentrum.cweiske.de/

来自我们的PEAR通道

$ pear channel-discover zustellzentrum.cweiske.de
$ pear install zz/jsonmapper

相关软件

• Java的Jackson数据绑定
• Johannes Schmitt序列化器（用于PHP）
• metassione（用于PHP）

关于 JsonMapper

许可

JsonMapper遵循OSL 3.0许可协议。

编码风格

JsonMapper遵循PEAR编码标准。

作者

Christian Weiske，cweiske.de