WP Manifestindependent plugin directory
manifest / developer / mpress-debug-flags

Mpress Debug Flags

Pozwala włączać logowanie dla konkretnych flag/stałych zdefiniowanych w wp-config.php. Użyj mpress_debug_log('wiadomosc', 'NAZWA_FLAGI').

by Mateusz Zadorożny · github.com/mateusz-zadorozny/mpress-debug-flags · website

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/mateusz-zadorozny/mpress-debug-flags/archive/refs/heads/master.zip

Readme

Mpress Debug Flags

Wtyczka: Mpress Debug Flags
Wersja: 1.0.0
Autor: Mateusz Zadorożny
Strona autora: https://mpress.cc
Licencja: GPLv2 lub późniejsza

Opis

„Mpress Debug Flags” to lekka wtyczka dla WordPressa, która pozwala włączyć szczegółowe logowanie wybranych fragmentów kodu (funkcji, modułów lub klas) poprzez zdefiniowanie w pliku wp-config.php odpowiednich stałych (flag). Dzięki temu nie musisz włączać wszechobecnego WP_DEBUG – możesz precyzyjnie wskazać, co ma trafiać do pliku debug.log, a co ma pozostać ignorowane.

Przykład użycia flagi:

// W wp-config.php:
define('DEB_FUNKCJA_X', true);

// W kodzie wtyczki / motywu:
mpress_debug_log('Start funkcji X', 'DEB_FUNKCJA_X');

Jeśli stała DEB_FUNKCJA_X jest ustawiona na true, komunikat trafi do pliku wp-content/debug.log. W przeciwnym wypadku – np. po zakończeniu debugowania danego pluginu/modułu/funkcji – wtyczka nie będzie nic zapisywać.

Funkcje wtyczki

  • mpress_debug_log( $message, $debug_flag )
    • $message (mixed) – dowolny komunikat do zalogowania (string, array, object itp.).
    • $debug_flag (string) – nazwa stałej zdefiniowanej w wp-config.php. Jeśli stała istnieje i jest równa true, nastąpi zapis do pliku debug.log.
    • Jeżeli $message jest tablicą lub obiektem, zostanie przekonwertowane przy pomocy print_r(), w przeciwnym razie zostanie zapisany „goły” łańcuch.
    • Prefiks każdego wpisu w logu przyjmuje formę:
      [Debug][NAZWA_FLAGI] wiadomość lub zawartość tablicy/obiektu
    • Jeśli flaga nie istnieje lub ma wartość false, funkcja kończy działanie bez generowania logu.

Instalacja

  1. Pobierz wtyczkę

    • Utwórz folder wtyczki:

      wp-content/plugins/mpress-debug/

    • Wewnątrz tego folderu utwórz plik mpress-debug.php i wklej do niego kod wtyczki:

      <?php
/**
 * Plugin Name:       Mpress Debug Flags
 * Plugin URI:        https://mpress.cc
 * Description:       Pozwala włączać logowanie dla konkretnych flag/stałych zdefiniowanych w wp-config.php. Użyj mpress_debug_log('wiadomosc', 'NAZWA_FLAGI').
 * Version:           1.0.0
 * Author:            Mateusz Zadorożny
 * Author URI:        https://mpress.cc
 * License:           GPLv2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // Zapobiegamy bezpośredniemu dostępowi
}

/**
 * Zapisuje do logu (error_log) lub robi print_r, jeżeli stała-flagę ustawiono na true.
 *
 * @param mixed  $message    Dowolny komunikat lub zmienna (string/array/object).
 * @param string $debug_flag Nazwa stałej (bez $), np. 'DEB_FUNKCJA_KTORA_SPRAWDZAM'.
 */
