promise

สัญญา

การใช้งาน CommonJS Promises/A สำหรับ PHP แบบน้ำหนักเบา

สารบัญ

1. การแนะนำ
2. แนวคิด
   • เลื่อนออกไป
   • สัญญา
3. เอพีไอ
   • เลื่อนออกไป
     • เลื่อนออกไป::สัญญา()
     • เลื่อนออกไป::แก้ไข()
     • เลื่อนออกไป::ปฏิเสธ()
   • อินเทอร์เฟซสัญญา
     • สัญญาอินเทอร์เฟซ::แล้ว()
     • สัญญาอินเทอร์เฟซ::จับ()
     • สัญญาอินเทอร์เฟซ::ในที่สุด ()
     • สัญญาอินเทอร์เฟซ::ยกเลิก()
     • สัญญาอินเทอร์เฟซ::มิฉะนั้น ()
     • สัญญาอินเทอร์เฟซ::always()
   • สัญญา
   • ฟังก์ชั่น
     • แก้ไข()
     • ปฏิเสธ()
     • ทั้งหมด()
     • แข่ง()
     • ใดๆ()
     • set_rejection_handler()
4. ตัวอย่าง
   • วิธีใช้รอการตัดบัญชี
   • การส่งต่อสัญญาทำงานอย่างไร
     • การส่งต่อความละเอียด
     • การส่งต่อการปฏิเสธ
     • ความละเอียดแบบผสมและการส่งต่อการปฏิเสธ
5. ติดตั้ง
6. การทดสอบ
7. เครดิต
8. ใบอนุญาต

การแนะนำ

Promise เป็นไลบรารีที่ใช้ CommonJS Promises/A สำหรับ PHP

นอกจากนี้ยังมีแนวคิดที่เกี่ยวข้องกับสัญญาที่มีประโยชน์อื่นๆ อีกหลายรายการ เช่น การรวมหลายสัญญา และการแม็ปและการลดการรวบรวมสัญญา

หากคุณไม่เคยได้ยินเกี่ยวกับคำสัญญามาก่อน โปรดอ่านข้อความนี้ก่อน

แนวคิด

เลื่อนออกไป

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

สัญญา

ในขณะที่การเลื่อนออกไปแสดงถึงการคำนวณนั้นเอง Promise จะแสดงผลลัพธ์ของการคำนวณนั้น ดังนั้นการเลื่อนแต่ละรายการจึงมีคำมั่นสัญญาที่ทำหน้าที่เป็นตัวแทนสำหรับผลลัพธ์ที่แท้จริง

เอพีไอ

เลื่อนออกไป

การเลื่อนออกไปหมายถึงการดำเนินการที่รอการแก้ไขอยู่ มีสัญญาและส่วนแก้ไขแยกกัน

 $ deferred = new React  Promise  Deferred ();

$ promise = $ deferred -> promise ();

$ deferred -> resolve (mixed $ value );
$ deferred -> reject (Throwable $ reason );

วิธี promise จะส่งคืนสัญญาของผู้ที่ถูกเลื่อนออกไป

วิธี resolve และ reject จะควบคุมสถานะของการเลื่อนออกไป

ตัวสร้างของ Deferred ยอมรับอาร์กิวเมนต์ $canceller ที่เป็นทางเลือก ดูสัญญาสำหรับข้อมูลเพิ่มเติม

เลื่อนออกไป::สัญญา()

 $ promise = $ deferred -> promise ();

ส่งกลับคำสัญญาของผู้ที่ถูกเลื่อนออกไป ซึ่งคุณสามารถมอบให้ผู้อื่นได้ในขณะที่ยังคงรักษาอำนาจในการแก้ไขสถานะไว้กับตัวคุณเอง

เลื่อนออกไป::แก้ไข()

 $ deferred -> resolve (mixed $ value );

แก้ไขสัญญาที่ส่งคืนโดย promise() ผู้บริโภคทุกคนจะได้รับแจ้งโดยการเรียก $onFulfilled (ซึ่งพวกเขาลงทะเบียนผ่าน $promise->then() ) ด้วย $value

