PHP 8.0: OpenSSL: resource to object migration

Version8.0
TypeChange

Along with PHP's resource to object transformation, PHP's OpenSSL extension changes its resource objects to standard PHP class objects in PHP 8.0.

The newly added class objects are not allowed to be instantiated with new OpenSSL...() constructs, and must be instantiated with the same functions that returned corresponding resource objects in prior PHP versions. Further, they are declared as final, which prevents them from being extended in a sub class.

OpenSSL key resources to OpenSSLAsymmetricKey objects

OpenSSL key resource type (produced by openssl_pkey_new function) is changed to OpenSSLAsymmetricKey class objects.

In PHP 8.0, openssl_pkey_new function returns an instance of OpenSSLAsymmetricKey class instead of OpenSSL key resources. All functions that previously accepted resources now accept the class objects as well.

OpenSSLAsymmetricKey class synopsis

final class OpenSSLAsymmetricKey {}

Instantiating a new object with new OpenSSLAsymmetricKey() construct will raise an error:

new OpenSSLAsymmetricKey();
PHP Error: Cannot directly construct OpenSSLAsymmetricKey, use openssl_pkey_new() instead in ... on line ...

OpenSSL X.509 resources to OpenSSLCertificate objects

In PHP 8.0 and later, openssl_x509_read function returns OpenSSLCertificate class objects instead of OpenSSL X.509 resources it did in PHP versions prior to PHP 8.0.

All functions that accepted/returned OpenSSL X.509 resources now accept/return OpenSSLCertificate objects instead.

OpenSSLCertificate class synopsis

final class OpenSSLCertificate {}

Instantiating a new object with new OpenSSLCertificate() construct will raise an error:

new OpenSSLCertificate();
PHP Error: Cannot directly construct OpenSSLCertificate, use openssl_x509_read() instead in ... on line ...

OpenSSL X.509 CSR resources to OpenSSLCertificateSigningRequest objects

openssl_csr_new returns OpenSSLCertificateSigningRequest objects in PHP 8.0 and later. This function returned OpenSSL X.509 CSR resources in prior PHP versions.

All functions that accepted OpenSSL X.509 CSR resource parameters now accept OpenSSLCertificateSigningRequest objects instead.

OpenSSLCertificateSigningRequest class synopsis

final class OpenSSLCertificateSigningRequest {}

Instantiating a new object with new OpenSSLCertificateSigningRequest() construct will raise an error:

new OpenSSLCertificateSigningRequest();
PHP Error: Cannot directly construct OpenSSLCertificateSigningRequest, use openssl_csr_new() instead in in ... on line ...

is_resource calls

is_resource function will no longer return true on return values of any of the OpenSSL extension functions.

Existing code that used is_resource function to check if the provided value is a valid OpenSSL resource will now need to check against the class names (OpenSSLAsymmetricKey, OpenSSLCertificate, and OpenSSLCertificateSigningRequest, depending on the use case) as well.

Using $value !== false can be used to check the validity as well, and works across all PHP versions.

Deprecation and resource freeing

In PHP 8.0, the following functions are deprecated.

Both of these functions are deprecated because the new objects automatically close the internal handlers when the objects fall out of scope, or when the request terminates.

Backwards Compatibility Impact

All OpenSSL functions return and accept class objects in lieu of the resource counter-parts in older PHP versions.

Unless there are is_resource calls on OpenSSL extensions resource types (pre-PHP 8.0), this update should not introduce any issues.

Note that openssl_pkey_free and openssl_x509_free functions a deprecated in PHP 8.0, and causes deprecation warnings in PHP 8.0. In code that must be backwards-compatible on PHP versions prior to 8.0, those functions needs to be called conditionally to avoid the deprecation notice.

- openssl_pkey_free($key);
+ if (\PHP_VERSION_ID < 80000) {
+   openssl_pkey_free($key);
+}

Implementation