Public disk and symbolic links in Laravel - Deep Dive

Overview - Public disk and symbolic links

What is it?

In Laravel, the public disk is a storage location meant for files that should be accessible from the web. Symbolic links are special shortcuts that connect one folder to another, allowing files stored in protected areas to be accessed publicly without moving them. Laravel uses symbolic links to connect the storage folder to the public folder, making files like images or documents available on the website.

Why it matters

Without the public disk and symbolic links, developers would have to manually copy files to public folders every time they want users to access them, which is inefficient and error-prone. This setup keeps files organized and secure while still allowing easy public access. It also helps websites serve user-uploaded files smoothly, improving user experience and site management.

Where it fits

Before learning this, you should understand Laravel's filesystem basics and how storage works. After this, you can explore advanced file handling, cloud storage integration, and managing file permissions securely.

Mental Model

Core Idea

A symbolic link in Laravel acts like a bridge that connects private storage to the public web folder, enabling safe and easy access to files from the internet.

Think of it like...

Imagine your house has a locked storage room where you keep valuable items. Instead of carrying items outside every time, you create a special window (symbolic link) that lets trusted people see or take items without opening the whole room.

storage/app/public  ──┐
                        │  (symbolic link)
                        ▼
public/storage  ──────────> Accessible folder for web users

Build-Up - 6 Steps

1

Foundation

Understanding Laravel Storage Basics

Concept: Learn what Laravel storage disks are and how they organize files.

Laravel uses 'disks' to manage where files are stored. The 'local' disk stores files inside the app folder, which is not accessible from the web. The 'public' disk stores files meant to be shared publicly, but these files are actually stored in a protected folder until linked.

Result

You know that files saved to the public disk are stored safely but not yet visible on the website.

Understanding storage disks helps you organize files by access level, keeping private and public files separate.

2

Foundation

What is a Symbolic Link?

Concept: Introduce symbolic links as shortcuts connecting folders.

A symbolic link is like a shortcut or alias that points from one folder to another. In Laravel, it connects the storage folder to the public folder, so files stored privately can be accessed publicly without copying.

Result

You understand that symbolic links let you share files without moving them physically.

Knowing symbolic links prevents confusion about why files appear in public folders without being duplicated.

3

Intermediate

Creating the Public Disk Symbolic Link

🤔Before reading on: Do you think Laravel creates the symbolic link automatically or requires a manual command? Commit to your answer.

Concept: Learn how to create the symbolic link using Laravel's artisan command.

Laravel provides the command 'php artisan storage:link' to create a symbolic link from 'public/storage' to 'storage/app/public'. This command must be run once after setting up the project or when deploying.

Result

After running the command, files saved to the public disk become accessible via the web through the 'storage' URL path.

Understanding this command is crucial because without the symbolic link, public files remain inaccessible from the browser.

4

Intermediate

Accessing Files via the Public Disk

🤔Before reading on: Do you think files saved to the public disk are accessible via a URL matching their storage path or a different path? Commit to your answer.

Concept: Learn how URLs map to files stored on the public disk through the symbolic link.

Files saved to 'storage/app/public' can be accessed in the browser at 'yourdomain.com/storage/filename'. The symbolic link makes 'public/storage' point to 'storage/app/public', so the web server serves these files correctly.

Result

You can display images or download files stored on the public disk by using URLs starting with '/storage/'.

Knowing the URL pattern helps you correctly link to user-uploaded files in your views or APIs.

5

Advanced

Managing Symbolic Link Issues in Production

🤔Before reading on: Do you think symbolic links always work the same on all servers or can server settings affect them? Commit to your answer.

Concept: Explore common problems with symbolic links on different hosting environments and how to fix them.

Some servers or shared hosting environments may not support symbolic links or require special permissions. You might need to create the link manually or adjust server settings. Also, clearing caches or restarting the server can help if files don't appear.

Result

You can troubleshoot why public disk files are not accessible and fix symbolic link problems in production.

Understanding server differences prevents deployment headaches and ensures reliable file access.

6

Expert

Security and Performance Considerations

🤔Before reading on: Is it safe to store sensitive files on the public disk if symbolic links are used? Commit to your answer.

Concept: Learn the security risks and performance impacts of using the public disk and symbolic links.

Files on the public disk are accessible to anyone with the URL, so sensitive files should never be stored there. Use private disks for sensitive data. Also, symbolic links add minimal overhead but improper use can expose files unintentionally. Cache headers and CDN can improve performance serving public files.

Result

You know how to protect sensitive data and optimize public file delivery in Laravel.

Knowing these limits helps you design secure and efficient file storage strategies.

Under the Hood

