streaming json encoder

streaming json encoder

streaming json encoder เป็นไลบรารี PHP ที่มีชุดคลาสเพื่อช่วยในการเข้ารหัส JSON ในลักษณะสตรีมมิ่ง กล่าวคือ ช่วยให้คุณสามารถเข้ารหัสเอกสาร JSON ทีละบิต แทนที่จะเข้ารหัสทั้งเอกสารในคราวเดียว เมื่อเปรียบเทียบกับฟังก์ชัน json_encode ในตัว มีข้อดีหลักๆ อยู่ 2 ประการ:

• คุณไม่จำเป็นต้องโหลดชุดข้อมูลทั้งหมดลงในหน่วยความจำ เนื่องจากตัวเข้ารหัสรองรับการวนซ้ำทั้งอาร์เรย์และตัววนซ้ำประเภทอื่นๆ เช่น ตัวสร้าง เป็นต้น
• คุณไม่จำเป็นต้องโหลดเอกสาร JSON ที่เป็นผลลัพธ์ทั้งหมดลงในหน่วยความจำ เนื่องจากเอกสาร JSON จะถูกเข้ารหัสตามค่า และเป็นไปได้ที่จะส่งออกเอกสารที่เข้ารหัสทีละชิ้น

กล่าวอีกนัยหนึ่ง streaming json encoder สามารถให้ประโยชน์สูงสุดเมื่อคุณต้องการจัดการชุดข้อมูลขนาดใหญ่ที่อาจใช้หน่วยความจำมากเกินไปในการประมวลผล

เพื่อเพิ่มความสามารถในการทำงานร่วมกัน ไลบรารียังมีสตรีมที่เข้ากันได้กับ PSR-7 เพื่อใช้กับเฟรมเวิร์กและคำขอ HTTP

เอกสาร API มีอยู่ที่: http://violet.riimu.net/api/streaming-json-encoder/

ความต้องการ

• เวอร์ชัน PHP ขั้นต่ำที่รองรับคือ 5.6
• ไลบรารีจะขึ้นอยู่กับไลบรารี PHP ภายนอกต่อไปนี้:
  • ข้อความ psr/http ( ^1.0 )

การติดตั้ง

การติดตั้งด้วย Composer

วิธีที่ง่ายที่สุดในการติดตั้งไลบรารีนี้คือการใช้ Composer เพื่อจัดการการขึ้นต่อกันของคุณ ในการติดตั้งไลบรารีนี้ผ่าน Composer เพียงปฏิบัติตามสองขั้นตอนเหล่านี้:

1. รับ composer.phar โดยการรันการติดตั้งบรรทัดคำสั่ง Composer ในรูทโปรเจ็กต์ของคุณ

2. เมื่อคุณรันสคริปต์การติดตั้งแล้ว คุณควรมีไฟล์ composer.phar ในโปรเจ็กต์รูทของคุณ และคุณสามารถรันคำสั่งต่อไปนี้:

    php composer.phar require "violet/streaming-json-encoder:^1.1"
   

หลังจากติดตั้งไลบรารีนี้ผ่าน Composer คุณสามารถโหลดไลบรารีโดยรวมไฟล์ vendor/autoload.php ที่สร้างโดย Composer ระหว่างการติดตั้ง

การเพิ่มไลบรารีเป็นการพึ่งพา

หากคุณคุ้นเคยกับวิธีใช้ Composer อยู่แล้ว คุณสามารถเพิ่มไลบรารีเป็นการพึ่งพาได้โดยการเพิ่มไฟล์ composer.json ต่อไปนี้ในโปรเจ็กต์ของคุณ และรันคำสั่ง composer install :

{
    "require" : {
        "violet/streaming-json-encoder" : " ^1.1 "
    }
}

การติดตั้งด้วยตนเอง

หากคุณไม่ต้องการใช้ Composer เพื่อโหลดไลบรารี คุณสามารถดาวน์โหลดไลบรารีได้ด้วยตนเองโดยการดาวน์โหลดรุ่นล่าสุดและแยกโฟลเดอร์ src ไปยังโปรเจ็กต์ของคุณ จากนั้นคุณอาจรวมไฟล์ src/autoload.php ที่ให้มาเพื่อโหลดคลาสไลบรารี