if ( ! function_exists( 'mpress_debug_log' ) ) {
    function mpress_debug_log( $message, $debug_flag ) {
        // Upewniamy się, że debug_flag to string i jest niepuste
        if ( ! is_string( $debug_flag ) || empty( $debug_flag ) ) {
            return;
        }

        // Sprawdzamy, czy taka stała istnieje i czy jest true
        if ( defined( $debug_flag ) && constant( $debug_flag ) ) {
            // Budujemy prefiks logu z nazwą flagi
            $prefix = '[Debug][' . $debug_flag . '] ';

            if ( is_array( $message ) || is_object( $message ) ) {
                // Jeśli tablica lub obiekt, to print_r do error_log
                error_log( $prefix . print_r( $message, true ) );
            } else {
                // W przeciwnym wypadku zapisujemy string
                error_log( $prefix . $message );
            }
        }
        // Jeśli stała nie jest zdefiniowana lub jest false, nic nie robimy
    }
}

  2. Włącz wtyczkę w WordPressie

    • Zaloguj się do panelu administracyjnego WordPress.
    • Przejdź do „Wtyczki” → „Zainstalowane wtyczki”.
    • Znajdź „Mpress Debug Flags” i kliknij „Aktywuj”.

  3. Dodaj flagi w pliku wp-config.php
    Otwórz swój wp-config.php (nad linią /* That's all, stop editing! Happy blogging. */) i dodaj dowolne stałe, np.:

    // Włączanie debugowania dla poszczególnych funkcji/modułów:
define('DEB_FUNKCJA_KTORA_SPRAWDZAM', true);
define('DEB_API_INTEGRACJA', true);
// Jeśli nie chcesz, by dana flaga logowała, usuń linię lub ustaw false:
// define('DEB_EMAIL', false);

Użycie

  1. Logowanie prostego komunikatu 

    // W kodzie Twojego motywu lub innej wtyczki:
mpress_debug_log( 'Rozpoczęcie działania funkcji A', 'DEB_FUNKCJA_KTORA_SPRAWDZAM' );

  2. Logowanie tablicy lub obiektu 

    $wynik = array( 'status' => 'OK', 'kod' => 200 );
mpress_debug_log( $wynik, 'DEB_API_INTEGRACJA' );
    • Jeśli w wp-config.php zdefiniowałeś define('DEB_API_INTEGRACJA', true);, w wp-content/debug.log pojawi się:
      [Debug][DEB_API_INTEGRACJA] Array
(
    [status] => OK
    [kod] => 200
)

  3. Przykład warunkowego logowania
    Jeżeli wolisz, możesz najpierw sprawdzić w kodzie, czy stała istnieje i jest true, a potem dopiero wywołać mpress_debug_log:

    if ( defined('DEB_FUNKCJA_KTORA_SPRAWDZAM') && DEB_FUNKCJA_KTORA_SPRAWDZAM ) {
    mpress_debug_log( 'Dane do debugowania', 'DEB_FUNKCJA_KTORA_SPRAWDZAM' );
}

    Jednak sama funkcja mpress_debug_log już wewnątrz sprawdza wartość stałej, więc nadrzędna kontrola nie jest konieczna – to tylko dodatkowa warstwa bezpieczeństwa.

Gdzie trafiają logi?

  • Wpisy generowane przez mpress_debug_log w linii:
    error_log( $prefix . … );

    zostaną zapisane domyślnie w pliku:

    wp-content/debug.log
  • Aby debug.log w ogóle istniał i przyjmował wpisy, w pliku wp-config.php musisz mieć włączone:
    define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
  • Jeśli debug.log nie zostanie utworzony automatycznie, upewnij się, że katalog wp-content/ jest zapisywalny przez serwer (uprawnienia przynajmniej 755 lub 775 w zależności od konfiguracji).

Przykładowy scenariusz

  1. Chcesz prześledzić, co się dzieje w funkcji moja_funkcja_testowa():

    function moja_funkcja_testowa() {
    $dane = array( 'x' => 10, 'y' => 20 );
    mpress_debug_log( 'Rozpoczęcie moja_funkcja_testowa', 'DEB_TESTOWA' );
    mpress_debug_log( $dane, 'DEB_TESTOWA' );
    // … reszta kodu …
}

  2. W wp-config.php definiujesz:

    define('DEB_TESTOWA', true);
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

  3. Uruchamiasz moja_funkcja_testowa(), a w wp-content/debug.log pojawiają się wpisy:

    [Debug][DEB_TESTOWA] Rozpoczęcie moja_funkcja_testowa
