dataclass

Perpustakaan dataclass PHP

dataclass memungkinkan Anda dengan cepat mengubah array biasa ke kelas PHP yang diberi petunjuk tipe dengan denormalisasi otomatis objek dan koleksi yang disematkan yang biasanya memerlukan banyak pekerjaan jika Anda menggunakan normalizer dan denormalizer. Perpustakaan terinspirasi oleh modul Python pydantic. Ini menggunakan kekuatan petunjuk tipe yang tersedia sejak PHP 7.4.

Tujuan utama dari paket ini adalah untuk menyediakan cara cepat untuk memiliki kelas dengan petunjuk tipe yang ketat untuk penggunaan lebih lanjut, misalnya untuk memetakan payload permintaan ke kelas yang diketik secara ketat sehingga Anda dapat menggunakannya sebagai pengganti array yang mungkin cocok atau tidak sesuai dengan kebutuhan Anda. Ini tidak akan menggantikan validasi data Anda tetapi akan memastikan Anda bahwa fx menerima payload JSON cocok dengan jenis yang diharapkan diterima oleh operasi backend Anda. Ini seperti yang disebutkan di atas antarmuka BaseModel atau TypeScript pydantic.

Yang Anda perlukan hanyalah membuat satu atau dua kelas:

 declare (strict_types= 1 );

class MyEmbededClass
{
    public float $ number ;
}

class MyClass
{
    public int $ number ;
    public ? string $ optionalText = null ;
    public MyEmbededClass $ embeded ;
}

Sebagai langkah selanjutnya, masukkan nama kelas utama dan data yang diterima, misalnya dari JSON yang diterima ke metode transform :

 $ data = ' {
    "number": 1,
    "embeded": {
        "number": 1.23
    }
} ' ;
$ object = transform (MyClass::class, json_decode ( $ data , true ));

Untuk memetakan data yang diterima dengan cepat ke dataclass yang berfungsi penuh :

 var_dump ( $ object )

 object (MyClass) {
  [ " number " ]=> int( 1 )
  [ " optionalText " ]=> NULL
  [ " embeded " ]=>
  object(MyEmbededClass) {
    [ " number " ]=>
    float( 1.23 )
  }
}

Anda tidak perlu khawatir meneruskan null dari json_decode , ini akan memunculkan TransformException untuk bidang root jika terdeteksi.

Anda tidak perlu khawatir tentang bidang yang hilang dan tipe yang tidak valid karena perpustakaan mendeteksi semua persyaratan yang diberi petunjuk tipe dan menampilkan TransformException dengan kesalahan (siap disajikan sebagai respons) yang menunjuk ke bidang yang tepat dengan pesan alasan sederhana, misalnya:

 echo json_encode ( $ transformException , JSON_PRETTY_PRINT )

{
    "errors" : [
        {
            "field" : " optionalText " ,
            "reason" : " Field must have value "
        },
        {
            "field" : " embeded " ,
            "reason" : " Field must have value "
        }
    ]
}

Anda juga dapat menggunakan metode Transform::to yang sebenarnya disebut dengan fungsi pembantu transform . Fungsi pembantu akan selalu menggunakan pengaturan optimal untuk objek Transform (segera setelah muncul).

 $ data = ' {
    "number": 1,
    "embeded": {
        "number": 1.23
    }
} ' ;
$ transformer = new Transform ();
$ object = $ transformer -> to (MyClass::class, json_decode ( $ data , true ));

Konstruktor

Jika Anda perlu menggunakan konstruktor dengan argumen yang diberi petunjuk tipe, Anda dapat melakukannya, tetapi dengan cara yang terbatas. Pustaka hanya mendukung pengisian argumen konstruktor dengan nilai dari payload. Artinya konstruktor harus menggunakan tipe dan nama variabel yang sama dengan properti kelas. Misalnya:

 class MyClass
{
    public float $ number ;
    public ? int $ numberTwo = null ;

    public function __construct ( float $ number )
    {
        $ this -> number = $ number ;
    }
}

Menggunakan nama atau tipe berbeda untuk argumen konstruktor tidak akan berhasil. Tujuannya untuk mendukung penegakan pengembang untuk mengisi properti.

Konstruktor apa pun yang berisi parameter selain properti akan menampilkan UnsupportedException . Parameter harus memiliki tipe yang sama dengan properti. Urutan tidak relevan. Jika diperlukan, hanya beberapa subset properti yang dapat ada di konstruktor.

Lebih banyak contoh

Silakan periksa direktori docs/ untuk contoh lebih lanjut.

Instalasi

Sesederhana

 composer install rutek/ dataclass

Petunjuk jenis yang didukung

Perhatian: harap berhati-hati dalam menggunakan petunjuk tipe array . Mereka tidak dapat digunakan (akan memunculkan UnsupportedException jika terdeteksi) karena PHP tidak menyediakan cara untuk mengetikkan item petunjuk dalam array. Silakan periksa bagian Koleksi di bawah untuk informasi lebih lanjut.

Skalar

Keempat skalar PHP didukung.

Bidang yang tidak dapat dibatalkan

