Case Sensitive File System Errors

August 4th, 2022

Chipper CI is continuous integration, just for Laravel. Give it a try - free!

If you haven't before, someday you will be hitting the error Class xxx does not exist in yyy. You know that class exists tho!

The issue is likely related to case-sensitive file systems on Linux servers.

Case-Insensitive In Development

If you're a Mac or Windows user, chances are good that the filesystem you're using right now is not case-sensitive.

If that's the case, then these two commands are functionally equivalent:

# This:
cat ~/Sites/my-site/config/app.php

# Is equivalent to this:
cat ~/SiTEs/mY-SIte/conFIG/aPP.PhP

Laravel (and PHP in general) uses auto-loading to discover and load classes as they are requested in our code.

On case-insensitive file systems, you can mix the cases up and it will still work:

# This:
$someObject = new \App\Foo\Bar\SomeObject;

# Is equivalent to this:
$someObject = new \aPP\fOo\BaR\SOMEObject;

This is, actually, sort of a problem!

Case-Sensitive Everywhere Else

While most of us are hacking away on Windows/Mac computers, we generally host (and test!) our applications on Linux systems. Linux-based systems almost always uses case-sensitive file systems. This means our capitalization has to line up!


# This works for file `app/Foo/Bar/SomeObject`
# (assuming autoloading is configured to look in directory 
#  "app" for the App namespace)
$someObject = new \App\Foo\Bar\SomeObject;

# This will not work, as file `aPP\fOo\BaR\SOMEObject.php` 
# won't exist on case-sensitive file systems
$someObject = new \aPP\fOo\BaR\SOMEObject;

Case-Sensitivity in Chipper CI

Chipper's build environment is in Linux, and is therefore case-sensitive.

If you hit this issue, you'll often presents itself as an error like this: Class "App\Foo\BarBazThing" not found.

So, if you see an error like that - you're likely referencing a file using the wrong case!

The error usually comes along with a stack trace, so you can track down what file is being used. However, tools such as silverseacher or ripgrep can be used to find content in code files using case-sensitive searches!

# Search for string FOOBazThing
# in our code base using "silversearcher"
ag FOOBazThing

# Or use ripgrep instead:
rg FOOBazThing

These are excellent tools to have installed on your dev machine - they are often faster and better than IDE-based tools at finding specific strings in your code base. As a bonus, they honor .gitignore and can also be modified to ignore huge files such as compiled javascript.

Try out Chipper CI!
Chipper CI is the easiest way to test and deploy your Laravel applications. Try it out - it's free!