PHP symlink Function
last modified April 3, 2025
The PHP symlink function creates symbolic links between files. It's
useful for creating file system references without duplicating content.
Basic Definition
The symlink function creates a symbolic link from the target to the
link name. It takes two parameters: the target path and the link name.
Syntax: symlink(string $target, string $link): bool. The function
returns true on success and false on failure. Requires appropriate permissions.
Basic symlink Example
This shows the simplest usage of symlink to create a link.
<?php
declare(strict_types=1);
$target = "/var/www/html/original.txt";
$link = "/var/www/html/link.txt";
if (symlink($target, $link)) {
echo "Symbolic link created successfully";
} else {
echo "Failed to create symbolic link";
}
This creates a symbolic link named "link.txt" pointing to "original.txt". The function returns true if successful. Note that the target must exist.
Relative Path symlink
The function can create links using relative paths for both target and link.
<?php
declare(strict_types=1);
$target = "../files/document.pdf";
$link = "downloads/doc.pdf";
if (symlink($target, $link)) {
echo "Relative symbolic link created";
} else {
echo "Failed to create relative link";
}
Here we create a link using relative paths. The link will point to the document one directory up in the files hierarchy. Relative links maintain their relationship when moved.
Directory symlink
symlink can create links to directories as well as files.
<?php
declare(strict_types=1);
$targetDir = "/var/www/projects/current";
$linkDir = "/var/www/html/project";
if (symlink($targetDir, $linkDir)) {
echo "Directory link created successfully";
} else {
echo "Failed to create directory link";
}
This creates a symbolic link to an entire directory. The link will behave like the original directory for most operations. Directory links are commonly used in web development.
Checking Before Creating
It's good practice to check if a link or file exists before creating.
<?php
declare(strict_types=1);
$target = "config.ini";
$link = "settings.ini";
if (file_exists($link)) {
echo "Link name already exists";
} elseif (!file_exists($target)) {
echo "Target file does not exist";
} elseif (symlink($target, $link)) {
echo "Symbolic link created safely";
} else {
echo "Failed to create symbolic link";
}
This example demonstrates safe link creation by checking preconditions. First we verify the target exists, then check the link name isn't taken. This prevents errors and overwrites.
Windows symlink Example
On Windows, symlink creation requires appropriate privileges.
<?php
declare(strict_types=1);
$target = "C:\\Users\\Public\\Documents\\report.docx";
$link = "C:\\Users\\Public\\Desktop\\current_report.docx";
if (symlink($target, $link)) {
echo "Windows symbolic link created";
} else {
echo "Failed to create Windows link";
}
Windows symlinks require administrator privileges or developer mode enabled. The syntax uses backslashes but forward slashes also work. Windows distinguishes file and directory links.
Edge Cases
symlink has specific behaviors with certain edge cases.
<?php
declare(strict_types=1);
// Attempt to create link to non-existent target
$result1 = symlink("nonexistent.txt", "badlink.txt");
// Attempt to create link where name exists
file_put_contents("existing.txt", "content");
$result2 = symlink("target.txt", "existing.txt");
var_dump($result1); // bool(false)
var_dump($result2); // bool(false)
Creating links to non-existent targets fails. Trying to create a link where the name already exists also fails. The function is strict about these conditions and returns false.
Best Practices
- Error Handling: Always check the return value.
- Permissions: Ensure proper filesystem permissions.
- Security: Validate paths to prevent symlink attacks.
- Cross-platform: Be aware of OS differences.
- Cleanup: Use unlink() to remove symbolic links.
Source
This tutorial covered the PHP symlink function with practical
examples showing its usage in different scenarios.