[Debug][DEB_TESTOWA] Array
(
    [x] => 10
    [y] => 20
)

  4. Gdy już skończysz debugować, możesz w wp-config.php usunąć lub ustawić na false linię define('DEB_TESTOWA', true);. Wtedy mpress_debug_log przestanie generować wpisy.

FAQ

  1. Czy muszę mieć włączone WP_DEBUG, żeby mpress_debug_log działało?
    Tak, wtyczka używa error_log(), więc aby wpisy trafiały do pliku wp-content/debug.log, w wp-config.php musisz mieć:

    define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

    Bez tego pliku debug.log może w ogóle nie zostać utworzony.

  2. Co się stanie, gdy mpress_debug_log zostanie wywołane, ale flaga nie jest zdefiniowana?
    Funkcja mpress_debug_log najpierw sprawdza defined( $debug_flag ) i constant( $debug_flag ). Jeśli flaga nie istnieje lub ma wartość false, to funkcja kończy działanie bez żadnego wpisu ani błędu.

  3. Czy mogę używać wielu flag jednocześnie?
    Oczywiście – wystarczy w wp-config.php zadeklarować wiele stałych:

    define('DEB_MODUL_A', true);
define('DEB_MODUL_B', true);
define('DEB_MODUL_C', false);

    Następnie w kodzie stosujesz:

    mpress_debug_log('Coś z modułu A', 'DEB_MODUL_A');
mpress_debug_log('Coś z modułu B', 'DEB_MODUL_B');
mpress_debug_log('Coś z modułu C', 'DEB_MODUL_C'); // nic nie zapisze, bo false

  4. Gdzie sprawdzać wygenerowane logi?
    Zaloguj się przez FTP/SFTP lub do panelu hostingu i otwórz plik:

    /wp-content/debug.log

    Jeśli katalog nie jest zapisywalny, nadaj mu odpowiednie uprawnienia (np. 755 lub 775).

Wyłączanie lub usuwanie wtyczki

  • Aby czasowo wyłączyć logowanie dla konkretnej funkcji, usuń lub ustaw na false odpowiednią stałą w wp-config.php.
  • Aby całkowicie dezaktywować wtyczkę, w panelu WordPress przejdź do „Wtyczki” → „Zainstalowane wtyczki” → kliknij „Dezaktywuj” przy „Mpress Debug Flags”.
  • Jeśli jednak chcesz całkowicie usunąć kod wtyczki z serwera, możesz skasować folder:
    wp-content/plugins/mpress-debug/

Uwaga dotycząca bezpieczeństwa i stabilności

  • Przy standardowym działaniu wtyczka nie wprowadza żadnych nowych tabel w bazie danych ani nie modyfikuje rdzenia WordPressa.

  • Debugowanie odbywa się wyłącznie poprzez zapisy do pliku debug.log.

  • Jeżeli kiedykolwiek potrzebujesz, aby wtyczka istniała, ale nie była aktywna (np. w środowisku, gdzie nie chcesz, aby brak definicji flagi spowodował błąd), możesz w wp-config.php zdefiniować pustą wersję funkcji mpress_debug_log, tak by wywołania w kodzie nie generowały fatalnego błędu „nieznana funkcja”. Przykład:

    // Przed include/require pliku wtyczki (lub w dowolnym miejscu wp-config.php)
if ( ! function_exists( 'mpress_debug_log' ) ) {
    function mpress_debug_log( $message = '', $debug_flag = '' ) {
        // Pusta funkcja – nic nie robi
    }
}

    Dzięki temu nawet jeśli plugin jest usunięty lub wyłączony, wywołania mpress_debug_log( … ) w kodzie nie przerwą działania WordPressa.

Licencja

Mpress Debug Flags jest udostępniona na licencji GPLv2 (lub późniejszej). Pełny tekst licencji znajdziesz w pliku LICENSE lub pod adresem:
https://www.gnu.org/licenses/gpl-2.0.html

Read the full README on GitHub →