I recently encountered an issue that took me far longer to solve that it should have. Laravel is an excellent framework for building PHP websites. I have used it to build several sites now and it is by far the best framework I have seen. The latest version, Laravel 5, is powerful and well documented. With Composer, Laravel is easily extendable and allows you to pull in common php packages.
Up to this point, I had used Composer to pull in packages and manage dependencies without really knowing how it worked. Unfortunately, due to my lack of understanding, Composer’s Autoload feature caused an issue that was very hard to debug.
In the site I was making, I created a new configuration file that was used to dynamically set routes so I could create new sections and add those sections to the navigation menus in one step.
Next, I created a template controller that I would simply copy, rename, and start working with for each of these new sections.
Everything was working fine until I used Composer to install a new package on my production system. I installed Guzzle to which is need to interface with MailGun. When you install a new package Composer updates composer.json, installs the package, and reruns dump-autoload.
After setting up email, I thought the site was ready for production. All the sudden, one of my many dynamically created sections was not working. For some reason, the route for this one section was calling the Template Controller instead of the proper controller.
First, I though one of Laravel’s many layers of caching was the issue. I disabled Laravel’s route caching, configuration caching and view caching. I even turned off mod_pagespeed and CloudFlare just to be sure no caching was the problem. But it still was not working.
I decided to hard code the routes to skip over my dynamic route generator. But still for just one section the Template Controller was being called instead of the proper controller. I checked the routes file again and again to ensure there was no earlier route being called.
Eventually, I removed the Template Controller entirely and the section in question would error out saying TemplateController.php was not found. But how was this controller being called? The section was working before. Everything was working on my development machine. Just in production, this one section of the site was not working. For some reason, this route:
Route::get('/quarters',
['as' => 'quarters', 'uses' => 'Content\QuartersController@index']);
would call the TemplateController@index
At this point I had completely deleted the Template Controller. Something must be calling Template Controller somewhere.
So I decide to SSH into my production server and run:
$ grep -R 'TemplateController' public_html/
That grep command searches the entire web directory recursively for the string ‘TemplateController.’
As you can see, the string was first found in an error log file. But the final match led to the solution.
We can see a file called `vendor/composer/autoload_classmap.php` contains a line that seems to be mapping the `QuartersController` class to the `TemplateControllers` class. How did that get there?
It turns out, that when I created the `TemplateController` file, I did it by copying the `QuartersController` and stripping out all of the code specific the that section. Unfortunately, I forgot to change the name of the class in the `TemplatesController.php` file. I accidentally left that class name as `QuartersController`.
Now, that should not be an issue. I am not even using the `TemplatesController` class. It is only there for a starting point when creating new sections.
What I did not know at the time is when your run composer dump-autoload , composer scans your entire project’s source code and creates a `autoload_classmap.php` file. The classmap files allows the application to more quickly find the file containing a particular class.
Because I had two classes with the same name (one of them not being used), composer mapped to the wrong file. I changed the TemplateController.php class name, reran dump-autoload and everything worked again!
This error only surfaced after installing Guzzle because after a package install, composer runs dump-autoload automatically.
The moral here is that you can only use a tool without knowing how it works for so long before it comes back to bite you.