หาก $value เป็นสัญญา สัญญาจะเปลี่ยนไปสู่สถานะของสัญญานี้เมื่อได้รับการแก้ไขแล้ว

ดูเพิ่มเติมที่ฟังก์ชัน resolve()

เลื่อนออกไป::ปฏิเสธ()

 $ deferred -> reject (Throwable $ reason );

ปฏิเสธสัญญาที่ส่งคืนโดย promise() ซึ่งส่งสัญญาณว่าการคำนวณของการเลื่อนออกไปล้มเหลว ผู้บริโภคทุกคนจะได้รับแจ้งโดยให้ $onRejected (ซึ่งพวกเขาลงทะเบียนผ่าน $promise->then() ) เรียกด้วย $reason

ดูเพิ่มเติมที่ฟังก์ชัน reject()

อินเทอร์เฟซสัญญา

อินเทอร์เฟซสัญญาจัดเตรียมอินเทอร์เฟซทั่วไปสำหรับการใช้งานตามสัญญาทั้งหมด ดูสัญญาสำหรับการใช้งานสาธารณะเพียงอย่างเดียวที่เปิดเผยโดยแพ็คเกจนี้

คำสัญญาแสดงถึงผลลัพธ์ในท้ายที่สุด ซึ่งอาจเป็นความสำเร็จ (ความสำเร็จ) และคุณค่าที่เกี่ยวข้อง หรือการปฏิเสธ (ความล้มเหลว) และเหตุผลที่เกี่ยวข้อง

เมื่ออยู่ในสถานะปฏิบัติตามหรือถูกปฏิเสธ คำสัญญาจะไม่เปลี่ยนรูป ไม่สามารถแก้ไขสถานะและผลลัพธ์ (หรือข้อผิดพลาด) ได้

สัญญาอินเทอร์เฟซ::แล้ว()

 $ transformedPromise = $ promise -> then (callable $ onFulfilled = null , callable $ onRejected = null );

แปลงค่าของสัญญาโดยการใช้ฟังก์ชันกับมูลค่าการปฏิบัติตามหรือการปฏิเสธของสัญญา ส่งกลับคำสัญญาใหม่สำหรับผลลัพธ์ที่เปลี่ยนแปลง

วิธีการ then() จะลงทะเบียนตัวจัดการที่ปฏิบัติตามและการปฏิเสธใหม่พร้อมกับสัญญา (พารามิเตอร์ทั้งหมดเป็นทางเลือก):

• $onFulfilled จะถูกเรียกใช้เมื่อสัญญาบรรลุผลและส่งผ่านผลลัพธ์เป็นอาร์กิวเมนต์แรก
• $onRejected จะถูกเรียกใช้เมื่อสัญญาถูกปฏิเสธและส่งเหตุผลเป็นอาร์กิวเมนต์แรก

มันจะส่งคืนสัญญาใหม่ที่จะตอบสนองด้วยค่าส่งคืนของ $onFulfilled หรือ $onRejected แล้วแต่ว่าอันไหนจะถูกเรียก หรือจะปฏิเสธโดยมีข้อยกเว้นที่ส่งออกมาหากมีการโยนอย่างใดอย่างหนึ่ง

สัญญาทำให้การรับประกันต่อไปนี้เกี่ยวกับตัวจัดการที่ลงทะเบียนในการเรียกเดียวกันกับ then() :

1. $onFulfilled หรือ $onRejected เพียงอันเดียวเท่านั้นที่จะถูกเรียก ไม่มีการเรียกทั้งสองอย่างเลย
2. $onFulfilled และ $onRejected จะไม่ถูกเรียกมากกว่าหนึ่งครั้ง

ดูเพิ่มเติม

• แก้ไข () - การสร้างคำสัญญาที่ได้รับการแก้ไข
• ปฏิเสธ() - การสร้างสัญญาที่ถูกปฏิเสธ

สัญญาอินเทอร์เฟซ::จับ()

 $ promise -> catch (callable $ onRejected );

