symlink()

Introduction

In PHP, the symlink() function creates a symbolic link (also called a symlink or soft link) — a special file that acts as a pointer to another file or directory. Instead of copying data, a symlink lets two paths refer to the same underlying target, so changes made through either path affect the same file.

Symlinks are handy when you need a stable, predictable path (for example current always pointing at the latest release directory), want to expose the same file under several names, or need to share a configuration file across projects without duplicating it.

This article covers the syntax, parameters, return value, common gotchas, and runnable examples.

How a Symbolic Link Works

A symbolic link stores a path to its target rather than a copy of the data. This differs from a hard link (created with link()), which points directly at the file's data on disk:

• A symlink can point to a directory and can cross filesystem boundaries; if the target is deleted, the symlink becomes "dangling" (broken).
• A hard link only works for files on the same filesystem and keeps the data alive even after the original name is removed.

Because a symlink only holds a path, that path can be relative (resolved against the directory the link lives in) or absolute.

Syntax

symlink(string $target, string $link): bool

symlink() returns true on success and false on failure (and emits a warning). It fails if $link already exists, if you lack write permission in the link's directory, or if symlinks are unsupported on the platform.

Example 1: Creating and Reading a Symbolic Link

This complete example creates a file, links to it, then proves the link points back at the original:

<?php
// Create the real file.
file_put_contents('example.txt', 'Hello from the target file');

// Create a symbolic link to it.
symlink('example.txt', 'example_link.txt');

// Reading through the link reads the target's contents.
echo file_get_contents('example_link.txt'), PHP_EOL;

// is_link() confirms the path is a symlink, readlink() reveals its target.
echo (is_link('example_link.txt') ? 'It is a link' : 'Not a link'), PHP_EOL;
echo 'Points to: ', readlink('example_link.txt'), PHP_EOL;

// Clean up: unlink() removes the link, not the target.
unlink('example_link.txt');
unlink('example.txt');

Output:

Hello from the target file
It is a link
Points to: example.txt

Reading example_link.txt returns the target's contents, is_link() detects that the path is a symlink, and readlink() returns the stored target path.

Example 2: Checking the Return Value

symlink() returns false (with a warning) if the link already exists or the directory is not writable, so always check the result in real code:

<?php
if (@symlink('target.txt', 'link.txt')) {
    echo 'Symbolic link created successfully.';
} else {
    echo 'Failed to create symbolic link.';
}

The @ suppresses the warning so you can handle the failure yourself. A robust routine removes a stale link first and verifies the outcome:

<?php
$target = 'config.php';
$link   = 'current-config.php';

if (is_link($link)) {
    unlink($link); // remove the old link before re-pointing it
}

if (symlink($target, $link)) {
    echo "Linked $link -> " . readlink($link);
} else {
    echo "Could not create link (check permissions).";
}

Relative vs. Absolute Targets

A relative $target is resolved against the directory containing the link, not against the current working directory. This is a common source of broken links:

<?php
// If the link lives in /var/www/app, this resolves to /var/www/shared/db.php
symlink('../shared/db.php', '/var/www/app/db.php');

// Absolute targets avoid the ambiguity entirely.
symlink('/var/www/shared/db.php', '/var/www/app/db.php');

Use an absolute path when the link might be created from a different working directory, or when you want it to keep working no matter where the link is read from.

Common Gotchas

• The link path must not already exist. Delete or update an existing link with unlink() first; otherwise symlink() fails.
• Windows requires elevated rights. Creating symlinks needs administrator privileges or Developer Mode enabled.
• Broken (dangling) links point to a missing target. is_link() still returns true, but file_exists() on the link returns false because it follows the link to the absent target.
• Permissions are checked on the link's parent directory, which must be writable.

Conclusion

The symlink() function provides a lightweight way to reference files and directories without copying data. Remember to verify its return value, prefer absolute targets when the working directory is uncertain, and account for platform-specific permission requirements. Pair it with is_link(), readlink(), and unlink() to inspect and manage links, and see the PHP Filesystem overview for the broader file API.

Practice