โปรดทราบว่าการใช้ Composer จะดาวน์โหลดไลบรารี PHP ที่จำเป็นอื่นๆ โดยอัตโนมัติด้วย หากคุณติดตั้งไลบรารีนี้ด้วยตนเอง คุณจะต้องทำให้ไลบรารีที่จำเป็นอื่นๆ เหล่านั้นพร้อมใช้งานด้วย

การใช้งาน

ไลบรารีนี้นำเสนอ 3 วิธีหลักในการใช้ไลบรารีผ่านคลาส BufferJsonEncoder , StreamJsonEncoder และ JsonStream สตรีมที่เข้ากันได้กับ PSR-7

การใช้ BufferJsonEncoder

ตัวเข้ารหัสบัฟเฟอร์มีประโยชน์มากที่สุดเมื่อคุณต้องการสร้างเอกสาร JSON ในลักษณะที่ไม่เกี่ยวข้องกับการส่งผ่านการโทรกลับเพื่อจัดการ JSON ที่สร้างขึ้น

วิธีที่ง่ายที่สุดในการใช้ BufferJsonEncoder คือการสร้างอินสแตนซ์ด้วยค่า JSON เพื่อเข้ารหัสและเรียกใช้เมธอด encode() เพื่อส่งคืนเอาต์พุตทั้งหมดเป็นสตริง:

 <?php

require ' vendor/autoload.php ' ;

$ encoder = new  Violet  StreamingJsonEncoder  BufferJsonEncoder ([ ' array_value ' ]);
echo $ encoder -> encode ();

อย่างไรก็ตาม วิธีที่มีประโยชน์ที่สุดในการใช้ตัวเข้ารหัสนี้คือการใช้เป็นตัววนซ้ำ ในขณะที่ตัวเข้ารหัสใช้อินเทอร์เฟซ Iterator คุณสามารถวนซ้ำ JSON ที่สร้างขึ้นด้วยการวนซ้ำ foreach:

 <?php

require ' vendor/autoload.php ' ;

$ encoder = new  Violet  StreamingJsonEncoder  BufferJsonEncoder ( range ( 0 , 10 ));

foreach ( $ encoder as $ string ) {
    echo $ string ;
}

นอกจากนี้ยังเป็นที่น่าสังเกตว่าตัวเข้ารหัสรองรับตัววนซ้ำสำหรับค่าต่างๆ ยิ่งไปกว่านั้น การปิดใดๆ ที่ส่งผ่านไปยังตัวเข้ารหัสจะถูกเรียกเช่นกัน และค่าที่ส่งคืนจะถูกใช้เป็นค่าแทน ตัวอย่างก่อนหน้านี้สามารถเขียนเป็น:

 <?php

require ' vendor/autoload.php ' ;

$ encoder = new  Violet  StreamingJsonEncoder  BufferJsonEncoder ( function () {
    for ( $ i = 0 ; $ i <= 10 ; $ i ++) {
        yield $ i ;
    }
});

foreach ( $ encoder as $ string ) {
    echo $ string ;
}

ตามหมายเหตุด้านข้าง ตัวเข้ารหัสจะเคารพอินเทอร์เฟซ JsonSerializable เช่นกัน และจะเรียก jsonSerialize สำหรับอ็อบเจ็กต์ที่ใช้อินเทอร์เฟซ

การใช้ StreamJsonEncoder

ตัวเข้ารหัสสตรีมทำงานคล้ายกับ BufferJsonEncoder มาก เนื่องจากขยายคลาสนามธรรมเดียวกัน อย่างไรก็ตาม ข้อแตกต่างที่สำคัญอยู่ที่วิธีจัดการการส่งผ่านเอาต์พุต JSON

StreamJsonEncoder ยอมรับ callable เป็นอาร์กิวเมนต์ตัวสร้างที่สอง เมื่อใดก็ตามที่จำเป็นต้องส่งออก JSON การเรียกนี้จะถูกเรียกด้วยสองอาร์กิวเมนต์ ได้แก่ สตริงจริงที่จะส่งออก และประเภทของโทเค็นที่จะส่งออก (ซึ่งเป็นหนึ่งในค่าคง JsonToken )

หากไม่มีการส่งผ่านการโทร StreamJsonEncoder จะส่งออก JSON โดยใช้คำสั่ง echo ตัวอย่างเช่น:

 <?php