ลงทะเบียนตัวจัดการการปฏิเสธสำหรับสัญญา เป็นทางลัดสำหรับ:

 $ promise -> then ( null , $ onRejected );

นอกจากนี้ คุณยังสามารถพิมพ์คำใบ้อาร์กิวเมนต์ $reason ของ $onRejected เพื่อตรวจจับเฉพาะข้อผิดพลาดเฉพาะเท่านั้น

 $ promise
    -> catch ( function (  RuntimeException $ reason ) {
        // Only catch RuntimeException instances
        // All other types of errors will propagate automatically
    })
    -> catch ( function (  Throwable $ reason ) {
        // Catch other errors
    });

สัญญาอินเทอร์เฟซ::ในที่สุด ()

 $ newPromise = $ promise -> finally (callable $ onFulfilledOrRejected );

ช่วยให้คุณดำเนินการงานประเภท "ล้างข้อมูล" ในห่วงโซ่สัญญา

โดยจะจัดให้มีการเรียก $onFulfilledOrRejected โดยไม่มีข้อโต้แย้ง เมื่อสัญญาบรรลุผลหรือถูกปฏิเสธ

• หาก $promise บรรลุผล และ $onFulfilledOrRejected ส่งกลับสำเร็จ $newPromise จะเติมเต็มด้วยค่าเดียวกันกับ $promise
• หาก $promise บรรลุผล และ $onFulfilledOrRejected ส่งหรือส่งคืนสัญญาที่ถูกปฏิเสธ $newPromise จะปฏิเสธโดยมีข้อยกเว้นที่ส่งออกมาหรือเหตุผลของสัญญาที่ถูกปฏิเสธ
• หาก $promise ปฏิเสธ และ $onFulfilledOrRejected กลับมาสำเร็จ $newPromise จะปฏิเสธด้วยเหตุผลเดียวกันกับ $promise
• หาก $promise ปฏิเสธ และ $onFulfilledOrRejected ส่งหรือส่งคืนสัญญาที่ถูกปฏิเสธ $newPromise จะปฏิเสธโดยมีข้อยกเว้นที่ส่งออกมาหรือเหตุผลของสัญญาที่ถูกปฏิเสธ

finally() มีพฤติกรรมคล้ายกับคำสั่งสุดท้ายแบบซิงโครนัส เมื่อรวมกับ catch() finally() จะช่วยให้คุณสามารถเขียนโค้ดที่คล้ายกับการจับคู่ catch/finally แบบซิงโครนัสที่คุ้นเคย

พิจารณาโค้ดซิงโครนัสต่อไปนี้:

 try {
    return doSomething ();
} catch (  Throwable $ e ) {
    return handleError ( $ e );
} finally {
    cleanup ();
}

โค้ดอะซิงโครนัสที่คล้ายกัน (ด้วย doSomething() ที่ส่งคืนสัญญา) สามารถเขียนได้:

 return doSomething ()
    -> catch ( ' handleError ' )
    -> finally ( ' cleanup ' );

สัญญาอินเทอร์เฟซ::ยกเลิก()

 $ promise -> cancel ();

เมธอด cancel() แจ้งให้ผู้สร้างทราบถึงสัญญาว่าจะไม่มีความสนใจในผลลัพธ์ของการดำเนินการอีกต่อไป

เมื่อสัญญาได้รับการชำระ (ไม่ว่าจะสำเร็จหรือถูกปฏิเสธ) การเรียก cancel() กับสัญญาจะไม่มีผลใดๆ

สัญญาอินเทอร์เฟซ::มิฉะนั้น ()

เลิกใช้แล้วตั้งแต่เวอร์ชัน 3.0.0 โปรดดู catch() แทน

วิธีการ otherwise() จะลงทะเบียนตัวจัดการการปฏิเสธสำหรับสัญญา

วิธีการนี้ยังคงมีอยู่ด้วยเหตุผล BC เท่านั้น และเพื่อความสะดวกในการอัปเกรดระหว่างเวอร์ชันต่างๆ มันเป็นนามแฝงสำหรับ:

 $ promise -> catch ( $ onRejected );

