README

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

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

它类似于PHP的SoapClient提供的本地SOAP参数映射，但适用于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(...);

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

可空

当JSON属性为null时，JsonMapper会抛出异常，除非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(...);

缺失属性

您可以在PHP类的属性的文档块中使用@required来标记它们为“必需”

/**
 * @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

相关软件

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

关于JsonMapper

许可证

JsonMapper 使用 OSL 3.0 许可证。

编码风格

JsonMapper 遵循 PEAR 编码标准。

作者

Christian Weiske，cweiske.de