dataclass
v0.1.2: Support for constructor parameters
dataclass 사용하면 정규화 도구와 비정규화 도구를 사용하는 경우 일반적으로 많은 작업이 필요한 포함된 개체 및 컬렉션의 자동 비정규화를 사용하여 일반 array 유형 힌트 PHP 클래스로 신속하게 변경할 수 있습니다. 라이브러리는 Python pydantic 모듈에서 영감을 받았습니다. PHP 7.4부터 사용할 수 있는 유형 힌트 기능을 사용합니다.
이 패키지의 주요 목표는 추가 사용을 위해 엄격한 유형 힌트 클래스를 갖는 빠른 방법을 제공하는 것입니다. 예를 들어 요청 페이로드를 엄격한 유형의 클래스에 매핑하여 요구 사항과 일치하거나 일치하지 않을 수 있는 배열 대신 사용할 수 있도록 하는 것입니다. 데이터 검증을 대체하지는 않지만 fx가 수신한 JSON 페이로드가 백엔드 작업에서 수신할 것으로 예상되는 유형과 일치하는지 확인합니다. 위에서 언급한 pydantic BaseModel 또는 TypeScript 인터페이스와 같습니다.
필요한 것은 클래스를 한두 개 만드는 것뿐입니다.
declare (strict_types= 1 );
class MyEmbededClass
{
public float $ number ;
}
class MyClass
{
public int $ number ;
public ? string $ optionalText = null ;
public MyEmbededClass $ embeded ;
} 다음 단계에서는 기본 클래스 이름과 수신된 데이터를 전달합니다(예: 수신된 JSON에서 transform 메서드로).
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ object = transform (MyClass::class, json_decode ( $ data , true ));수신된 데이터를 완전히 작동하는 dataclass 에 신속하게 매핑하려면 다음을 수행하세요.
var_dump ( $ object ) object (MyClass) {
[ " number " ]=> int( 1 )
[ " optionalText " ]=> NULL
[ " embeded " ]=>
object(MyEmbededClass) {
[ " number " ]=>
float( 1.23 )
}
} json_decode 에서 null 전달하는 것에 대해 걱정할 필요가 없습니다. null이 감지되면 root 필드에 대해 TransformException 발생합니다.
라이브러리는 모든 유형 힌트 요구 사항을 감지하고 간단한 이유 메시지와 함께 정확한 필드를 가리키는 오류(응답으로 제공될 준비가 됨)와 함께 TransformException 발생시키므로 누락된 필드 및 유효하지 않은 유형에 대해 걱정할 필요가 없습니다. 예:
echo json_encode ( $ transformException , JSON_PRETTY_PRINT ){
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} 실제로 transform 도우미 함수에 의해 호출되는 Transform::to 메서드를 사용할 수도 있습니다. 도우미 기능은 항상 Transform 개체에 대한 최적의 설정을 사용합니다(표시되는 즉시).
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ transformer = new Transform ();
$ object = $ transformer -> to (MyClass::class, json_decode ( $ data , true ));유형 힌트 인수와 함께 생성자를 사용해야 하는 경우 그렇게 할 수 있지만 방법이 제한됩니다. 라이브러리는 페이로드의 값으로 생성자 인수 채우기만 지원합니다. 이는 생성자가 클래스 속성과 동일한 유형 및 변수 이름을 사용해야 함을 의미합니다. 예를 들어:
class MyClass
{
public float $ number ;
public ? int $ numberTwo = null ;
public function __construct ( float $ number )
{
$ this -> number = $ number ;
}
}생성자 인수에 다른 이름이나 유형을 사용하면 작동하지 않습니다. 목표는 개발자가 속성을 입력하도록 지원하는 것입니다.
속성 이외의 다른 매개변수를 포함하는 생성자는 UnsupportedException 발생시킵니다. 매개변수는 속성과 동일한 유형을 가져야 합니다. 순서는 상관없습니다. 필요한 경우 속성의 일부 하위 집합만 생성자에 존재할 수 있습니다.
더 많은 예제를 보려면 docs/ 디렉토리를 확인하세요.
다음과 같이 간단하게
composer install rutek/ dataclass
주의: array 유형 힌트 사용에 유의하세요. PHP는 배열 항목에 대한 유형 힌트 방법을 제공하지 않으므로 사용할 수 없습니다(감지되면 UnsupportedException 발생합니다). 자세한 내용은 아래 컬렉션 섹션을 확인하세요.
4개의 PHP 스칼라가 모두 지원됩니다.
유형 힌트 null 허용 여부가 지원됩니다. 예를 들어 ?string 사용하면 string 과 null 모두 허용할 수 있습니다. ?string $field 만 사용한다고 해서 변환된 배열에 이 필드가 포함되지 않을 수 있다는 의미는 아닙니다. 이는 이 값이 null 허용한다는 의미일 뿐입니다.
일부 필드를 포함하지 않는 데이터 변환을 허용해야 하는 경우 기본값을 사용할 수 있습니다(예: ?string $field = null . dataclass 라이브러리는 이 속성이 페이로드에 존재하지 않음을 감지하고 대신 기본값을 사용합니다.
Collection 클래스를 사용해야 하는 객체 컬렉션이나 스칼라를 포함해야 하는 경우 PHP는 유형 힌트 array 필드를 지원하지 않습니다. 유형 힌트 인수 분해를 사용하여 생성자를 사용하여 확장해야 합니다. 예를 들면 다음과 같습니다.
class Tags extends Collection
{
public function __construct ( string ... $ names )
{
$ this -> items = $ names ;
}
} string[] 과 같은 유형 힌트 배열은 RFC에서 거부되었으므로 이 동작은 곧 변경되지 않을 것입니다.
라이브러리는 제공된 값이 생성자의 유형 힌트와 일치하는지 확인합니다.
최소 및 최대 항목을 확인할 수는 없지만 다음 버전에서는 해당 기능이 있을 수 있습니다.
변환하려는 기본 클래스로 Collection을 사용할 수도 있습니다. 예를 들면 다음과 같습니다.
$ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);TransformException - 데이터가 스키마와 일치하지 않습니다. 이는 예상할 수 있는 기본 예외입니다. 함수 transform(string $class, $data) 또는 Transform::to 에 전달된 데이터(페이로드)가 유형 힌트 클래스와 일치하지 않을 때마다 실제로 무엇을 설명하는 getErrors(): FieldError[] 메소드를 사용하여 TransformException 받게 됩니다. 일어났다.
모든 FieldError 에는 유형 검사에 실패한 필드를 설명하는 field 와 해당 필드가 거부된 reason 간단한 단어로 설명하는 필드가 모두 포함되어 있습니다. 중첩된 개체가 있는 경우 parentProperty.childrenProperty (점으로 구분된 수준)와 같은 field 값을 받을 것으로 예상할 수 있습니다.
클래스는 JSON 직렬화를 지원하며 항상 다음과 같은 것을 반환합니다.
{
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} 향후 code 필드가 추가될 수 있습니다.
UnsupportedException - 유형 힌트가 지원되지 않는 경우에만 해당 엄격한 컨텍스트가 없는 유형 힌트를 정의할 수 있으므로 라이브러리는 모든 시나리오를 다루지는 않습니다. 예를 들어 object 속성을 사용하는 경우 개체가 스키마와 일치하므로 유효성을 검사할 수 없습니다. 이러한 경우 UnsupportedException 발생할 수 있습니다.
PHP 8.0 통합 유형 및 PHP 8.1 교차 유형은 현재 지원되지 않습니다.
기본 PHP 8.1 열거형은 현재 지원되지 않습니다.
현재로서는 모든 유형 힌트 필드가 공개되어야 합니다. 원하지 않는 오버헤드를 초래하는 속성에 대한 getter를 생성해야 하므로 이러한 기능을 구현하는 것은 의심스럽습니다. 라이브러리는 원격 시스템(API, 큐/버스 메시지, 브라우저)에서 수신된 데이터에 대한 내부 스키마를 정의할 수 있는 가능성을 생성하기 위한 것입니다.
모든 반사 검사는 transform 또는 Transform::to 함수가 호출될 때마다 수행됩니다. 곧 더 나은 성능을 위한 캐싱 기능을 기대할 수 있습니다.
이 패키지의 목표는 수신한 데이터의 유효성을 완전히 검사하는 것이 아니라 페이로드가 복잡한 구조를 가지고 있는 경우에도 페이로드를 완전히 유형 힌트로 만드는 간단한 클래스를 만드는 것임을 기억하세요. 유형 힌트가 일부 포함된 값 대신 어떤 객체 또는 배열을 생성해야 하는지 코드에 알려주기 때문에 class 필드를 사용하여 JSON으로 클래스를 인코딩할 필요가 없습니다.
API를 생성 중이고 엔터프라이즈급 OpenAPI 스키마 검증이 필요한 경우 hkarlstrom/openapi-validation-middleware를 확인해야 하며 이후에 이 라이브러리를 사용하여 수신된 페이로드를 유형 힌트 클래스에 매핑할 수 있습니다! :)
