🛠 2 Sposoby uzyskania ścieżki głównej WordPress

Dodają Państwo plik w functions.php i WordPress nie może go znaleźć. Znajoma sytuacja? Przyczyna prawie zawsze leży w nieprawidłowej ścieżce do folderu głównego.

Wpisana ręcznie /var/www/html/ psuje się przy przenosinach na inny serwer. A sztywno zakodowana ../../wp-content/plugins/ przestaje działać przy zmianie struktury katalogów. Na szczęście WordPress udostępnia dwa standardowe sposoby na poznanie ścieżki absolutnej do katalogu głównego witryny, bez żadnych domysłów. Oba domyślnie zwracają ścieżkę z końcowym ukośnikiem, więc konkatenacja podścieżek nie wymaga dodatkowego /.

Po przeczytaniu tego wpisu będą Państwo dokładnie wiedzieć, kiedy użyć get_home_path(), a kiedy ABSPATH, i dlaczego w jednych projektach są one tożsame, a w innych zwracają różne katalogi. Jako bonus omówimy typowy błąd z podwójnym ukośnikiem oraz scenariusz dla zewnętrznych skryptów cron.

💡 Szybki przegląd:

• Proszę otworzyć functions.php motywu i załączyć wp-admin/includes/file.php, a następnie wywołać get_home_path(), aby uzyskać ścieżkę absolutną z końcowym ukośnikiem
• Proszę używać stałej ABSPATH z wp-config.php, jest dostępna globalnie, nie wymaga ręcznego załączania i działa nawet na froncie
• Przy niestandardowej strukturze katalogów (Bedrock, wydzielony rdzeń) proszę porównać wyniki obu metod na serwerze testowym, mogą one wskazywać na różne foldery
• Dla wtyczek i motywów dystrybuowanych przez katalog WordPress.org proszę stosować ABSPATH, to standard, który gwarantuje działanie na każdym hostingu

1. Get_home_path(): ścieżka przez API panelu admina

Funkcja get_home_path() jest opisana w oficjalnej dokumentacji WordPressa i zwraca absolutną ścieżkę systemową do katalogu głównego instalacji, tego, w którym znajdują się wp-admin, wp-includes i wp-content. W przeciwieństwie do ręcznego wpisywania nie zależy od hostingu i nie psuje się przy przenosinach.

Główna zaleta: nie muszą Państwo zgadywać, czy witryna jest zainstalowana w katalogu głównym domeny, czy w podkatalogu. Funkcja sama to ustali i zwróci na przykład /var/www/html/ dla standardowej instalacji lub /home/user/site.com/wordpress/ dla witryny w podfolderze. Żadnych ../../ i ręcznej edycji konfigów.

Plik z funkcją znajduje się w wp-admin/includes/file.php, dlatego bezpośrednio w motywie lub na froncie get_home_path() nie jest dostępna. Aby użyć jej poza panelem admina, należy najpierw ręcznie załączyć plik. Kod dodaje się w functions.php motywu potomnego lub przez wtyczkę Code Snippets:

1
// Підключаємо файл з функцією — без неї get_home_path() викличе фатальну помилку
2
require_once ABSPATH . 'wp-admin/includes/file.php';
3
 
4
// Отримуємо абсолютний шлях до кореня WordPress
5
$root = get_home_path();
6
 
7
// Приклад: підключаємо файл update.php з wp-admin
8
require_once $root . 'wp-admin/update.php';

Tutaj require_once ze ścieżką przez ABSPATH ładuje plik administracyjny tylko raz, ponowne załączenie nie spowoduje konfliktu. Po tym get_home_path() jest dostępna w dowolnym miejscu motywu.

Proszę zwrócić uwagę: końcowy ukośnik jest już zawarty w zwracanym ciągu. Proszę konkatenować podścieżki bez dodatkowego / na początku: $root . 'wp-admin/update.php', a nie $root . '/wp-admin/update.php'. Podwójny ukośnik PHP po cichu przełknie na większości systemów plików, ale niektóre restrykcyjne sprawdzenia file_exists() mogą się na nim potknąć.

