Полный ответ:

1. Основное назначение и синтаксис

realpath() — это функция, которая преобразует любой переданный путь (относительный, абсолютный, с символами ., .. или избыточными разделителями) в канонизированный абсолютный путь.

realpath(string $path): string|false

• Принимает строку с путем.
• Возвращает абсолютный нормализованный путь или false, если путь не существует.

2. Что именно делает realpath()? (Канонизация)

Функция выполняет несколько важных преобразований:

1. Разрешает относительные пути в абсолютные (относительно текущей рабочей директории).
2. Разрешает символы . (текущая директория) и .. (родительская директория).
3. Убирает избыточные разделители (//, \/ и т.д.).
4. Следует по симлинкам (symbolic links) и возвращает путь реального файла/директории.
5. Проверяет существование конечного пути в файловой системе.

3. Примеры работы

Предположим, структура файлов такая:

/var/www
├── project/
│   ├── index.php
│   └── config/
│       └── app.php
└── -> project/ (симлинк)

// Файл: /var/www/project/index.php
echo getcwd(); // Допустим, /var/www/project

echo realpath('../project/index.php');          
// /var/www/project/index.php (относительный → абсолютный)

echo realpath('./config/../index.php');      
// /var/www/project/index.php (убрал избыточность)

echo realpath('/var/www//project/./config/../index.php'); 
// /var/www/project/index.php (нормализовал путь)

echo realpath('/var/symlink-to-project/index.php'); 
// /var/www/project/index.php (разрешил симлинк)

echo realpath('non-existent-file.txt');      
// false (файл не существует)

4. Ключевые особенности

1. Проверка существования: Если любой компонент пути не существует, функция вернет false. Это одновременно и преимущество, и ограничение.

2. Работа с симлинками: realpath() всегда возвращает путь реального файла, на который указывает симлинк. Это ключевое отличие от __FILE__, который может возвращать путь симлинка.

3. Безопасность: Функция полезна для проверки, не выходит ли вычисленный путь за пределы разрешенной директории.

   $userPath = $_GET['file']; // '../etc/passwd'
   $fullPath = realpath('/base/dir/' . $userPath);
       
   // Проверяем, что путь остался внутри базовой директории
   if ($fullPath && strpos($fullPath, '/base/dir/') === 0) {
       // Безопасно использовать файл
   }
   

5. Отличие от похожих функций

6. Практическое применение

1. Нормализация путей для сравнения:

   $path1 = '/var/www//project/./file.php';
   $path2 = '/var/www/project/../project/file.php';
       
   if (realpath($path1) === realpath($path2)) {
       echo 'Это один и тот же файл';
   }
   

2. Безопасная работа с пользовательским вводом:

   $userFile = $_POST['file'];
   $baseDir = '/allowed/directory';
   $absolutePath = realpath($baseDir . '/' . $userFile);
       
   // Проверяем, что путь существует и находится внутри базовой директории
   if ($absolutePath === false || strpos($absolutePath, $baseDir) !== 0) {
       throw new Exception('Доступ запрещен');
   }
   

3. Получение реального пути при использовании симлинков:

   // Если скрипт запущен через симлинк
   $actualPath = realpath($_SERVER['SCRIPT_FILENAME']);
   

7. Ограничения и предостережения

• Производительность: Функция обращается к файловой системе, поэтому частые вызовы могут замедлить работу.
• Кеширование: Результаты могут кешироваться на уровне ОС, но не PHP.
• Сетевые пути: Может работать с сетевыми дисками, но зависит от ОС и настроек.

Итог:

realpath() — это мощная функция для нормализации и верификации путей. Она преобразует любой путь в абсолютный, убирая избыточность, разрешая относительные переходы (..) и симлинки, и проверяя существование конечного файла/директории. Критически важна для безопасности при работе с динамически формируемыми путями.