The Missing Link in Laravel 5.4 Storage: Symlinks and Permissions
When you call $request->paper_file->store('documents') in Laravel 5.4, the framework correctly places the file inside storage/app/public/documents. Your configuration confirms that the disk is set to local with a root pointing to that directory and visibility marked as public. Logically, accessing /storage/documents/... should work. However, hitting that URL often results in a 404 Not Found error. This isn't a bug in Laravel's file handling logic; it is a deployment configuration issue related to how the web server accesses the storage directory.
The root cause lies in the public disk configuration. By default, Laravel expects your application to run from a location where storage/app/public is directly accessible via the web server's document root (usually public_html or www). When you configure the url to point to /storage, you are telling the application that it should serve files from the storage root relative to the base URL. However, if your web server (Apache or Nginx) is configured to look for files in public/storage/documents instead of storage/app/public/documents, the path resolution breaks.
In a standard development environment using PHP built-in servers, this often works fine because the path is resolved relative to the script's execution context. In production, especially when deploying via FTP or git clones where you cannot symlink the entire storage folder, the web server needs explicit instructions to follow symlinks or map the directory correctly.
If you are on a shared hosting environment or a standard Apache setup without AllowOverride All, the .htaccess file might be blocking access to the storage directory entirely. You must ensure that your virtual host configuration explicitly maps the storage path. For example, if your document root is /var/www/html/public, your Apache config should include:
Alias /storage /path/to/your/app/storage/app/public
<Directory "/path/to/your/app/storage/app/public">
Options -Indexes +FollowSymLinks
AllowOverride All
Require all granted
</Directory>
Without this alias, the URL /storage/documents/file.pdf maps to a non-existent physical path inside the document root, triggering the 404.
Another frequent oversight involves file permissions. Even if the path is correct, the web server user (typically www-data, apache, or nginx) must have read and execute permissions on the storage directory and its parent folders. If you created the directories as your local user, the web server might not be able to traverse into them. Run chmod -R 755 storage or set ownership with chown -R www-data:www-data storage depending on your Linux distribution.
It is also worth noting that in Laravel 5.4, the APP_URL environment variable plays a critical role. If your .env file defines APP_URL=http://yourdomain.com/storage, the framework generates URLs assuming the storage folder is directly accessible at that root. If you are testing locally, ensure APP_URL matches your local domain exactly, including the trailing slash considerations, though Laravel usually handles this gracefully.
If you cannot modify the server configuration to create an alias, the alternative is to change the root in your disk configuration to match the web server's document root structure, but this requires restructuring how you store files initially. The cleanest solution remains ensuring the symlinks or aliases point directly from the document root to storage/app/public.
Finally, always verify that the symlink itself exists if you used php artisan storage:link. In Laravel 5.4, running php artisan storage:link creates a symbolic link from public/storage to ../app/storage. If this command failed silently or was run as a user without permissions, the link would be missing, causing the web server to look for files in the wrong place. Check with ls -la public/ to ensure the symlink is present and points to the correct location.