fix(ssl): copy and validate custom certs on site update

[mrrobot47]

Problem

ee site update --ssl=custom set the DB flag and enabled HTTPS but never copied the certificate files. update_ssl() calls www_ssl_wrapper(), which explicitly skips all cert work for custom, and the cert-copy helpers (validate_site_custom_ssl() / custom_site_ssl()) were only invoked from the create path. Result: HTTPS turned on with no certs in nginx-proxy/certs/, so the site served a wrong/default cert. This is also the path Cloner.php recommends after cloning a custom-SSL site, so that guidance led to a broken state too.

Fix

In update_ssl(), when the target type is custom, mirror the create path: validate --ssl-key/--ssl-crt via validate_site_custom_ssl() and copy them via custom_site_ssl() before www_ssl_wrapper(). Also documents the --ssl-key/--ssl-crt flags and adds an example. To replace an expiring custom cert, disable SSL and re-enable it with the new pair (ee site update <site> --ssl=off, then ee site update <site> --ssl=custom --ssl-key=... --ssl-crt=...); running --ssl=custom on a site that already has SSL still stops with "SSL is already enabled".

Missing or nonexistent --ssl-key/--ssl-crt fails fast (inside the existing try/catch, before $site->save()), and so does a certificate that isn't valid PEM, a broken chain or a key that doesn't match the certificate, through #492's assert_valid_cert_key_pair() in validate_site_custom_ssl(). Nothing is copied and there is no partial DB-vs-cert state. Re-enabling with the files already in nginx-proxy/certs/ as the source no longer truncates them.

Known limitation

If the post-copy bring-up (www_ssl_wrapper) throws, the copied cert files are left in place (no rollback); re-running the command overwrites them. The create path's catch_clean unwind is not mirrored here — a follow-up could unify the two cert paths.

Testing

Manual: create a non-SSL site, generate a self-signed key/crt, run ee site update <site> --ssl=custom --ssl-key=... --ssl-crt=..., and assert nginx-proxy/certs/<site>.key|.crt exist and the served cert matches.

Tested on Ubuntu 26.04 with EasyEngine 4.12.0: valid pair with relative paths (served cert matches, HTTP redirects to HTTPS), missing flags, nonexistent path and mismatched pair (rejected, nothing copied), same-path re-enable, the off-then-custom replacement flow, and create --ssl=custom regressions.

Merge note

Depends on #492 and must merge after it. The certificate content checks on site update (PEM parse, chain, key match) come from #492's validator, so this PR no longer carries its own key/cert match check.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.