Nullabilitas petunjuk ketik didukung. Anda dapat dengan aman menggunakan misalnya ?string untuk menerima string dan null . Perlu diketahui karena hanya menggunakan ?string $field tidak berarti bahwa array yang diubah tidak boleh berisi bidang ini. Ini hanya berarti bahwa nilai ini menerima null .

Nilai bawaan

Jika Anda perlu menerima transformasi data yang tidak berisi beberapa bidang, Anda dapat menggunakan nilai default, misalnya: ?string $field = null . perpustakaan dataclass akan mendeteksi bahwa properti ini tidak ada di payload dan sebagai gantinya akan menggunakan nilai default.

Koleksi

PHP tidak mendukung bidang array petunjuk tipe jika Anda perlu menyematkan koleksi objek atau skalar, Anda harus menggunakan kelas Collection . Anda perlu memperluasnya dengan konstruktor dengan dekonstruksi argumen yang diberi petunjuk tipe, misalnya:

 class Tags extends Collection
{
    public function __construct ( string ... $ names )
    {
        $ this -> items = $ names ;
    }
}

Array dengan petunjuk tipe seperti string[] ditolak di RFC jadi mungkin perilaku ini tidak akan segera berubah.

Perpustakaan akan memeriksa apakah nilai yang diberikan cocok dengan petunjuk tipe konstruktor.

Tidak ada kemungkinan untuk memeriksa item minimum dan maksimum tetapi mungkin ada fitur seperti itu di versi berikutnya.

Harap dicatat bahwa Anda juga dapat menggunakan Koleksi sebagai kelas dasar yang ingin Anda ubah, misalnya:

 $ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);

Pengecualian

TransformException - data tidak cocok dengan skema Anda

Ini adalah pengecualian dasar yang dapat Anda harapkan. Setiap kali data Anda (payload) diteruskan ke fungsi transform(string $class, $data) atau Transform::to tidak akan cocok dengan kelas yang Anda ketikkan, Anda akan menerima TransformException dengan metode getErrors(): FieldError[] yang menjelaskan apa yang sebenarnya telah terjadi.

Setiap FieldError berisi field yang menjelaskan bidang mana yang gagal dalam pemeriksaan jenis dan reason yang menjelaskan dengan kata-kata sederhana mengapa bidang tersebut ditolak. Jika ada objek bertumpuk, Anda akan menerima nilai field seperti parentProperty.childrenProperty (level dipisahkan dengan titik).

Kelas mendukung serialisasi JSON dan akan selalu mengembalikan sesuatu seperti:

{
    "errors" : [
        {
            "field" : " optionalText " ,
            "reason" : " Field must have value "
        },
        {
            "field" : " embeded " ,
            "reason" : " Field must have value "
        }
    ]
}

Harap dicatat bahwa bidang code dapat ditambahkan di masa depan.

UnsupportedException - hanya jika petunjuk tipe Anda tidak didukung

Perpustakaan tidak mencakup semua skenario karena Anda dapat menentukan petunjuk tipe yang tidak memiliki konteks ketat. Misalnya jika Anda menggunakan properti object , tidak mungkin memvalidasinya karena objek apa pun akan cocok dengan skema Anda. Dalam kasus seperti ini, Anda dapat mengharapkan UnsupportedException .

Tidak didukung (belum?)

Jenis persimpangan dan serikat pekerja

Tipe gabungan PHP 8.0 dan tipe persimpangan PHP 8.1 saat ini tidak didukung.

Enum

Enum asli PHP 8.1 tidak didukung saat ini.

Properti pribadi dan dilindungi

Semua bidang yang diberi petunjuk ketik harus bersifat publik seperti untuk saat ini. Menerapkan fitur seperti itu patut dipertanyakan karena Anda harus membuat pengambil untuk properti tersebut yang merupakan overhead yang tidak diinginkan. Perpustakaan dimaksudkan untuk menciptakan kemungkinan untuk menentukan skema internal untuk data yang diterima dari sistem jarak jauh (API, antrian/pesan bus, browser).

Cache refleksi

Semua pemeriksaan refleksi dilakukan setiap kali transform atau Transform::to dipanggil. Anda dapat segera mengharapkan fungsionalitas caching untuk kinerja yang lebih baik.

Perkataan

Harap diingat bahwa tujuan paket ini bukan untuk sepenuhnya memvalidasi data yang Anda terima tetapi untuk membuat kelas sederhana yang membuat payload Anda sepenuhnya diberi petunjuk ketika mereka memiliki struktur yang rumit. Anda tidak perlu menyandikan kelas Anda di JSON dengan bidang class karena petunjuk tipe Anda akan memberi tahu kode Anda objek atau larik apa yang harus dibuat sebagai pengganti beberapa nilai yang disematkan.

Jika Anda membuat API dan memerlukan validasi skema OpenAPI tingkat perusahaan, Anda harus memeriksa hkarlstrom/openapi-validation-middleware dan setelah itu Anda dapat memetakan payload yang diterima ke kelas yang diberi petunjuk menggunakan perpustakaan ini! :)