สัญญาอินเทอร์เฟซ::always()

เลิกใช้แล้วตั้งแต่เวอร์ชัน 3.0.0 โปรดดู finally() แทน

เมธอด always() ช่วยให้คุณสามารถดำเนินงานประเภท "การล้างข้อมูล" ในห่วงโซ่สัญญาได้

วิธีการนี้ยังคงมีอยู่ด้วยเหตุผล BC เท่านั้น และเพื่อความสะดวกในการอัปเกรดระหว่างเวอร์ชันต่างๆ มันเป็นนามแฝงสำหรับ:

 $ promise -> finally ( $ onFulfilledOrRejected );

สัญญา

สร้างสัญญาที่สถานะถูกควบคุมโดยฟังก์ชันที่ส่งไปยัง $resolver

 $ resolver = function ( callable $ resolve , callable $ reject ) {
    // Do some work, possibly asynchronously, and then
    // resolve or reject.

    $ resolve ( $ awesomeResult );
    // or throw new Exception('Promise rejected');
    // or $resolve($anotherPromise);
    // or $reject($nastyError);
};

$ canceller = function () {
    // Cancel/abort any running operations like network connections, streams etc.

    // Reject promise by throwing an exception
    throw new Exception ( ' Promise cancelled ' );
};

$ promise = new React  Promise  Promise ( $ resolver , $ canceller );

ตัวสร้างสัญญาได้รับฟังก์ชันตัวแก้ไขและฟังก์ชันตัวยกเลิกทางเลือกซึ่งทั้งสองจะถูกเรียกด้วยสองอาร์กิวเมนต์:

• $resolve($value) - ฟังก์ชันหลักที่ผนึกชะตากรรมของสัญญาที่ส่งคืน ยอมรับมูลค่าที่ไม่ใช่สัญญาหรือสัญญาอื่น เมื่อเรียกด้วยมูลค่าที่ไม่สัญญา จะทำให้สัญญาบรรลุผลด้วยมูลค่านั้น เมื่อถูกเรียกพร้อมกับสัญญาอื่น เช่น $resolve($otherPromise) ชะตากรรมของสัญญาจะเทียบเท่ากับชะตากรรมของ $otherPromise
• $reject($reason) - ฟังก์ชั่นที่ปฏิเสธคำสัญญา ขอแนะนำให้โยนข้อยกเว้นแทนการใช้ $reject()

หากตัวแก้ไขหรือตัวยกเลิกส่งข้อยกเว้น สัญญาจะถูกปฏิเสธพร้อมกับข้อยกเว้นที่ส่งออกมานั้นเป็นเหตุผลในการปฏิเสธ

ฟังก์ชันตัวแก้ไขจะถูกเรียกใช้ทันที ส่วนฟังก์ชันตัวยกเลิกจะทำก็ต่อเมื่อผู้บริโภคทุกคนเรียกเมธอด cancel() ของสัญญาเท่านั้น

ฟังก์ชั่น

ฟังก์ชั่นที่มีประโยชน์สำหรับการสร้างและเข้าร่วมคอลเลกชันคำสัญญา

ฟังก์ชั่นทั้งหมดที่ทำงานกับการรวบรวมสัญญา (เช่น all() , race() ฯลฯ ) รองรับการยกเลิก ซึ่งหมายความว่า หากคุณเรียก cancel() กับสัญญาที่ส่งคืน สัญญาทั้งหมดในคอลเลกชันจะถูกยกเลิก

แก้ไข()

 $ promise = React  Promise resolve (mixed $ promiseOrValue );

สร้างสัญญาสำหรับ $promiseOrValue ที่ให้มา

หาก $promiseOrValue เป็นค่า มันจะเป็นค่าการแก้ไขของสัญญาที่ส่งคืน

ถ้า $promiseOrValue เป็น thenable (อ็อบเจ็กต์ใดๆ ที่ให้เมธอด then() ) สัญญาที่เชื่อถือได้ซึ่งเป็นไปตามสถานะของ the thenable จะถูกส่งคืน

