What to include in gitignore for a Laravel and PHPStorm project?
Your initial .gitignore draft handles the most obvious sources of friction: vendor binaries, IDE workspace state, and generated caches. However, when collaborating on a shared codebase, the goal is not just to ignore files; it is to ensure that every developer's environment generates identical output for every build step. If your local builds diverge from CI/CD pipelines or teammates' machines due to ignored artifacts, you will face endless merge conflicts and debugging sessions.
The entries you listed are a solid foundation, but they miss critical nuances regarding Laravel's internal caching mechanisms and PHPStorm's specific file tracking behavior. Let's refine this list by addressing the gaps in your current configuration.
The .idea Directory Nuance
You mentioned encountering issues with .idea/workspace.xml. This is a common trap. While it is good practice to ignore the entire .idea directory, you must be careful about what goes into that directory versus what gets ignored.
PHPStorm creates a .idea/ folder in your repository root (or project root) to store workspace settings like the "Project View" tree, which can include references to local paths. If you ignore .idea/workspace.xml but commit other files inside .idea/, you risk leaking sensitive build configurations or local path mappings into your history.
The standard approach is to ignore the entire .idea directory:
.idea/
However, if you specifically want to exclude only the workspace file while keeping other IDE metadata (like .idea/.phpstorm.meta.php), you can be more granular. But generally, committing any part of .idea/ is risky because it often contains references to local disk paths that will break on another machine.
Laravel-Specific Caches
Your draft includes /bootstrap/compiled.php, which is correct for older Laravel versions. Modern Laravel (6.x and above) uses vendor/middleware, vendor/view, and similar directories within the bootstrap folder, but relying solely on bootstrap/compiled.php might be insufficient depending on your version.
More importantly, you need to explicitly ignore Laravel's opcache files. These are not generated by PHPStorm, but they are critical for preventing "stale code" issues where a developer updates a file but the server (or local artisan serve) serves the old compiled version.
Add these standard Laravel cache directories:
/bootstrap/cache/*
/storage/logs/*.log
/storage/framework/cache/*
/storage/framework/sessions/*
/storage/framework/views/*
/storage/laravel-*.sql
Note that storage/ is often ignored entirely in production, but for a dev environment shared via Git, you might want to ignore specific logs or cache dumps while keeping the storage directory itself tracked if your team manages it manually. However, the safest bet for a standard Laravel project is to ignore the contents of bootstrap/cache and any SQL dumps generated by migrations in storage.
Composer Artifacts
Your list includes composer.phar and composer.lock. The presence of composer.lock is actually a point of contention among senior engineers. While some teams prefer to track it to ensure dependency versions are locked across environments, others argue it should be ignored if they manage dependencies differently or use a monorepo setup where the lock file is generated per-service.
If you choose to ignore it:
composer.lock
Be aware that ignoring composer.lock means every developer must run composer install and manually resolve versions, which can lead to "it works on my machine" syndrome. If your team wants deterministic builds, keep it tracked. If you ignore it, ensure everyone runs composer update consistently.
PHPStorm Meta Files
Beyond workspace.xml, PHPStorm generates .phpstorm.meta.php files. These are hints for the IDE to understand specific classes or functions. They should generally be committed if they contain project-wide rules, but local overrides (like those inside .idea/phpstorm.xml) should be ignored.
Also, do not forget the .DS_Store on macOS and Thumbs.db on Windows. While you have these in your list, ensure they are at the root level:
.DS_Store
Thumbs.db
Final Checklist
Before committing, run git status to see what is actually staged. A common mistake is ignoring a file that was already committed previously. To fix a "dirty" git history where you accidentally committed an ignored file or deleted it from the ignore list, use:
git rm -r --cached .idea/
git add .idea/
This removes the tracked files and re-adds them to the index so they become ignored again. This is often necessary when cloning a repository where the .idea folder was previously committed by mistake.
By tightening your .gitignore to include Laravel's cache artifacts, ensuring the entire .idea directory is excluded, and making an informed decision about composer.lock, you eliminate the most common sources of build inconsistency in PHPStorm + Laravel projects.