What Is New in phpseclib 4.0
| Category | Highlights |
|---|---|
| New Features |
|
| Improvements |
|
| Breaking Changes |
|
Why did phpseclib move CSR, CRL, and SPKAC out of X509?
phpseclib split CSR, CRL, and SPKAC handling into their own dedicated classes instead of bundling everything under the single X509 class. In earlier versions, X509 tried to do double duty as both the certificate model and the entry point for related PKI artifacts, which made the class large and its API harder to reason about.
In practice, this means code that previously called methods like signCSR() or signSPKAC() directly on an X509 instance will need to be updated to use the new dedicated classes. Watch out for this if you have certificate authority tooling or internal PKI automation built on phpseclib, since these call sites are exactly where the change bites hardest.
Most teams that only issue and validate certificates (without touching CSR/CRL/SPKAC generation directly) will see minimal impact from this particular change on its own.
What does PFX and CMS support add to phpseclib?
phpseclib 4.0 adds native support for PFX (PKCS#12) files and CMS (Cryptographic Message Syntax), closing a long-standing gap for teams that need to work with certificate bundles exported from Windows environments, IIS, or third-party certificate authorities.
This matters if your workflow involves:
- Importing certificates and private keys bundled together as
.pfxor.p12files - Signing or verifying CMS-wrapped messages, a format used heavily in S/MIME and some enterprise document-signing pipelines
- Interoperating with systems that export key material in PKCS#12 rather than separate PEM files
Before 4.0, teams typically had to shell out to OpenSSL or another library to handle PFX/CMS, then hand the extracted PEM data back to phpseclib. That extra hop can now be removed from many pipelines.
How does lazy loading for ASN1 affect performance?
Lazy loading for ASN1 means phpseclib now defers parsing parts of an ASN.1 structure until that data is actually accessed, rather than eagerly decoding the entire structure up front. In practice, this reduces unnecessary CPU work and memory allocation when your code only needs a subset of the fields in a certificate or key.
This is most noticeable in applications that process large volumes of certificates, keys, or other DER/BER-encoded structures, such as certificate validation services or bulk key-import tooling. If your workload only reads a small number of fields per structure, you should see a measurable reduction in overhead compared to phpseclib 3.
Why do SSH2 and SFTP now throw exceptions instead of returning false?
phpseclib 4.0 changes SSH2 and SFTP so that failures throw exceptions instead of returning false. Returning false made it easy to miss failures silently, especially in long automation scripts where a single failed put() or exec() call could be swallowed by a loosely checked conditional.
This matters if you have existing code written like:
if (!$sftp->put($remote, $local, SFTP::SOURCE_LOCAL_FILE)) {
// handle failure
}That pattern will no longer catch failures the way it used to, since the failure now surfaces as a thrown exception rather than a falsy return value. In practice, you will want to wrap SSH2 and SFTP calls in try/catch blocks during your upgrade, particularly around connection setup, authentication, and file transfer operations. Most teams find this change actually improves reliability once the migration is done, since failures can no longer be ignored by accident.
What do the namespace change and PHP 8.1 requirement mean for upgrading?
phpseclib 4.0 renames its root namespace from \phpseclib3 to \phpseclib4 and raises the minimum supported PHP version to 8.1.0. Both changes are intentionally breaking, and both need to be planned for before you touch a production deployment.
In practice, the namespace change means every use statement referencing phpseclib3\... needs to be updated to phpseclib4\.... The phpseclib team has flagged a future phpseclib3_compat shim to ease this transition, though it had not been published at the time of this release, so plan for a manual find-and-replace pass in the meantime.
The PHP 8.1 requirement means projects still running PHP 7.4 or 8.0 cannot upgrade to phpseclib 4.0 without first upgrading their PHP runtime. Check your composer.json platform requirements and CI matrix before bumping the dependency, since a mismatched PHP version will fail at install time rather than at runtime.
FAQ: phpseclib 4.0
Is phpseclib 4.0 a drop-in replacement for phpseclib 3?
No, it is not a drop-in replacement because the namespace changed from phpseclib3 to phpseclib4 and the minimum PHP version was raised to 8.1.0.
Do I need to change my composer.json to install phpseclib 4.0?
Yes, you need to update your require line to point at the new major version, for example changing phpseclib/phpseclib to the 4.0 constraint, and confirm your platform PHP version meets 8.1.0 or higher.
Will my existing SSH2 and SFTP error handling still work after upgrading?
Probably not without changes, since code that checks for a false return value from methods like put or exec will no longer catch failures, which now throw exceptions instead.
What happened to CSR, CRL, and SPKAC methods that used to live on X509?
They were split out into their own dedicated classes in 4.0, so calls that previously went through the X509 class need to be updated to use those new classes.
Can phpseclib 4.0 read PKCS12 or PFX files directly?
Yes, phpseclib 4.0 adds native PFX and CMS support, so you can work with PKCS12 bundles without shelling out to OpenSSL first.
Is there a compatibility shim to ease migration from phpseclib3 to phpseclib4?
A phpseclib3_compat shim is planned to ease the namespace transition, but it had not been released alongside 4.0, so most teams will need to update their use statements manually for now.