หาก $promiseOrValue เป็นสัญญา ก็จะถูกส่งคืนตามสภาพที่เป็นอยู่

ผลลัพธ์ $promise จะใช้ PromiseInterface และสามารถใช้ได้เหมือนกับสัญญาอื่นๆ:

 $ promise = React  Promise resolve ( 42 );

$ promise -> then ( function ( int $ result ): void {
    var_dump ( $ result );
}, function (  Throwable $ e ): void {
    echo ' Error: ' . $ e -> getMessage () . PHP_EOL ;
});

ปฏิเสธ()

 $ promise = React  Promise reject (Throwable $ reason );

สร้างสัญญาที่ถูกปฏิเสธสำหรับ $reason ที่ให้มา

โปรดทราบว่าอินเทอร์เฟซ Throwable ที่นำมาใช้ใน PHP 7 ครอบคลุมทั้งข้อผิดพลาด PHP ภายในของผู้ใช้ land Exception และ Error ด้วยการบังคับใช้ Throwable เป็นเหตุผลในการปฏิเสธสัญญา ข้อผิดพลาดทางภาษาหรือข้อยกเว้นของผู้ใช้สามารถใช้เพื่อปฏิเสธสัญญาได้

ผลลัพธ์ $promise จะใช้ PromiseInterface และสามารถใช้ได้เหมือนกับสัญญาอื่นๆ:

 $ promise = React  Promise reject ( new RuntimeException ( ' Request failed ' ));

$ promise -> then ( function ( int $ result ): void {
    var_dump ( $ result );
}, function (  Throwable $ e ): void {
    echo ' Error: ' . $ e -> getMessage () . PHP_EOL ;
});

โปรดทราบว่าคำสัญญาที่ถูกปฏิเสธควรได้รับการจัดการในลักษณะเดียวกับวิธีจับข้อยกเว้นใดๆ ในบล็อก try + catch เสมอ หากคุณลบการอ้างอิงล่าสุดไปยังสัญญาที่ถูกปฏิเสธซึ่งไม่ได้รับการจัดการ ระบบจะรายงานการปฏิเสธสัญญาที่ไม่ได้จัดการ:

 function incorrect (): int
{
     $ promise = React  Promise reject ( new RuntimeException ( ' Request failed ' ));

     // Commented out: No rejection handler registered here.
     // $promise->then(null, function (Throwable $e): void { /* ignore */ });

     // Returning from a function will remove all local variable references, hence why
     // this will report an unhandled promise rejection here.
     return 42 ;
}

// Calling this function will log an error message plus its stack trace:
// Unhandled promise rejection with RuntimeException: Request failed in example.php:10
incorrect ();

สัญญาที่ถูกปฏิเสธจะถือว่า "ได้รับการจัดการ" หากคุณทราบสาเหตุการปฏิเสธด้วยวิธีการ then() วิธี catch() หรือวิธี finally() โปรดทราบว่าแต่ละวิธีเหล่านี้ส่งคืนสัญญาใหม่ที่อาจถูกปฏิเสธอีกครั้งหากคุณส่งข้อยกเว้นอีกครั้ง

สัญญาที่ถูกปฏิเสธจะถือว่า "ได้รับการจัดการ" หากคุณยกเลิกการดำเนินการด้วยวิธี cancel() (ซึ่งโดยปกติจะปฏิเสธสัญญาหากยังคงค้างอยู่)

ดูเพิ่มเติมที่ฟังก์ชัน set_rejection_handler()

ทั้งหมด()

 $ promise = React  Promise all (iterable $ promisesOrValues );

ส่งกลับคำสัญญาที่จะแก้ไขก็ต่อเมื่อรายการทั้งหมดใน $promisesOrValues ​​ได้รับการแก้ไขแล้วเท่านั้น ค่าความละเอียดของสัญญาที่ส่งคืนจะเป็นอาร์เรย์ที่มีค่าความละเอียดของแต่ละรายการใน $promisesOrValues

แข่ง()

 $ promise = React  Promise race (iterable $ promisesOrValues );

