The Hidden State in composer.json and Why Removing a Package Isn't Just About Editing Files
When you decide to remove a dependency from a Laravel application, the instinct is often to simply edit the composer.json file, delete the class aliases from your configuration, scrub the code references, and then run composer update. While these steps address the logical dependencies, they frequently leave residual state that breaks the application or causes confusing errors. The issue usually lies in how Composer manages the local installation directory and how Laravel's autoloader interacts with it.
The first critical step is ensuring the package actually disappears from your project's physical file structure. Editing composer.json removes the instruction to install the package, but it does not automatically delete the vendor folder contents associated with that specific dependency. If you run composer update, Composer will notice the removal and delete the relevant directory entries in vendor/. However, if you rely solely on composer dump-autoload without running a fresh update or installation command after modifying composer.json, the old classes might still be cached in memory or referenced by the autoloader map.
There is a specific nuance regarding the app.php file (or its modern equivalent in newer Laravel versions, often handled automatically via service providers). Removing class aliases manually is a good start, but if you are using older conventions where service providers were registered explicitly in config files or boot methods, those calls must also be removed. Simply deleting the alias isn't enough; the code that triggers the alias registration needs to be gone as well.
The most common pitfall occurs after running composer update. Even though Composer cleans up the vendor directory, your application's memory state might still hold references if the script was not restarted properly. Furthermore, Laravel caches its configuration and route definitions in .env or cache directories (like storage/framework/cache). If a package modified these cached files during its operation, simply removing the package won't revert those changes until you clear the cache.
You should always run php artisan config:clear, php artisan route:clear, and php artisan cache:clear after uninstalling a significant dependency. These commands ensure that Laravel is not trying to autoload classes or load configuration keys that no longer exist. If your application still throws "Class not found" errors or "Undefined property" exceptions, it is often because the autoloader map in vendor/composer/autoload_classmap.php contains stale entries. Running composer dump-autoload --optimize forces Composer to regenerate this map, but only after the dependency has been fully removed from the require section and the vendor directory.
Another scenario involves packages that install artisan commands or console scripts. If you run a command like php artisan package:discover (or similar lifecycle events handled by the package), those commands might persist in your global registry or local bin folder even after the dependency is removed. You may need to manually check the vendor/bin directory and remove any executables that belong to the uninstalled package.
If you are maintaining a large Laravel project, consider using Composer's remove command directly on the command line instead of manually editing JSON. Running composer remove vendor/package-name ensures that all associated scripts, autoloaders, and dependencies are handled atomically by the tool itself. This approach prevents partial removals where the JSON file is clean but the vendor folder retains orphaned files.
For teams managing multiple environments, always verify that the .env file does not contain hardcoded paths or configuration keys specific to the removed package. Sometimes packages register environment variables; leaving these keys can lead to unexpected behavior if the application expects them to be unset or null.
Finally, if you encounter persistent issues where the application refuses to start after removal, check the vendor/composer/installed.php file. This file tracks which packages are installed and their version constraints. If this file is out of sync with your composer.json, it can cause Composer to think the package is still present or that a version mismatch exists. Regenerating the lock file with composer update after cleaning up composer.json resolves most synchronization issues.
By following a strict sequence of removal, cache clearing, and autoloader regeneration, you ensure a clean slate for your Laravel application without leaving behind hidden dependencies that could cause instability in production environments.
