jsonmapper
1.0.0
JSON 웹 서비스에서 검색된 데이터를 가져와서 자체 모델 클래스를 사용하여 중첩된 개체 및 배열로 변환합니다.
기본 개체에서 시작하여 JSON 데이터를 클래스 속성에 매핑하여 올바른 단순 유형이나 개체로 변환합니다.
이는 PHP의 SoapClient 제공하는 기본 SOAP 매개변수 매핑과 약간 유사하지만 JSON의 경우입니다. 이는 어떤 스키마에도 의존하지 않으며 오직 PHP 클래스 정의에만 의존합니다.
유형 감지는 유형 선언과 클래스 속성의 @var docblock 주석뿐만 아니라 setter 메소드의 유형 힌트를 구문 분석하여 작동합니다.
JSON 관련 코드를 추가하여 모델 클래스를 수정할 필요가 없습니다. 이미 존재하는 문서 블록을 구문 분석하여 자동으로 작동합니다.
이 라이브러리에는 종속성이 없습니다.
키워드: 역직렬화, 수화
내용물
map() 에 배열 전달하기모델 클래스는 직접 작성해야 합니다.
JsonMapper는 스키마 정보(예: json-schema)에 의존하지 않으므로 모델 클래스를 자동으로 생성할 수 없습니다.
netresearch/jsonmapper 설치JsonMapper 객체 인스턴스 생성map 또는 mapArray 메소드를 호출하십시오.일반 객체 매핑:
<?php
require ' autoload.php ' ;
$ mapper = new JsonMapper ();
$ contactObject = $ mapper -> map ( $ jsonContact , new Contact ());
// or as classname
$ contactObject = $ mapper -> map ( $ jsonContact , Contact::class);객체 배열 매핑:
<?php
require ' autoload.php ' ;
$ mapper = new JsonMapper ();
$ contactsArray = $ mapper -> mapArray (
$ jsonContacts , array (), ' Contact '
); array() 대신 ArrayObject 및 파생 클래스는 물론 ArrayAccess 구현하는 클래스를 사용할 수도 있습니다.
주소록 웹 서비스의 JSON:
{
"name" : "Sheldon Cooper" ,
"address" : {
"street" : "2311 N. Los Robles Avenue" ,
"city" : "Pasadena"
}
} 귀하의 지역 Contact 수업:
<?php
class Contact
{
/**
* Full name
*/
public string $ name ;
public ? Address $ 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 여러 소스를 사용하여 다음 순서로 올바른 속성 유형을 감지합니다.
세터 메소드( set + ucwords($propertyname) )
밑줄 " _ " 및 하이픈 " - "은 다음 문자를 대문자로 만듭니다. foo_bar-baz 속성은 setter 메소드 setFooBarBaz 로 연결됩니다.
메소드 시그니처에 유형 힌트가 있는 경우 해당 유형이 사용됩니다.
공개 함수 setPerson($person에게 연락) {...}
메소드의 docblock에서 @param $type 주석이 있는지 검사합니다.
/**
* @param 연락처 $person 이 애플리케이션의 기본 연락처
*/
공개 함수 setPerson($person) {...}
유형을 감지할 수 없는 경우 일반 JSON 값이 setter 메소드에 전달됩니다.
클래스 속성 유형(PHP 7.4부터):
공개 연락처 $person;
생성자 속성 승격 유형(PHP 8.0부터):
공개 함수 __construct(보호된 연락처 $person) {}
@var $type 클래스 속성의 docblock 주석:
/** * @var myapplicationmodel연락처 */ 공개 $사람;
속성을 직접 사용하려면 공개되어야 합니다. $bIgnoreVisibility를 사용하여 보호 속성과 개인 속성을 활용할 수도 있습니다.
유형을 감지할 수 없는 경우 속성은 일반 JSON 값 세트를 가져옵니다.
속성을 찾을 수 없는 경우 JsonMapper는 대/소문자를 구분하지 않고 속성을 찾으려고 시도합니다. 그러면 JSON 속성 isempty PHP 속성 isEmpty 에 매핑됩니다.
메모
유형이 작동하려면 정규화된 네임스페이스를 제공해야 합니다. 상대 클래스 이름은 존재할 수 있는 가져오기를 고려하지 않고 현재 클래스 네임스페이스의 컨텍스트에서 평가됩니다.
PHP는 Reflection을 통한 가져오기를 제공하지 않습니다. 주석 텍스트에는 해당 유형의 리터럴 텍스트만 포함됩니다. 성능상의 이유로 JsonMapper는 가져오기를 감지하고 확장하기 위해 소스 코드를 자체적으로 구문 분석하지 않습니다.
단순 유형
stringbool , booleanint , integerdouble , floatarrayobjectmixed네임스페이스가 있거나 없는 클래스 이름
Contact - JSON 값이 null 인 경우 예외가 발생합니다.단순 유형 및 클래스 이름의 배열:
int[]Contact[]다차원 배열:
int[][]TreeDeePixel[][][]단순 유형 및 클래스 이름의 ArrayObject:
ContactList[Contact]NumberList[int]네임스페이스가 있거나 없는 지원되는 열거형
Suit:string|Suit:int- JSON 값이 열거형에 없으면 예외가 발생합니다.
Null 허용 유형:
int|null 또는 ?int - JSON의 값이 null 이면 null 이 되고, 그렇지 않으면 정수가 됩니다.Contact|null 또는 ?Contact - JSON의 값이 null 이면 null 이 되고, 그렇지 않으면 Contact 유형의 객체가 됩니다.ArrayObject 및 확장 클래스는 배열로 처리됩니다.
유형이 없거나 유형이 mixed 변수는 변환 없이 직접 JSON 값 세트를 가져옵니다.
자세한 내용은 phpdoc의 유형 문서를 참조하세요.
메모
이 기능은 버전 5부터 보안상의 이유로 기본적으로 비활성화되어 있습니다. 자세한 내용은 $bStrictObjectTypeChecking을 참조하세요.
객체를 생성해야 하지만 JSON에 단순 유형(예: 문자열, 부동 소수점, 부울)만 포함된 경우 이 값이 클래스 생성자에 전달됩니다. 예:
PHP 코드:
public DateTime $ 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 유형의 객체가 생성됩니다.
실제 구현 클래스를 동적으로 결정해야 하는 경우(예: 공용체의 경우) 콜러블을 사용하는 것도 가능합니다. 매핑된 클래스(아래 예에서는 'Foo')와 Json 데이터가 호출에 매개변수로 전달됩니다.
$ mapper = function ( $ class , $ jvalue ) {
// examine $class and $jvalue to figure out what class to use...
return ' DateTime ' ;
};
$ jm = new JsonMapper ();
$ jm -> classMap [ ' Foo ' ] = $ mapper ;
$ jm -> map (...); JsonMapper는 JSON 속성이 null 인 경우 예외를 발생시킵니다. 단, PHP 클래스 속성에 null 허용 유형(예: Contact|null 또는 ?Contact 이 있는 경우는 예외입니다.
API에 null 일 수 있는 필드가 많이 포함되어 있고 모든 유형 정의를 null 허용으로 설정하지 않으려면 다음을 설정하세요.
$ jm -> bStrictNullTypes = false ; 버전 5.0.0부터 배열의 null 값은 유형이 null을 허용하지 않는 한 JsonMapper_Exception 으로 이어집니다(예: array[?string] 또는 array[string|null] .
이전 동작을 다시 가져오려면(선언되지 않은 경우에도 null을 허용) 다음을 설정하십시오.
$ jm -> bStrictNullTypesInArrays = false ; JsonMapper의 setLogger() 메서드는 모든 PSR-3 호환 로거 인스턴스를 지원합니다.
기록되는 이벤트:
개발 중에 API가 자주 변경됩니다. 이러한 변경 사항에 대한 알림을 받으려면 데이터가 누락되었거나 아직 알려지지 않은 경우 예외를 발생시키도록 JsonMapper를 구성할 수 있습니다.
JsonMapper가 PHP 클래스에 정의되지 않은 JSON 데이터의 속성을 볼 때 $bExceptionOnUndefinedProperty 설정하여 예외를 발생시키도록 할 수 있습니다.
$ jm = new JsonMapper ();
$ jm -> bExceptionOnUndefinedProperty = true ;
$ jm -> map (...); $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 (...); 또는 JsonMapper가 setter를 처리하도록 하려면 속성 이름으로 사용될 $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 fixPropName ( $ object , $ propName , $ jsonValue )
{
return ucfirst ( $ propName );
}
$ jm = new JsonMapper ();
$ jm -> undefinedPropertyHandler = ' fixPropName ' ;
$ jm -> map (...);메모
이는 $bStrictObjectTypeChecking이 활성화된 경우에만 작동합니다.
PHP 클래스의 속성은 문서 블록에 @required 넣어 "필수"로 표시할 수 있습니다.
/**
* @var string
* @required
*/
public $ someDatum ; JSON 데이터에 이 속성이 포함되어 있지 않으면 $bExceptionOnMissingData 활성화될 때 JsonMapper가 JsonMapper_Exception 을 발생시킵니다.
$ jm = new JsonMapper ();
$ jm -> bExceptionOnMissingData = true ;
$ jm -> map (...); $bRemoveUndefinedAttributes 옵션을 사용하면 JsonMapper가 JSON 데이터에 없는 속성을 최종 객체에서 제거하게 됩니다.
$ jm = new JsonMapper ();
$ jm -> bRemoveUndefinedAttributes = true ;
$ jm -> map (...); $bIgnoreVisibility true로 설정하면 개인 및 보호 속성과 setter 메서드에 대한 매핑을 허용할 수 있습니다.
$ jm = new JsonMapper ();
$ jm -> bIgnoreVisibility = true ;
$ jm -> map (...); 변수 유형이 클래스이고 JSON 데이터가 string 같은 단순 유형인 경우 JsonMapper는 그렇게 구성되면 이 값을 클래스 생성자에 전달할 수 있습니다.
$ jm = new JsonMapper ();
$ jm -> bStrictObjectTypeChecking = false ;
$ jm -> map (...);이는 날짜 문자열에서 DateTime 객체를 자동으로 초기화하는 데 사용할 수 있습니다.
하지만 이 엄격한 객체 유형 검사를 비활성화하면 문제가 발생할 수 있습니다.
@required 속성은 채워지지 않습니다.메모
보안을 강화하기 위해 버전 5에서는 기본값이 false 에서 true 로 변경되었습니다.
이제 클래스 생성자에 간단한 유형을 전달하려면 선택해야 합니다.
map() 에 배열 전달하기 호출하여 얻은 map() 에 배열 데이터를 전달할 수 있습니다.
json_decode ( $ jsonString , true ) 기본적으로 JsonMapper는 map() 에 첫 번째 매개변수로 객체가 필요하기 때문에 예외를 발생시킵니다. $bEnforceMapType false 로 설정하면 이를 피할 수 있습니다.
$ jm = new JsonMapper ();
$ jm -> bEnforceMapType = false ;
$ jm -> map (...);JsonMapper는 매핑이 완료된 후 각 객체에서 직접 사용자 정의 메서드를 호출할 수 있습니다.
$ jm = new JsonMapper ();
$ jm -> postMappingMethod = ' afterMapping ' ;
$ jm -> map (...); 이제 매핑된 각 객체에서 afterMapping() 이 호출됩니다(클래스에 해당 메서드가 있는 경우).
사후 매핑 콜백에 추가 인수를 전달할 수 있습니다.
$ jm = new JsonMapper ();
$ jm -> postMappingMethod = ' afterMapping ' ;
$ jm -> postMappingMethodArguments = [ 23 , ' foo ' ];
$ jm -> map (...);Packagist의 Composer를 통해:
$ 작곡가에는 netresearch/jsonmapper가 필요합니다.
대안
JsonMapper는 OSL 3.0에 따라 라이센스가 부여됩니다.
JsonMapper는 PEAR 코딩 표준을 따릅니다.
크리스티안 바이스케(cweiske.de)