เริ่มต้นการแข่งขันที่เปิดโอกาสให้ผู้ชนะหนึ่งคน ส่งคืนสัญญาที่ได้รับการแก้ไขในลักษณะเดียวกับที่สัญญาที่ตกลงกันครั้งแรกได้รับการแก้ไข

สัญญาที่ส่งคืนจะกลายเป็น ค้างอยู่อย่างไม่สิ้นสุด หาก $promisesOrValues ​​มี 0 รายการ

ใดๆ()

 $ promise = React  Promise any (iterable $ promisesOrValues );

ส่งกลับคำสัญญาที่จะแก้ไขเมื่อรายการใดรายการหนึ่งใน $promisesOrValues ​​แก้ไข ค่าการแก้ไขของสัญญาที่ส่งคืนจะเป็นค่าการแก้ไขของรายการที่ทริกเกอร์

สัญญาที่ส่งคืนจะปฏิเสธก็ต่อเมื่อรายการ ทั้งหมด ใน $promisesOrValues ​​ถูกปฏิเสธ ค่าการปฏิเสธจะเป็น ReactPromiseExceptionCompositeException ซึ่งเก็บเหตุผลในการปฏิเสธทั้งหมด สามารถรับเหตุผลในการปฏิเสธได้ด้วย CompositeException::getThrowables()

สัญญาที่ส่งคืนจะถูกปฏิเสธด้วย ReactPromiseExceptionLengthException หาก $promisesOrValues ​​มี 0 รายการ

set_rejection_handler()

 React  Promise set_rejection_handler(?callable $ callback ): ?callable;

ตั้งค่าตัวจัดการการปฏิเสธส่วนกลางสำหรับการปฏิเสธสัญญาที่ไม่มีการจัดการ

โปรดทราบว่าคำสัญญาที่ถูกปฏิเสธควรได้รับการจัดการในลักษณะเดียวกับวิธีจับข้อยกเว้นใดๆ ในบล็อก try + catch เสมอ หากคุณลบการอ้างอิงล่าสุดไปยังสัญญาที่ถูกปฏิเสธซึ่งไม่ได้รับการจัดการ ระบบจะรายงานการปฏิเสธสัญญาที่ไม่มีการจัดการ ดูเพิ่มเติมที่ฟังก์ชัน reject() สำหรับรายละเอียดเพิ่มเติม

อาร์กิวเมนต์ ?callable $callback ต้องเป็นฟังก์ชันการเรียกกลับที่ถูกต้องที่ยอมรับอาร์กิวเมนต์ Throwable เดียวหรือค่า null เพื่อคืนค่าตัวจัดการการปฏิเสธสัญญาเริ่มต้น ค่าที่ส่งคืนของฟังก์ชันการโทรกลับจะถูกละเว้นและไม่มีผลกระทบ ดังนั้นคุณควรส่งคืนค่าเป็น void ฟังก์ชั่นการโทรกลับต้องไม่โยน ไม่เช่นนั้นโปรแกรมจะถูกยกเลิกโดยมีข้อผิดพลาดร้ายแรง

ฟังก์ชันส่งคืนตัวจัดการการปฏิเสธก่อนหน้าหรือ null หากใช้ตัวจัดการการปฏิเสธตามสัญญาเริ่มต้น

ตัวจัดการการปฏิเสธคำสัญญาเริ่มต้นจะบันทึกข้อความแสดงข้อผิดพลาดพร้อมการติดตามสแต็ก:

 // Unhandled promise rejection with RuntimeException: Unhandled in example.php:2
React  Promise reject ( new RuntimeException ( ' Unhandled ' ));

ตัวจัดการการปฏิเสธสัญญาอาจใช้เพื่อใช้ปรับแต่งข้อความบันทึกหรือเขียนไปยังเป้าหมายบันทึกที่กำหนดเอง ตามหลักทั่วไปแล้ว ฟังก์ชันนี้ควรใช้เป็นทางเลือกสุดท้ายเท่านั้น และการปฏิเสธที่ได้รับสัญญาว่าจะจัดการได้ดีที่สุดโดยใช้เมธอด then() เมธอด catch() หรือเมธอด finally() ดูเพิ่มเติมที่ฟังก์ชัน reject() สำหรับรายละเอียดเพิ่มเติม