2. ABSPATH: stała prosto z wp-config.php

ABSPATH to stała, którą WordPress definiuje w wp-config.php podczas ładowania. W standardowym pliku wygląda ona tak:

1
if (!defined('ABSPATH')) {
2
    define('ABSPATH', __DIR__ . '/');
3
}

__DIR__ zwraca katalog, w którym leży sam wp-config.php, a jest to właśnie katalog główny WordPressa. Stała jest dostępna globalnie: w motywie, wtyczkach, na froncie, w panelu admina, w WP-CLI. Żadnych require_once do załadowania, jest już w pamięci od momentu uruchomienia rdzenia.

Użycie jest trywialne, proszę wstawić ABSPATH wszędzie tam, gdzie potrzebna jest ścieżka absolutna:

1
// Зберігаємо шлях у змінну для читаності
2
$rootPath = ABSPATH;
3
 
4
// Підключаємо файл з wp-admin
5
require_once ABSPATH . 'wp-admin/update.php';
6
 
7
// Або завантажуємо користувацький файл з кореня
8
include_once ABSPATH . 'custom-cron.php';

Końcowy ukośnik również tutaj występuje, zachowanie jest identyczne jak w get_home_path(). Wzorzec require_once ABSPATH . 'wp-admin/update.php' zadziała na każdym hostingu, w dowolnej strukturze katalogów, bez żadnej edycji ścieżki. Właśnie dlatego większość wtyczek z katalogu WordPress.org używa ABSPATH, a nie get_home_path(): stała nie wymaga ręcznego załączania pliku i nie zależy od kontekstu wywołania.

Kiedy get_home_path() i ABSPATH zwracają różne katalogi

W standardowej instalacji WordPressa obie konstrukcje zwracają ten sam ciąg. Istnieją jednak dwa scenariusze, w których się rozchodzą, i jeśli Państwo o nich nie wiedzą, błąd może przeżyć w kodzie miesiącami.

Rdzeń poza katalogiem głównym dokumentów. Niektóre hostingi (Kinsta, WP Engine) i niestandardowe konfiguracje umieszczają pliki rdzenia w osobnym katalogu, a wp-config.php, poziom wyżej. W tym przypadku ABSPATH wskazuje na folder z wp-config.php, a get_home_path(), na podkatalog z rdzeniem. Na WordPress StackExchange deweloperzy podają rzeczywisty przykład: ABSPATH = /www/site/, a get_home_path() = /www/site/wp/. Różnica jednego katalogu i require_once kończy się błędem krytycznym.

Bedrock i inne niestandardowe struktury. W Bedrock od Roots katalog główny witryny (web/wp/) jest oddzielony od katalogu głównego projektu, gdzie leżą config/, vendor/ i web/. ABSPATH w Bedrock wskazuje na web/wp/, podczas gdy get_home_path() kieruje się ustawieniami multisite i domowym URL-em. W praktyce get_home_path() w Bedrock może zwrócić ścieżkę do web/wp/, która jest tożsama z ABSPATH, ale nie należy na tym polegać, proszę to sprawdzić na konkretnym projekcie.

Praktyczny wniosek: jeśli piszą Państwo wtyczkę do publikacji w katalogu WordPress.org, proszę używać ABSPATH, jest dostępna wszędzie bez dodatkowych załączeń. Jeśli piszą Państwo kod dla konkretnej witryny o niestandardowej strukturze, proszę sprawdzić obie stałe na środowisku testowym i wybrać tę, która wskazuje tam, gdzie Państwo potrzebują. Pięć minut porównania na serwerze testowym zaoszczędzi godziny debugowania na produkcji.

Jest jeszcze jeden niuans związany z motywem: jeśli Państwa motyw jest dystrybuowany na Themeforest lub w katalogu WordPress.org, proszę zawsze używać ABSPATH, jest ona gwarantowanie zdefiniowana na każdym hostingu klienta. get_home_path() może nie zadziałać, jeśli motyw wywoła ją przed załadowaniem panelu admina.

