Jak jedną biblioteką rozwiązać wiele problemów?

Korzystając z JsonMapper, można dostarczyć oprogramowanie szybciej, z mniejszą liczbą błędów i prostsze w modyfikacji.

JsonMapper to biblioteka, której zadaniem jest mapowanie obiektów stdClass oraz tablic, na konkretne typy klas wraz z zachowaniem typów właściwości zdeklarowanych PHPDocem w tychże klasach.

 

Ta czynność daje nam wiele zalet:

  • mamy określoną strukturę na której pracuje dalej kod, przez co łatwo dowiedzieć się jakie pola są przekazywane, oraz jak się powinny nazywać i jakiego być typu
  • w IDE zyskujemy automatyczne podpowiadanie składni
  • świadomość na jakich danych pracujemy
  • możliwość wstępnego oczyszczenia danych – zostaną tylko te które mamy zdefiniowane i programista o nich wie
  • szybsze wykrywanie błędów – już na poziomie mapowania możemy odkryć błąd
  • “dokumentacja” czego się spodziewamy w danym komunikacie
  • jeżeli zajdzie potrzeba rozbudowy API, będziemy mieć dalej opisane struktury oddzielone od pozostałego kodu, który na nich operuje (możemy dodać wiele API)

Wady:

  • trzeba napisać struktury
  • brak wbudowanej walidacji

 

Instalacja
Skrypt napisany jest z zachowaniem standardu PSR-0, co ułatwia nam wczytywanie klas. Ponadto wspiera także Composer’a, co sprawia że bajecznie prosto się z niego korzysta.
Wystarczy dodać ręcznie `require` w `composer.json` lub wykonać polecenie:

 

$ composer require netresearch/jsonmapper

 

Pierwsze uruchomienie

Jeżeli zdecydowaliśmy się na wariant instalacji z wykorzystaniem Composer’a, pozostaje nam stworzyć plik który:

  • dołączył utworzony autoload.php
  • utworzymy klasę do której chcemy zmapować dane
  • utworzymy zmienną przechowującą dane, które chcemy zmapować do obiektu danego typu
  • utworzymy JsonMapper, oraz wykonany na nim metodę `map()`. W pierwszym argumencie podajemy dane, natomiast w drugim obiekt do którego chcemy te dane zmapować, w rezultacie metoda zwraca nam obiekt z ustawionymi danymi.

<?php

require ‚vendor/autoload.php’;

class Contact

{

}

$jsonContact = json_decode(‚{}’);

$mapper = new JsonMapper();

$contactObject = $mapper->map($jsonContact, new Contact());

 

Rezultatem działania skryptu będzie przypisany obiekt `Contact` do zmiennej `$contactObject` z ustawionymi wartościami z `$jsonContact` – dla uproszczenia pierwszego przykładu nie są ustawione żadne dane, ponieważ `Contact` nie ma zdefiniowanych żadnych atrybutów, oraz `$jsonContact` też jest pustym obiektem `stdClass`.

 

Przykład z życia

Rozbudujemy wcześniejszy przykład, powiedzmy że frontend będzie przesyłał nam kontakt, który będzie zawierał nazwę, oraz adres. Adres będzie się składał z ulicy oraz miasta. Całość można opisać poniższymi klasami.

class Contact

{

/**

* @var string

*/

public $name;

/**

* @var Address

*/

public $address;

}

class Address

{

/**

* @var string

*/

public $street;

/**

* @var string

*/

public $city;

}

Więc przykładowo JSON przekazany nam przez frontend powinien wyglądać tak:

{

   „name”: „MENTAX SA”,

   „address”: {

       „street”: „Szczecińska 25a\/5”,

       „city”: „Koszalin”

   }

}

Aby nasz skrypt zadziałał musimy przygotować następujący kod:

<?php

require ‚vendor/autoload.php’;

class Contact

{

/**

* @var string

*/

public $name;

/**

* @var Address

*/

public $address;

}

class Address

{

/**

* @var string

*/

public $street;

/**

* @var string

*/

public $city;

}

$json = <<<JSON

{

   „name”: „MENTAX SA”,

   „address”: {

       „street”: „Szczecińska 25a\/5”,

       „city”: „Koszalin”

   }

}

JSON;

$jsonContact = json_decode($json);

$mapper = new JsonMapper();

$contactObject = $mapper->map($jsonContact, new Contact());

Teraz pod zmienna `$contactObject` mamy faktycznie `Contact` ze zmapowanymi odpowiednio polami:

„`
object(Contact)[7]

 public ‚name’ => string ‚MENTAX SA’ (length=9)

 public ‚address’ =>

   object(Address)[12]

     public ‚street’ => string ‚Szczecińska 25a/5’ (length=17)

     public ‚city’ => string ‚Koszalin’ (length=8)

„`

Teraz wystarczy, albo uzupełnić PHPDoc, albo zapakować w funkcję/metodę i możemy się cieszyć podpowiadaniem składni i jasno zdefiniowanymi polami.

 

Alternatywne zastosowania
Pomimo nazwy JsonMapper, poza samym JSON’em sprawdza się on też całkiem nieźle we wszystkich miejscach gdzie normalnie operujemy na tablicach albo obiektach stdClass. Formularze, obróbka danych z różnych źródeł, pliki konfiguracyjne, dane pozyskiwane z RPC wszędzie tam może pomóc nam JsonMapper.

Projekt jest dobrze udokumentowany także zachęcam zapoznać się z jego stronie na github’ie.

Przedstawię przykład jak można przy pomocy JsonMappera określić jakie pola powinny zostać przekazywane nam przez formularz. Jako że metoda `map()` jako pierwszy parametr w phpDoc ma określony typ object, musimy skonfigurować naszą instalację JsonMapper tak żeby pozwalała przyjmować inne typy, co umożliwi nam pracę z interesującą nas tablicą.

„`

<?php

require ‚vendor/autoload.php’;

class Address

{

/**

* @var string

*/

public $street;

/**

* @var string

*/

public $city;

}

$_POST[‚street’] = ‚Ulica’;

$_POST[‚city’] = ‚Miasto’;

$mapper = new JsonMapper();

$mapper->bEnforceMapType = false; // Zezwalaj na przekazywanie tablicy

$addressObject = $mapper->map($_POST, new Address());

„`

Po tym działaniu mamy w pełni przygotowany obiekt Adress w którym są ustawione odpowiednie pola oraz zachowane typy dla nich.

Więcej informacji znajdziemy na stronie projektu: https://github.com/cweiske/jsonmapper

Autor: Paweł Halicki


Opublikowano:

Mentax na Facebook'u