ตัวอย่าง

วิธีใช้รอการตัดบัญชี

 function getAwesomeResultPromise ()
{
    $ deferred = new React  Promise  Deferred ();

    // Execute a Node.js-style function using the callback pattern
    computeAwesomeResultAsynchronously ( function (  Throwable $ error , $ result ) use ( $ deferred ) {
        if ( $ error ) {
            $ deferred -> reject ( $ error );
        } else {
            $ deferred -> resolve ( $ result );
        }
    });

    // Return the promise
    return $ deferred -> promise ();
}

getAwesomeResultPromise ()
    -> then (
        function ( $ value ) {
            // Deferred resolved, do something with $value
        },
        function (  Throwable $ reason ) {
            // Deferred rejected, do something with $reason
        }
    );

การส่งต่อสัญญาทำงานอย่างไร

ตัวอย่างง่ายๆ บางส่วนที่แสดงให้เห็นว่ากลไกของการส่งต่อ Promises/A ทำงานอย่างไร แน่นอนว่าตัวอย่างเหล่านี้ได้รับการประดิษฐ์ขึ้น และในการใช้งานจริง Promise Chains จะกระจายไปตามการเรียกใช้ฟังก์ชันต่างๆ หรือแม้แต่สถาปัตยกรรมแอปพลิเคชันของคุณหลายระดับ

การส่งต่อความละเอียด

แก้ไขแล้ว สัญญาส่งต่อค่าการแก้ไขไปยังสัญญาถัดไป สัญญาแรก $deferred->promise() จะได้รับการแก้ไขด้วยค่าที่ส่งไปยัง $deferred->resolve() ด้านล่าง

การเรียกแต่ละครั้งที่ then() จะส่งคืนสัญญาใหม่ที่จะแก้ไขด้วยค่าส่งคืนของตัวจัดการก่อนหน้า สิ่งนี้จะสร้าง "ท่อส่ง" คำมั่นสัญญา

 $ deferred = new React  Promise  Deferred ();

$ deferred -> promise ()
    -> then ( function ( $ x ) {
        // $x will be the value passed to $deferred->resolve() below
        // and returns a *new promise* for $x + 1
        return $ x + 1 ;
    })
    -> then ( function ( $ x ) {
        // $x === 2
        // This handler receives the return value of the
        // previous handler.
        return $ x + 1 ;
    })
    -> then ( function ( $ x ) {
        // $x === 3
        // This handler receives the return value of the
        // previous handler.
        return $ x + 1 ;
    })
    -> then ( function ( $ x ) {
        // $x === 4
        // This handler receives the return value of the
        // previous handler.
        echo ' Resolve ' . $ x ;
    });

$ deferred -> resolve ( 1 ); // Prints "Resolve 4" 

การส่งต่อการปฏิเสธ

คำสัญญาที่ถูกปฏิเสธมีพฤติกรรมคล้ายกัน และยังทำงานคล้ายกันใน try/catch: เมื่อคุณตรวจพบข้อยกเว้น คุณต้องเขียนใหม่เพื่อให้มันเผยแพร่

ในทำนองเดียวกัน เมื่อคุณจัดการกับคำสัญญาที่ถูกปฏิเสธ เพื่อเผยแพร่การปฏิเสธ "โยนใหม่" ด้วยการคืนคำสัญญาที่ถูกปฏิเสธ หรือโยนทิ้งจริง ๆ (เนื่องจากคำสัญญาแปลข้อยกเว้นที่ถูกโยนเป็นการปฏิเสธ)

 $ deferred = new React  Promise  Deferred ();

