promise
v3.2.0
PHP용 CommonJS Promises/A의 경량 구현입니다.
Promise는 PHP용 CommonJS Promises/A를 구현하는 라이브러리입니다.
또한 여러 Promise 결합, Promise 컬렉션 매핑 및 축소와 같은 몇 가지 유용한 Promise 관련 개념도 제공합니다.
이전에 Promise에 대해 들어본 적이 없다면 먼저 이 내용을 읽어보세요.
Deferred는 아직 완료되지 않은 계산 또는 작업 단위를 나타냅니다. 일반적으로(항상 그런 것은 아님) 해당 계산은 비동기식으로 실행되고 향후 특정 시점에 완료됩니다.
Deferred는 계산 자체를 나타내는 반면 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() 가 반환한 promise를 해결합니다. 모든 소비자는 $value 로 $onFulfilled ( $promise->then() 통해 등록)를 호출하여 알림을 받습니다.
$value 자체가 Promise인 경우 Promise는 해결된 후 이 Promise 상태로 전환됩니다.
resolve() 함수도 참조하세요.
$ deferred -> reject (Throwable $ reason ); promise() 가 반환한 promise를 거부하여 지연된 계산이 실패했음을 알립니다. 모든 소비자는 $reason 으로 $onRejected ( $promise->then() 통해 등록)를 호출하여 알림을 받습니다.
reject() 함수도 참조하세요.
Promise 인터페이스는 모든 Promise 구현에 대한 공통 인터페이스를 제공합니다. 이 패키지에 의해 노출되는 유일한 공개 구현은 Promise를 참조하세요.
약속은 이행(성공) 및 관련 값 또는 거부(실패) 및 관련 이유인 최종 결과를 나타냅니다.
이행 또는 거부 상태가 되면 약속은 변경할 수 없게 됩니다. 상태나 결과(또는 오류)는 수정할 수 없습니다.
$ transformedPromise = $ promise -> then (callable $ onFulfilled = null , callable $ onRejected = null );Promise의 이행 또는 거부 값에 함수를 적용하여 Promise의 값을 변환합니다. 변환된 결과에 대한 새로운 약속을 반환합니다.
then() 메소드는 Promise를 사용하여 새로운 이행 및 거부 핸들러를 등록합니다(모든 매개변수는 선택사항임).
$onFulfilled 약속이 이행되고 결과가 첫 번째 인수로 전달되면 호출됩니다.$onRejected Promise가 거부되고 이유를 첫 번째 인수로 전달하면 호출됩니다. $onFulfilled 또는 $onRejected 중 어느 쪽이든 호출되는 반환 값으로 이행하거나, 둘 중 하나가 발생하면 던져진 예외를 거부하는 새로운 약속을 반환합니다.
Promise는 then() 에 대한 동일한 호출에 등록된 핸들러에 대해 다음을 보장합니다.
$onFulfilled 또는 $onRejected 중 하나만 호출되며 둘 다 호출되지는 않습니다.$onFulfilled 및 $onRejected 두 번 이상 호출되지 않습니다. $ promise -> catch (callable $ onRejected );Promise에 대한 거부 핸들러를 등록합니다. 다음 항목에 대한 바로가기입니다.
$ promise -> then ( null , $ onRejected ); 또한 $onRejected 의 $reason 인수에 힌트를 입력하여 특정 오류만 포착할 수 있습니다.
$ 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 );Promise 체인에서 "정리" 유형 작업을 실행할 수 있습니다.
Promise가 이행되거나 거부될 때 인수 없이 $onFulfilledOrRejected 호출되도록 준비합니다.
$promise 이행되고 $onFulfilledOrRejected 성공적으로 반환되면 $newPromise $promise 와 동일한 값으로 이행됩니다.$promise 이행되고 $onFulfilledOrRejected 거부된 Promise를 던지거나 반환하는 경우 $newPromise 던져진 예외 또는 거부된 Promise의 이유를 거부합니다.$promise 거부하고 $onFulfilledOrRejected 성공적으로 반환되면 $newPromise $promise 와 동일한 이유로 거부합니다.$promise 거부하고 $onFulfilledOrRejected 거부된 Promise를 던지거나 반환하는 경우 $newPromise 던져진 예외 또는 거부된 Promise의 이유를 거부합니다. finally() 동기식 finally 문과 유사하게 동작합니다. catch() 와 결합하면 finally() 사용하여 익숙한 동기식 catch/finally 쌍과 유사한 코드를 작성할 수 있습니다.
다음 동기 코드를 고려해보세요.
try {
return doSomething ();
} catch ( Throwable $ e ) {
return handleError ( $ e );
} finally {
cleanup ();
} 유사한 비동기 코드(promise를 반환하는 doSomething() 포함)를 작성할 수 있습니다.
return doSomething ()
-> catch ( ' handleError ' )
-> finally ( ' cleanup ' ); $ promise -> cancel (); cancel() 메서드는 작업 결과에 더 이상 관심이 없다는 것을 약속 생성자에게 알립니다.
약속이 확정되면(이행되거나 거부됨) 약속에 대해 cancel() 호출해도 아무런 효과가 없습니다.
v3.0.0부터 더 이상 사용되지 않습니다. 대신
catch()참조하세요.
otherwise() 메소드는 Promise에 대한 거부 핸들러를 등록합니다.
이 방법은 BC 이유와 버전 간 업그레이드를 용이하게 하기 위해서만 계속 존재합니다. 이는 다음의 별칭입니다.
$ promise -> catch ( $ onRejected );v3.0.0부터 더 이상 사용되지 않습니다. 대신
finally()참조하세요.
always() 메소드를 사용하면 Promise 체인에서 "정리" 유형 작업을 실행할 수 있습니다.
이 방법은 BC 이유와 버전 간 업그레이드를 용이하게 하기 위해서만 계속 존재합니다. 이는 다음의 별칭입니다.
$ promise -> finally ( $ onFulfilledOrRejected ); $resolver 에 전달된 함수에 의해 상태가 제어되는 Promise를 생성합니다.
$ 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 );Promise 생성자는 두 개의 인수로 호출되는 확인 함수와 선택적 취소 함수를 받습니다.
$resolve($value) - 반환된 Promise의 운명을 결정하는 기본 함수입니다. 약속이 아닌 값이나 다른 약속을 받아들입니다. 약속되지 않은 값으로 호출되면 해당 값으로 약속을 이행합니다. 다른 Promise(예: $resolve($otherPromise) 와 함께 호출되면 Promise의 운명은 $otherPromise 의 운명과 같습니다.$reject($reason) - 약속을 거부하는 함수입니다. $reject() 사용하는 대신 예외를 발생시키는 것이 좋습니다.확인자나 취소자가 예외를 발생시키면 해당 예외를 거부 사유로 삼아 Promise가 거부됩니다.
확인자 함수는 즉시 호출되며, 취소자 함수는 모든 소비자가 약속의 cancel() 메서드를 호출한 후에만 호출됩니다.
Promise 컬렉션을 생성하고 결합하는 데 유용한 기능입니다.
Promise 컬렉션(예: all() , race() 등)에서 작동하는 모든 함수는 취소를 지원합니다. 즉, 반환된 Promise에 대해 cancel() 호출하면 컬렉션의 모든 Promise가 취소됩니다.
$ promise = React Promise resolve (mixed $ promiseOrValue ); 제공된 $promiseOrValue 에 대한 약속을 만듭니다.
$promiseOrValue 값이면 반환된 Promise의 해결 값이 됩니다.
$promiseOrValue 가 thenable( then() 메서드를 제공하는 모든 객체)인 경우 thenable의 상태를 따르는 신뢰할 수 있는 약속이 반환됩니다.
$promiseOrValue 약속인 경우 그대로 반환됩니다.
결과 $promise PromiseInterface 를 구현하고 다른 Promise처럼 사용할 수 있습니다.
$ 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 에 대해 거부된 약속을 만듭니다.
PHP 7에 도입된 Throwable 인터페이스는 사용자의 Exception 및 Error 내부 PHP 오류를 모두 포함합니다. Promise를 거부하는 이유로 Throwable 적용하면 언어 오류나 사용자 예외를 사용하여 Promise를 거부할 수 있습니다.
결과 $promise PromiseInterface 를 구현하고 다른 Promise처럼 사용할 수 있습니다.
$ 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 ;
}); 거부된 Promise는 항상 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() 메서드를 사용하여 거부 이유를 포착하면 거부된 Promise는 "처리된" 것으로 간주됩니다. 이러한 각 메서드는 예외가 다시 발생하면 다시 거부될 수 있는 새로운 Promise를 반환합니다.
취소된 Promise는 cancel() 메서드를 사용하여 작업을 중단하는 경우에도 "처리된" 것으로 간주됩니다(대개 보류 중인 Promise는 일반적으로 거부됩니다).
set_rejection_handler() 함수도 참조하세요.
$ promise = React Promise all (iterable $ promisesOrValues ); $promisesOrValues 의 모든 항목이 해결된 후에만 해결되는 약속을 반환합니다. 반환된 Promise의 해결 값은 $promisesOrValues 에 있는 각 항목의 해결 값을 포함하는 배열이 됩니다.
$ promise = React Promise race (iterable $ promisesOrValues );한 명의 승자를 허용하는 경쟁 경주를 시작합니다. 첫 번째 확정된 프로미스가 해결되는 것과 같은 방식으로 해결되는 프로미스를 반환합니다.
$promisesOrValues 에 항목이 0개 있으면 반환된 Promise는 무한정 보류 상태가 됩니다.
$ promise = React Promise any (iterable $ promisesOrValues ); $promisesOrValues 의 항목 중 하나가 해결될 때 해결될 약속을 반환합니다. 반환된 Promise의 해결 값은 트리거 항목의 해결 값이 됩니다.
반환된 Promise는 $promisesOrValues 의 모든 항목이 거부된 경우에만 거부됩니다. 거부 값은 모든 거부 이유를 포함하는 ReactPromiseExceptionCompositeException 이 됩니다. 거부 이유는 CompositeException::getThrowables() 사용하여 얻을 수 있습니다.
$promisesOrValues 에 0개 항목이 포함된 경우 반환된 Promise는 ReactPromiseExceptionLengthException 과 함께 거부됩니다.
React Promise set_rejection_handler(?callable $ callback ): ?callable;처리되지 않은 약속 거부에 대한 전역 거부 핸들러를 설정합니다.
거부된 Promise는 항상 try + catch 블록에서 예외를 포착하는 방식과 유사하게 처리되어야 합니다. 처리되지 않은 거부된 프로미스에 대한 마지막 참조를 제거하면 처리되지 않은 프로미스 거부가 보고됩니다. 자세한 내용은 reject() 함수를 참조하세요.
?callable $callback 인수는 기본 Promise 거부 핸들러를 복원하기 위해 단일 Throwable 인수 또는 null 값을 허용하는 유효한 콜백 함수여야 합니다. 콜백 함수의 반환 값은 무시되고 아무런 효과가 없으므로 void 값을 반환해야 합니다. 콜백 함수는 절대로 던져서는 안 됩니다. 그렇지 않으면 프로그램이 치명적인 오류로 종료됩니다.
이 함수는 이전 거부 핸들러를 반환하거나 기본 약속 거부 핸들러를 사용하는 경우 null 반환합니다.
기본 약속 거부 핸들러는 오류 메시지와 스택 추적을 기록합니다.
// Unhandled promise rejection with RuntimeException: Unhandled in example.php:2
React Promise reject ( new RuntimeException ( ' Unhandled ' )); 약속 거부 핸들러는 로그 메시지를 사용자 정의하거나 사용자 정의 로그 대상에 기록하는 데 사용될 수 있습니다. 경험상 이 함수는 최후의 수단으로만 사용해야 하며 promise 거부는 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 체인은 일반적으로 여러 함수 호출 또는 애플리케이션 아키텍처의 여러 수준에 걸쳐 분산됩니다.
해결된 약속은 해결 값을 다음 약속으로 전달합니다. 첫 번째 약속인 $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" 거부된 Promise는 유사하게 작동하며 try/catch와 유사하게 작동합니다. 예외를 포착하면 전파되도록 다시 발생시켜야 합니다.
마찬가지로, 거부된 Promise를 처리할 때 거부를 전파하려면 거부된 Promise를 반환하거나 실제로 던져서 "다시 발생"하십시오(Promise는 던져진 예외를 거부로 변환하므로).
$ 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를 사용하는 것입니다. Composer를 처음 사용하시나요?
이 프로젝트는 SemVer를 따릅니다. 그러면 이 분기에서 지원되는 최신 버전이 설치됩니다.
composer require react/promise:^3.2버전 업그레이드에 대한 자세한 내용은 CHANGELOG를 참조하세요.
이 프로젝트는 모든 플랫폼에서 실행되는 것을 목표로 하므로 PHP 확장이 필요하지 않으며 PHP 7.1부터 현재 PHP 8+까지의 실행을 지원합니다. 이 프로젝트에는 지원되는 최신 PHP 버전을 사용하는 것이 좋습니다 .
우리는 장기 지원(LTS) 옵션을 제공하고 원활한 업그레이드 경로를 제공하기 위해 최선을 다하고 있습니다. 이전 PHP 버전을 사용하는 경우 호환되는 API를 제공하지만 최신 언어 기능을 활용하지 않는 2.x 분기(PHP 5.4+) 또는 1.x 분기(PHP 5.3+)를 사용할 수 있습니다. 다음과 같이 더 넓은 범위의 PHP 버전을 지원하기 위해 동시에 여러 버전을 대상으로 할 수 있습니다.
composer require " react/promise:^3 || ^2 || ^1 " 테스트 스위트를 실행하려면 먼저 이 저장소를 복제한 다음 Composer를 통해 모든 종속성을 설치해야 합니다.
composer install테스트 스위트를 실행하려면 프로젝트 루트로 이동하여 다음을 실행하십시오.
vendor/bin/phpunit또한 프로젝트 전반에 걸쳐 유형 안전성을 보장하기 위해 최대 수준에서 PHPStan을 사용합니다.
vendor/bin/phpstanPromise는 Brian Cavalier가 만든 when.js의 포트입니다.
또한 문서의 상당 부분이 when.js Wiki 및 API 문서에서 옮겨졌습니다.
MIT 라이선스로 출시되었습니다.