Krótkie wideo powyżej obrazowo pokazuje, jak ABSPATH chroni wtyczki przed bezpośrednim uruchomieniem i dlaczego wzorzec defined('ABSPATH') or die jest standardem bezpieczeństwa dla każdego pliku PHP w ekosystemie WordPressa.

⁉️🤔 Często zadawane pytania

Co jest szybsze: get_home_path() czy ABSPATH?

ABSPATH to stała: jej wartość jest definiowana raz podczas ładowania WordPressa i przechowywana w pamięci. get_home_path() to funkcja, która przy pierwszym wywołaniu parsuje domowy URL i oblicza ścieżkę względem systemu plików. Różnica w szybkości jest pomijalnie mała (mikrosekundy na wywołanie), ale jeśli ścieżka jest pobierana dziesiątki razy w ramach jednego żądania HTTP, proszę zapisać ABSPATH w zmiennej na początku skryptu i jej używać.

Czy trzeba ręcznie załączać ABSPATH w swoich plikach?

Jeśli Państwa kod wykonuje się w kontekście WordPressa (motyw, wtyczka, handler AJAX), ABSPATH jest już zdefiniowana, nie trzeba niczego załączać. Sprawdzenie if (!defined('ABSPATH')) { exit; } na początku dowolnego pliku PHP w katalogu głównym witryny to dobra praktyka bezpieczeństwa: blokuje bezpośrednie uruchomienie skryptu z pominięciem WordPressa i chroni przed wyciekiem danych przez bezpośrednie żądanie HTTP do pliku.

Czy można używać ABSPATH w zewnętrznym skrypcie cron?

Można, ale z ostrożnością. Jeśli skrypt leży poza instalacją WordPressa, proszę załadować wp-load.php: require_once '/path/to/wp-load.php';. Po tym ABSPATH stanie się dostępna. Proszę wziąć pod uwagę: bezpośrednie wywołanie wp-load.php ładuje cały rdzeń i wszystkie aktywne wtyczki, dla częstych zadań cron jest to nadmiarowe. Dla projektów o dużym obciążeniu lepiej wydzielić logikę do komendy WP-CLI.

Czy get_home_path() zwraca ścieżkę z podwójnym ukośnikiem?

Nie. Funkcja gwarantowanie zwraca jeden końcowy ukośnik. Podwójny ukośnik może się pojawić tylko wtedy, gdy sami Państwo dodadzą / na początku podścieżki: get_home_path() . '/wp-admin/'. Prawidłowo jest bez początkowego ukośnika: get_home_path() . 'wp-admin/'. Na większości systemów Linux podwójny ukośnik jest równoważny pojedynczemu, ale nie należy na tym polegać, sprawdzenia file_exists() w niektórych konfiguracjach mogą zwrócić false.

Czym ścieżka główna różni się od home URL?

Ścieżka główna (/var/www/html/) to system plików serwera. Home URL (https://site.com) to adres widziany przez przeglądarkę. Do pobrania URL-a proszę używać home_url(), a do ścieżki systemowej, get_home_path() lub ABSPATH. Proszę nie mylić: require_once oczekuje ścieżki systemowej, wp_remote_get() oczekuje URL-a. Pomylenie skutkuje albo false z file_exists(), albo nieprawidłowym żądaniem HTTP do lokalnej ścieżki.

Co stosować w Państwa projekcie: podsumowanie

Do zdecydowanej większości zadań wystarczy ABSPATH. Stała jest dostępna natychmiast po załadowaniu WordPressa, nie wymaga ręcznego załączania plików i działa tak samo na każdym hostingu. Jeśli piszą Państwo wtyczkę lub motyw do dystrybucji, tylko ABSPATH, bez wyjątków.

Jeśli administrują Państwo witryną o niestandardowej strukturze katalogów (wydzielony rdzeń, Bedrock, multisite z różnymi domowymi URL-ami), proszę poświęcić pięć minut i porównać wyniki get_home_path() i ABSPATH na środowisku testowym. Rozbieżność o jeden katalog może kosztować godziny debugowania na produkcji.

A którą metodę Państwo stosują, get_home_path() czy ABSPATH? Proszę napisać w komentarzach: czytamy każdy.