Eloquentencryption Laravel Package

Getting Started

1. Check your PHP and Laravel versions before composer update. v4.0 requires PHP 8.0+ and Laravel 9. If you are still on Laravel 8 or PHP 7.4, stay on v3.x — v4.0 is a hard floor, not a soft recommendation.
2. composer require <vendor>/<package> "^4.0" and then publish any shipped config:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

3. Look first at the package's config file and service provider bindings. Because the package wraps phpseclib/phpseclib (crypto / SSH / SFTP primitives), the config is where credential shape (key vs. password, key format, passphrase) is decided — that is the file you will spend the most time in.
4. First use case: connect to a remote host (or encrypt a payload) from a service class, not directly from a controller or Blade view. Resolve the package's connection/crypto object out of the container so it can be swapped in tests.

Implementation Patterns

• Wrap, don't sprinkle. Register your own SshService / CryptoService that depends on the package object and bind it as a singleton. Every controller, command, and job then depends on your class, so a future phpseclib 3.x migration only touches one file.
• Connection reuse. SSH handshakes are expensive. Resolve the client once per job/command lifecycle rather than per call, and explicitly disconnect() in a finally block — long-lived workers leak sockets otherwise.
• Queue it. Remote transfers and RSA operations are I/O-bound and slow. Dispatch a job, close the connection at the end of handle(), and use $this->timeout / retryUntil() generously.
• Credentials via config + env, never inline. Point the config at env('SSH_KEY_PATH') and store the key outside the repo; on Laravel 9 use the config() cache-safe pattern (php artisan config:cache will bake in env values, so keep secrets read at runtime if they rotate).
• Key handling. Load keys with phpseclib's PublicKeyLoader at runtime rather than committing .pem files. Support both PKCS#1 and PKCS#8/OpenSSH formats — this is the most common "works locally, fails in prod" cause.
• Test with a fake. Never hit a real host in the test suite. Bind a fake implementation of your wrapper interface in the container, or use phpseclib's in-memory RSA keys for crypto paths.
• Integration tip: if you already use Laravel's Storage for local files, keep the same mental model — read a local stream, push it through the package, land it remotely. Don't buffer whole files in memory.

Gotchas and Tips

• v4.0 is a breaking release in disguise. The notes read as "framework bump + dependency pin," but dropping Laravel 8/PHP 7.x breaks CI matrices, composer.lock files, and any downstream package that still constrains this one. Audit transitive constraints before upgrading.
• phpseclib 2.0.37 is the end of the 2.0 line. It is receiving security fixes only; upstream is on 3.x. Treat v4.0 as a stopgap: the 2.x → 3.x API change (namespaces, PublicKeyLoader, SFTP → SFTP\SFTP) is the real migration you should be planning for. Keep it isolated behind your wrapper now.
• Host key verification is usually off by default. phpseclib will happily connect to a MITM unless you assert the server fingerprint. If the package doesn't expose this, add it yourself — pin the fingerprint in config.
• Timeouts and keepalive. Default socket timeouts are long enough to hang a queue worker. Set explicit setTimeout() values and enable keepalive for long transfers or you will get silent stalls on idle NAT/firewalls.
• Memory on large SFTP transfers. Use SFTP::get()/put() with stream resources or nlist/rawlist pagination — reading a 2 GB file into a string will OOM before it finishes.
• Debugging: phpseclib's own logging is your best tool. Attach a phpseclib\Net\SSH2 logger (PSR-3) behind a debug config flag, and remember Laravel's Log facade satisfies the interface.
• Extension points: the service provider bindings and the config file are the intended seams. If you need custom auth (agent forwarding, jump hosts), decorate the package's client rather than forking it — you'll want the clean upgrade path when 3.x arrives.
• Watch the changelog, not just the version number. These release notes don't mention behavioral changes, but a dependency pin at 2.0.37 can silently alter cipher negotiation or key-parsing edge cases. Run your SSH/crypto integration tests explicitly after upgrading, not just the unit suite.