require ' vendor/autoload.php ' ;

$ encoder = new  Violet  StreamingJsonEncoder  StreamJsonEncoder ([ ' array_value ' ]);
$ encoder -> encode ();

เมธอด encode() ใน StreamJsonEncoder ส่งคืนจำนวนไบต์ทั้งหมดที่ส่งผ่านไปยังเอาต์พุต ตัวเข้ารหัสนี้ทำให้สะดวก เช่น ในการเขียน JSON ลงในไฟล์ในลักษณะสตรีมมิ่ง ตัวอย่างเช่น:

 <?php

require ' vendor/autoload.php ' ;

$ fp = fopen ( ' test.json ' , ' wb ' );
$ encoder = new  Violet  StreamingJsonEncoder  StreamJsonEncoder (
    range ( 1 , 100 ),
    function ( $ json ) use ( $ fp ) {
        fwrite ( $ fp , $ json );
    }
);

$ encoder -> encode ();
fclose ( $ fp );

การใช้ JsonStream

คลาสสตรีมมี StreamInterface ที่เข้ากันได้กับ PSR-7 สำหรับการสตรีมเนื้อหา JSON จริงๆ แล้ว มันใช้ BufferJsonEncoder เพื่อทำงานหนักและเพียงแค่ตัดสายในกระแสเหมือนแฟชั่น

ตัวสร้างของ JsonStream ยอมรับค่าที่จะเข้ารหัสเป็น JSON หรืออินสแตนซ์ของ BufferJsonEncoder (ซึ่งอนุญาตให้คุณตั้งค่าตัวเลือกการเข้ารหัส) จากนั้นคุณสามารถดำเนินการสตรีมโดยใช้วิธีการที่ได้รับจากอินเทอร์เฟซ PSR-7 ตัวอย่างเช่น:

 <?php

require ' vendor/autoload.php ' ;

$ iterator = function () {
    foreach ( new DirectoryIterator ( __DIR__ ) as $ file ) {
        yield $ file -> getFilename ();
    }
};

$ encoder = ( new  Violet  StreamingJsonEncoder  BufferJsonEncoder ( $ iterator ))
    -> setOptions ( JSON_PRETTY_PRINT );

$ stream = new  Violet  StreamingJsonEncoder  JsonStream ( $ encoder );

while (! $ stream -> eof ()) {
    echo $ stream -> read ( 1024 * 8 );
}

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการสตรีม PSR-7 โปรดดูเอกสารประกอบของ PSR-7

วิธีที่ตัวเข้ารหัสแก้ไขค่า

ในหลาย ๆ วิธี streaming json encoder มีจุดมุ่งหมายเพื่อให้ทำงานเป็นส่วนใหญ่แทน json_encode() อย่างไรก็ตาม เนื่องจากตัวเข้ารหัสมีวัตถุประสงค์เพื่อจัดการกับชุดข้อมูลขนาดใหญ่ จึงมีความแตกต่างที่เห็นได้ชัดเจนบางประการในการจัดการกับวัตถุและอาร์เรย์

ขั้นแรก เพื่อกำหนดวิธีการเข้ารหัสออบเจ็กต์ ตัวเข้ารหัสจะพยายามแก้ไขค่าออบเจ็กต์ด้วยวิธีต่อไปนี้:

• สำหรับอ็อบเจ็กต์ใดๆ ที่ใช้ JsonSerializable จะมีการเรียกใช้เมธอด jsonSerialize() ที่นำไปใช้งาน และใช้ค่าที่ส่งคืนแทน
• Closure ใด ๆ จะถูกเรียกใช้และค่าส่งคืนจะถูกใช้แทน อย่างไรก็ตาม ไม่มีการเรียกสิ่งอื่นใดในลักษณะนี้

ค่าที่ส่งคืนจะวนซ้ำจนกว่าจะไม่สามารถแก้ไขเพิ่มเติมได้ หลังจากนั้น จะมีการตัดสินใจว่าอาร์เรย์หรือวัตถุถูกเข้ารหัสเป็นอาร์เรย์หรือเป็นวัตถุ มีการใช้ตรรกะต่อไปนี้:

• อาร์เรย์หรืออาร์เรย์ว่างใดๆ ที่มีคีย์ตั้งแต่ 0 ถึง n-1 ตามลำดับนั้นจะถูกเข้ารหัสเป็นอาร์เรย์ JSON อาร์เรย์อื่นๆ ทั้งหมดจะถูกเข้ารหัสเป็นออบเจ็กต์ JSON
• หากอ็อบเจ็กต์ใช้ Traversable และส่งคืนค่า interger 0 เป็นคีย์แรกหรือไม่ส่งคืนค่าใดๆ เลย อ็อบเจ็กต์นั้นจะถูกเข้ารหัสเป็นอาร์เรย์ JSON (โดยไม่คำนึงถึงคีย์อื่นๆ) ออบเจ็กต์อื่นๆ ทั้งหมดที่ใช้งาน Traversable จะถูกเข้ารหัสเป็นออบเจ็กต์ JSON
• ออบเจ็กต์อื่นๆ ไม่ว่าจะว่างเปล่าหรือคีย์ใดก็ตามที่ฉันมี จะถูกเข้ารหัสเป็นออบเจ็กต์ JSON

อย่างไรก็ตาม โปรดทราบว่าหากใช้ตัวเลือกการเข้ารหัส JSON JSON_FORCE_OBJECT กต์และอาร์เรย์ทั้งหมดจะถูกเข้ารหัสเป็นออบเจ็กต์ JSON

โปรดทราบว่าวัตถุทั้งหมดถูกสำรวจผ่านคำสั่ง foreach ซึ่งหมายความว่าออบเจ็กต์ Traversable ทั้งหมดได้รับการเข้ารหัสโดยใช้ค่าที่ส่งคืนโดยตัววนซ้ำ สำหรับออบเจ็กต์อื่นๆ หมายความว่ามีการใช้คุณสมบัติสาธารณะ (ตามพฤติกรรมการวนซ้ำเริ่มต้น)

ค่าอื่นๆ ทั้งหมด (เช่น ค่าว่าง บูลีน ตัวเลข และสตริง) จะได้รับการปฏิบัติเช่นเดียวกับที่ json_encode() ทำทุกประการ (และในความเป็นจริง ค่าดังกล่าวใช้ในการเข้ารหัสค่าเหล่านั้น)

ตัวเลือกการเข้ารหัส JSON

ทั้ง BufferJsonEncoder และ StreamJsonEncoder มีเมธอด setOptions() เพื่อเปลี่ยนตัวเลือกการเข้ารหัส JSON ตัวเลือกที่ยอมรับจะเหมือนกับตัวเลือกที่ยอมรับโดยฟังก์ชัน json_encode() ตัวเข้ารหัสยังคงใช้เมธอด json_encode() ภายในเพื่อเข้ารหัสค่าอื่นที่ไม่ใช่อาร์เรย์หรืออ็อบเจ็กต์ ตัวเลือกบางตัวยังมีผลกระทบเพิ่มเติมต่อตัวเข้ารหัส:

• การใช้ JSON_FORCE_OBJECT จะบังคับให้อาร์เรย์และออบเจ็กต์ทั้งหมดถูกเข้ารหัสเป็นออบเจ็กต์ JSON ที่คล้ายกับ json_encode()
• การใช้ JSON_PRETTY_PRINT จะทำให้ตัวเข้ารหัสแสดงช่องว่างเอาต์พุตเพื่อทำให้เอาต์พุตอ่านได้ง่ายขึ้น การเยื้องที่ใช้สามารถเปลี่ยนแปลงได้โดยใช้เมธอด setIndent() ซึ่งยอมรับอาร์กิวเมนต์สตริงเพื่อใช้เป็นการเยื้องหรือจำนวนเต็มเพื่อระบุจำนวนช่องว่าง
• การใช้ JSON_PARTIAL_OUTPUT_ON_ERROR จะทำให้ตัวเข้ารหัสดำเนินการเอาต์พุตต่อไปแม้จะมีข้อผิดพลาดในการเข้ารหัสก็ตาม มิฉะนั้นการเข้ารหัสจะหยุดลงและตัวเข้ารหัสจะส่ง EncodingException

เครดิต

ห้องสมุดนี้เป็นลิขสิทธิ์ (c) 2017-2022 Riikka Kalliomäki

ดูใบอนุญาตสำหรับข้อมูลใบอนุญาตและการคัดลอก