$ deferred -> promise ()
    -> then ( function ( $ x ) {
        throw new  Exception ( $ x + 1 );
    })
    -> catch ( function (  Exception $ x ) {
        // Propagate the rejection
        throw $ x ;
    })
    -> catch ( function (  Exception $ x ) {
        // Can also propagate by returning another rejection
        return React  Promise reject (
            new  Exception ( $ x -> getMessage () + 1 )
        );
    })
    -> catch ( function ( $ x ) {
        echo ' Reject ' . $ x -> getMessage (); // 3
    });

$ deferred -> resolve ( 1 );  // Prints "Reject 3" 

ความละเอียดแบบผสมและการส่งต่อการปฏิเสธ

เช่นเดียวกับ try/catch คุณสามารถเลือกที่จะเผยแพร่หรือไม่ก็ได้ การผสมผสานการแก้ปัญหาและการปฏิเสธจะยังคงส่งต่อผลลัพธ์ของตัวจัดการในลักษณะที่คาดเดาได้

 $ deferred = new React  Promise  Deferred ();

$ deferred -> promise ()
    -> then ( function ( $ x ) {
        return $ x + 1 ;
    })
    -> then ( function ( $ x ) {
        throw new  Exception ( $ x + 1 );
    })
    -> catch ( function (  Exception $ x ) {
        // Handle the rejection, and don't propagate.
        // This is like catch without a rethrow
        return $ x -> getMessage () + 1 ;
    })
    -> then ( function ( $ x ) {
        echo ' Mixed ' . $ x ; // 4
    });

$ deferred -> resolve ( 1 );  // Prints "Mixed 4" 

ติดตั้ง

วิธีที่แนะนำในการติดตั้งไลบรารีนี้คือผ่าน Composer ยังใหม่กับนักแต่งเพลงใช่ไหม?

โครงการนี้เป็นไปตาม SemVer สิ่งนี้จะติดตั้งเวอร์ชันที่รองรับล่าสุดจากสาขานี้:

composer require react/promise:^3.2

ดูเพิ่มเติมที่ CHANGELOG สำหรับรายละเอียดเกี่ยวกับการอัปเกรดเวอร์ชัน

โปรเจ็กต์นี้มีจุดมุ่งหมายเพื่อทำงานบนแพลตฟอร์มใดๆ ดังนั้นจึงไม่จำเป็นต้องมีส่วนขยาย PHP ใดๆ และรองรับการทำงานบน PHP 7.1 จนถึง PHP 8+ ปัจจุบัน ขอแนะนำอย่างยิ่งให้ใช้ PHP เวอร์ชันล่าสุดที่รองรับ สำหรับโปรเจ็กต์นี้

เรามุ่งมั่นที่จะมอบตัวเลือกการสนับสนุนระยะยาว (LTS) และมอบเส้นทางการอัปเกรดที่ราบรื่น หากคุณใช้ PHP เวอร์ชันเก่า คุณอาจใช้ 2.x Branch (PHP 5.4+) หรือ 1.x Branch (PHP 5.3+) ซึ่งทั้งคู่มี API ที่เข้ากันได้ แต่ไม่ได้ใช้ประโยชน์จากฟีเจอร์ภาษาที่ใหม่กว่า คุณสามารถกำหนดเป้าหมายหลายเวอร์ชันพร้อมกันเพื่อรองรับ PHP เวอร์ชันต่างๆ ที่กว้างขึ้นดังนี้:

composer require " react/promise:^3 || ^2 || ^1 " 

การทดสอบ

หากต้องการรันชุดทดสอบ คุณต้องโคลน repo นี้ก่อน จากนั้นจึงติดตั้งการขึ้นต่อกันทั้งหมดผ่าน Composer:

composer install

หากต้องการรันชุดทดสอบ ให้ไปที่รูทโปรเจ็กต์แล้วรัน:

vendor/bin/phpunit

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

vendor/bin/phpstan

เครดิต

Promise เป็นพอร์ตของ when.js โดย Brian Cavalier

นอกจากนี้ เอกสารส่วนใหญ่ยังได้รับการย้ายจาก when.js Wiki และเอกสาร API

ใบอนุญาต

เผยแพร่ภายใต้ใบอนุญาต MIT