Laravel's filesystem uses the Flysystem PHP package to abstract storage disks. The public disk points to 'storage/app/public' folder. The symbolic link created by 'php artisan storage:link' is a filesystem shortcut named 'public/storage' that points to this folder. When a web request asks for a file under '/storage', the server follows the symbolic link to serve the actual file. This avoids duplicating files and keeps storage organized.

Why designed this way?

Laravel separates storage from public files to improve security and organization. Instead of exposing the entire storage folder, only the public disk is linked. Symbolic links allow this without copying files, saving space and sync effort. This design balances ease of access with protection of private data.

┌───────────────┐       symbolic link       ┌─────────────────────┐
│ public/storage│ ─────────────────────────>│ storage/app/public   │
└───────────────┘                           └─────────────────────┘
        ▲                                           ▲
        │                                           │
   Web server serves files                   Laravel stores files here

Myth Busters - 4 Common Misconceptions

Quick: Do you think files saved to the public disk are automatically accessible on the web without extra setup? Commit to yes or no.

Common Belief: Files saved to the public disk are immediately accessible from the web without any additional steps.

Reality: Files become accessible only after creating the symbolic link with 'php artisan storage:link'. Without this, files remain inaccessible from the browser.

Why it matters: Assuming files are accessible without the link leads to confusion and broken image or download links in the application.

Quick: Do you think symbolic links duplicate files physically on the server? Commit to yes or no.

Common Belief: Symbolic links copy the files to the public folder, so there are two copies of each file.

Reality: Symbolic links are just pointers; they do not duplicate files. Only one copy exists in storage, saving disk space.

Why it matters: Misunderstanding this can cause unnecessary file management or storage concerns.

Quick: Do you think storing sensitive files on the public disk is safe if you don't share their URLs? Commit to yes or no.

Common Belief: Sensitive files can be stored on the public disk safely as long as you don't link to them.

Reality: Any file on the public disk is accessible if someone guesses or knows the URL, so sensitive files should never be stored there.

Why it matters: Ignoring this can cause serious data leaks and security breaches.

Quick: Do you think symbolic links behave the same on all hosting environments? Commit to yes or no.

Common Belief: Symbolic links always work the same way on any server or hosting environment.

Reality: Some servers restrict symbolic links or require manual creation and permission adjustments.

Why it matters: Assuming uniform behavior leads to deployment failures and inaccessible files in production.

Expert Zone

1

Symbolic links can break if the target folder is moved or renamed, requiring careful deployment scripts to maintain links.

2

Using relative symbolic links instead of absolute paths can improve portability across environments.

3

Caching headers and CDN integration for files served via the public disk can greatly improve performance but require extra configuration.

When NOT to use

Avoid using the public disk and symbolic links for sensitive or private files; instead, use private disks with controlled access. Also, on hosting environments that do not support symbolic links, consider alternative file serving methods like copying files or using cloud storage with signed URLs.

Production Patterns

In production, teams automate the 'storage:link' command in deployment scripts to ensure symbolic links exist. They also separate user uploads into the public disk and keep backups on private disks. For large apps, CDNs serve public disk files to reduce server load and improve speed.

Connections

Filesystem Permissions

Builds-on

Understanding filesystem permissions helps manage who can create symbolic links and access storage folders, preventing permission errors.

Content Delivery Networks (CDN)

Builds-on

Knowing how symbolic links expose files publicly helps integrate CDNs to serve these files faster and more securely.

Operating System Shortcuts

Same pattern

Symbolic links in Laravel work like OS shortcuts, showing how software concepts often mirror everyday computer usage.

Common Pitfalls

#1 Forgetting to run the symbolic link command after deployment.

Wrong approach:

php artisan migrate

Correct approach:

php artisan storage:link

Root cause:

Confusing database setup commands with filesystem setup commands leads to inaccessible public files.

#2 Storing sensitive files on the public disk expecting them to be private.

Wrong approach:

Storage::disk('public')->put('secret.txt', 'private data');

Correct approach:

Storage::disk('local')->put('secret.txt', 'private data');

Root cause:

Misunderstanding the public disk's purpose causes security risks.

#3 Assuming symbolic links work on all servers without checking permissions.

Wrong approach:

Relying on 'php artisan storage:link' without verifying server support.

Correct approach:

Manually creating symbolic links or adjusting server settings when needed.

Root cause:

Not accounting for hosting environment differences causes deployment failures.

Key Takeaways

Laravel's public disk stores files meant to be accessible from the web but requires a symbolic link to make them visible.

Symbolic links act as shortcuts connecting private storage folders to public web folders without duplicating files.

Running 'php artisan storage:link' is essential to create this connection and enable public access.

Files on the public disk are accessible by anyone with the URL, so sensitive data must be stored elsewhere.

Understanding server environments and permissions is crucial to ensure symbolic links work correctly in production.