PHP: Что такое JsonMapper и для чего он нужен?

В этой записи я расскажу про JsonMapper, для чего он используется и почему стоит начать им пользоваться.

Вкратце: Что такое JsonMapper?

JsonMapper использует данные полученные с API в формате JSON для конвертации во вложенные объекты и массивы внутри собственного класса.

Пример

Я люблю примеры, потому что они лучше объясняют.

Давайте представим, что у вас есть API который возвращает какие-то JSON данные. Например ответ может быть следующего формата:

{
  "country": "Russia",
  "city": "Moscow",
  "countryShort": "ru",
  "population": 12000000
}

Ответ состоит из четырех ключей — country, city, countryShort и population. У каждого есть свои значения. В целом — обычная JSON структура. Теперь основываясь на этом, давайте создадим PHP класс, который будет использоваться JsonMapper’ом.

Создадим новый класс, например, Country и ключи из JSON будут параметрами внутри класса:

<?php

class Country 
{

  /**
   * @var string
   */
  public $country;
  /**
   * @var string 
   */
  public $city; 
  /**
   * @var string
   */
  public $countryShort;
  /**
   * @var integer
   */
  public $population; 
}

Ключи должны называться так же как и в JSON, иначе может выдать ошибку или значения которые не в классе будут проигнорированы.

@var теги играют ключевую роль в этом классе, потому что именно они используются JsonMapper’ом, чтобы он мог понимать тип переменной. Тем самым — string будет строкой, а integer будет числом.

Вместо типа можно использовать класс — это будет означать, что внутри переменной будет еще один объект с собственными переменными, но об этом чуть позже.

Чтобы не тратить много времени на то как делать запросы к API и т.д. (ожидаю, что вы уже это сделали или знаете как делать), я буду сразу описывать с момента когда вы уже получили JSON и поместили его в какую-то локальную переменную.

Теперь самый минимальный пример использования JsonMapper’а:

<?php 

require 'JsonMapper.php';
require 'Country.php';

/**
 * Тут допустим у вам был запрос к API 
 */

$jsonResult = '{ "country": "Russia", "city": "Moscow", "countryShort": "ru", "population": 12000000 }';

$obj = json_decode($jsonResult);

$mapper = new JsonMapper();
$country = $mapper->map($obj, new Country());

Как это работает?

Мы подключили библиотеку JsonMapper, которая будет парсить JSON ответ с API и поместили этой в переменную $jsonResult. Далее, я использую json_decode() и заношу результат в новую переменную $json, чтобы сделать из обычной JSON текста PHP класс.

После этого я инициализирую JsonMapper внутри $mapper и использую метод map() с двумя аргументами:

первый — это $json (что нам вернулось из API и что мы немного подкорректировали (сделали обычным классом))
второй — это класс, который будет использоваться для парсинга

После того как JSON сделает свою работы, то в $country будет являться классов Country, включая все что есть внутри класс, а так же переменные будут иметь в себе значения из API.

Для проверки вы можете сделать var_dump() переменной $country.

В чем плюсы JsonMapper’а?

Автор библиотеки описывает следующие удобства:

Если вы используете IDE (например, PhpStorm), то она будет вам подсказывать переменные и методы классов, которые вы используется для обработки данных из API
Очень удобно добавить новые методы, которые могут помочь в обработке данные полученных с API
Ваше JSON API может поменять, но класс останется прежним. Возможно вам нужно будет добавить новые переменные или что-то подобное, но в целом структура будет неизменна, что очень удобно и не поломает текущий функционал проекта

Вкратце: Что такое JsonMapper?

Пример

В чем плюсы JsonMapper’а?

Об авторе