streaming json encoder
Version 1.1.5
streaming json encoder عبارة عن مكتبة PHP توفر مجموعة من الفئات للمساعدة في تشفير JSON بطريقة التدفق، أي السماح لك بتشفير مستند JSON شيئًا فشيئًا بدلاً من تشفير المستند بأكمله مرة واحدة. بالمقارنة مع وظيفة json_encode المضمنة، هناك ميزتان رئيسيتان:
بمعنى آخر، يمكن أن يوفر streaming json encoder أكبر فائدة عندما تحتاج إلى التعامل مع مجموعات كبيرة من البيانات التي قد تستهلك الكثير من الذاكرة لمعالجتها.
من أجل زيادة إمكانية التشغيل البيني، توفر المكتبة أيضًا دفقًا متوافقًا مع PSR-7 لاستخدامه مع أطر العمل وطلبات HTTP.
وثائق واجهة برمجة التطبيقات متاحة على: http://violet.riimu.net/api/streaming-json-encoder/
^1.0 ) أسهل طريقة لتثبيت هذه المكتبة هي استخدام Composer للتعامل مع تبعياتك. لتثبيت هذه المكتبة عبر Composer، ما عليك سوى اتباع الخطوتين التاليتين:
احصل على composer.phar عن طريق تشغيل تثبيت سطر أوامر Composer في جذر مشروعك.
بمجرد تشغيل البرنامج النصي للتثبيت، يجب أن يكون لديك ملف composer.phar .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 الأخرى المطلوبة تلقائيًا. إذا قمت بتثبيت هذه المكتبة يدويًا، فستحتاج أيضًا إلى إتاحة تلك المكتبات الأخرى المطلوبة.
توفر هذه المكتبة ثلاث طرق رئيسية مختلفة لاستخدام المكتبة عبر الفئات BufferJsonEncoder و StreamJsonEncoder والدفق المتوافق مع PSR-7 JsonStream .
يكون برنامج تشفير المخزن المؤقت مفيدًا للغاية عندما تحتاج إلى إنشاء مستند 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 للكائنات التي تنفذ الواجهة.
يعمل برنامج تشفير الدفق بشكل مشابه جدًا لـ BufferJsonEncoder لأنه يمتد إلى نفس الفئة المجردة. ومع ذلك، فإن الاختلاف الرئيسي يكمن في كيفية التعامل مع تمرير مخرجات JSON.
يقبل StreamJsonEncoder القابل للاستدعاء كوسيطة المنشئ الثانية. عندما يلزم إخراج JSON، يتم استدعاء هذا القابل للاستدعاء باستخدام وسيطتين، السلسلة الفعلية المراد إخراجها ونوع الرمز المميز المراد إخراجه (وهو أحد ثوابت JsonToken ).
إذا لم يتم تمرير أي قابل للاستدعاء، فسيقوم StreamJsonEncoder ببساطة بإخراج JSON باستخدام عبارة الصدى. على سبيل المثال:
<?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 ); توفر فئة الدفق 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 وسيتم استخدام القيمة المرجعة بدلاً من ذلك. ومع ذلك، لا يتم استدعاء أي استدعاءات أخرى بهذه الطريقة.يتم تكرار القيمة التي تم إرجاعها حتى لا يمكن حلها بشكل أكبر. بعد ذلك، يتم اتخاذ قرار بشأن ما إذا كان سيتم ترميز المصفوفة أو الكائن كمصفوفة أم ككائن. يتم استخدام المنطق التالي:
Traversable وقام إما بإرجاع interger 0 كمفتاح أول أو عدم إرجاع أي قيم على الإطلاق، فسيتم ترميزه كمصفوفة JSON (بغض النظر عن المفاتيح الأخرى). يتم تشفير كافة الكائنات الأخرى التي تنفذ Traversable ككائنات JSON. ومع ذلك، لاحظ أنه إذا تم استخدام خيار تشفير JSON JSON_FORCE_OBJECT ، فسيتم تشفير كافة الكائنات والمصفوفات ككائنات JSON.
لاحظ أنه يتم اجتياز جميع الكائنات عبر عبارة foreach . هذا يعني أن كافة الكائنات Traversable يتم ترميزها باستخدام القيم التي يتم إرجاعها بواسطة المكرّر. بالنسبة للكائنات الأخرى، هذا يعني أنه يتم استخدام الخصائص العامة (حسب سلوك التكرار الافتراضي).
يتم التعامل مع جميع القيم الأخرى (أي القيم الخالية والقيم المنطقية والأرقام والسلاسل) تمامًا بنفس الطريقة التي يتعامل بها json_encode() (وفي الواقع، يتم استخدامه لتشفير تلك القيم).
يمتلك كل من 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.
راجع الترخيص للحصول على معلومات الترخيص والنسخ.
