Jak dodawać własne moduły

Moduły są identyfikowane w systemie przez unikalną nazwę składającą się jedynie z liter i cyfr oraz ewentualnie znaków podkreślenie _ i dywiz -. Osobno można dać modułowi nazwę „przyjazną dla użytkownika”.

Moduły zapisywane są w osobnych plikach. Uruchamiane są:

• nazwa.php w głównym katalogu serwisu – jest to skrypt uruchamiany przez użytkowników serwisu
• nazwa.inc.php w katalogu /admin – panel do administrowania modułem, włączany do standardowego modułu admin/index.php

Dodatkowe pliki rozszerzające oba skrypty najlepiej nazywać nazwa*_.inc.php i umieszczać w katalogach odpowiednio /include albo /admin.

Jeżeli moduł korzysta z bazy danych, to najwygodniej założyć dla niego odpowiednie, osobne tabele. Zmienianie już istniejących tabel może uniemożliwić aktualizowanie systemu Enkidu CMS.

Aby nowy moduł był „widziany” przez system Enkidu CMS i mógł korzystać z wbudowanych w ten system funkcji, jego nazwa musi być dodana do tablic w pliku /include/modules.inc.php:

$module_names – przechowuje nazwy-identyfikatory modułów i nazwy przyjazne dla użytkownika,

$admin_modules – nazwy-identyfikatory administracyjnej części modułów,

$adminmoduleslevels – poziomy dostępu w panelu administracyjnym; aby administrator miał dostęp do edycji tego modułu, jego poziom administratora musi być co najmniej równy wartości wpisanej w tej tabeli.

W samym skrypcie należy oprócz tego zdefiniować zmienne globalne:

$module_name – nazwa-identyfikator modułu

$sel_title – „przyjazna” nazwa aktualnie wyświetlanej strony; wykorzystywana m.in. jako część tytułu okna przeglądarki; np. tytuł artykułu

$sel_description – „przyjazny” opis aktualnie wyświetlanej strony, wykorzystywany m.in. w opisie strony dla wyszukiwarek

$subject – jeżeli aktualnie wyświetlana strona należy do jakiegoś Tematu, to warto go określić w tej tablicy; jej najważniejsze pola to: id, title i access_level

$selshowcomments – określa, czy pokazywać komentarze na tej stronie. Standardowo -1 czyli skorzystaj z wartości domyślnej dla całego Tematu lub ogólnej dla całego serwisu. Inne wartości: 0 - nie pokazuj, 1 - pokaż normalnie, 2 - zachęcaj do dyskusji

Niedokładne „czyszczenie” parametrów przekazywanych przez użytkownika jest jedną z najczęściej wykorzystywanych przez włamywaczy luk w bezpieczeństwie serwisów internetowych. Dlatego Enkdiu CMS zawiera ułatwienia dla twórców modułów zwiększające poziom bezpieczeństwa.

System Enkidu CMS usuwa zarówno „registered globals”, jak i „magic quotes”, bez względu na parametry serwera. Zastępuje te nieskuteczne i niewygodne rozwiązania koncepcją „bezpiecznych parametrów” i funkcjami czyszczącymi parametry niestandardowe.

„Bezpieczne parametry”, to takie, które Enkidu CMS automatycznie wyciąga z zapytania użytkownika (tablicy $_REQUEST) w dołączanym skrypcie /include/security.inc.php. Starannie konwertuje je do zmiennych globalnych określonego typu, tak aby na pewno były wolne od niepożądanych elementów.

Te zmienne, to:

$sel – zawsze liczba całkowita. Zalecane zastosowanie: numer id elementu, którym zajmuje się aktualnie skrypt, „podmiot” strony

$do – zawsze ciąg wyłącznie liter alfabetu łacińskiego i cyfr oraz znaków - (dywiz), _ (podkreślnik) oraz . (kropka). Zalecane zastosowanie: akcja do wykonania przez skrypt, „orzeczenie” strony

$opt – zawsze ciąg wyłącznie liter alfabetu łacińskiego i cyfr oraz znaków - (dywiz), _ (podkreślnik) oraz . (kropka). Zalecane zastosowanie: przełącza funkcje skryptu, „przydawka” strony

$ref – zawsze liczba całkowita. Zalecane zastosowanie: dodatkowy numer id, „dopełnienie” strony

Przykłady:

/photo.php?sel=6&ref=12 – pokaż zdjęcie numer 6 z możliwością powrotu do artykułu 12

/admin/index.php?opt=teaser&do=pos&sel=5 – administruj pozycją zajawki numer 5

Dla poprawy bezpieczeństwa nowo tworzonych modułów zalecamy do korzystania ze standardowych funkcji czyszczących parametry zawartych w pliku /include/security.inc.php:

function ecms_sanitize($postkey, $opt=array(0,0))

Zwraca wartość parametru przekazanego przez użytkownika bezpieczną do wstawienia do bazy danych, prosto do wklejenia do zapytania SQL. Wartości tekstowe otaczane są apostrofami.

Jeżeli wartość parametru okaże się niewłaściwa, zwrócona zostanie wartość null.

$postkey to nazwa parametru przekazanego skryptowi metodą POST

$opt to tablica parametrów:

type (str, int albo email, domyślnie str) – typ parametru,

NULLok (true albo false, domnyślnie false) – w przypadku pustego parametru zwracaj ciąg czterech znaków NULL, a nie domyślną wartość php: null

HTMLok (true albo false, domyślnie false) &#8211; standardowo funkcja ecmssanitize zamienia specjalne znaki HTML na encje (< na &lt;, & na &amp; itd.), tak aby użytkownik otrzymywał to, czego oczekuje, a niekoniecznie to, co jest technicznie poprawne. Po ustawieniu HTMLok => true funkcja ecmssanitize zostawi znaki HTML tak, jak je wpisano, jedynie zabezpieczając parametr z punktu widzenia bazy MySQL. W efekcie użytkownik będzie mógł podawać kod HTML, a nawet umieszczać w nim potencjalnie niebezpieczne fragmenty javascript.

Funkcja ecmssanitize korzysta między innymi z funkcji mysqlrealescapestring, tak więc nie należy jej uruchamiać powtórnie.

function ecms_db2form($str)

Zamienia i zwraca tekst wyciągnięty z bazy danych na kod HTML do użycia jako wartość pól formularzy na stronie, tak aby efekt był przyjazny dla użytkownika.

Funkcja zakłada, że przekazany ciąg znaków zawiera zwykły tekst, a nie fragment HTML. Encje mające swoje odpowiedniki na typowej klawiaturze będą zastępowane odpowiednimi znakami, a pozostałe będą miały znak ** zastąpiony przez &amp;, dzięki czemu użytkownik będzie mógł edytować bardziej skomplikowane encje, takie jak &mdash;**

function ecms_db2formHTML($str)

Zamienia i zwraca tekst wyciągnięty z bazy danych na kod HTML do użycia jako wartość pól formularzy na stronie, tak aby umożliwić edycję tekstu jako fragmentu HTML.

De facto zamienia znak ** na encję &amp; Np. &lt; wyciągnięte z bazy danych zostanie zastąpione przez &amp;lt;, dzięki czemu użytkownik zobaczy na stronie napis &lt; a nie znak

…

Aby ograniczyć dostęp do modułu lub jego części, wygodnie jest skorzystać ze zmiennych globalnych oraz funkcji accessdeniedpage($level=1) wyświetlającej pełną stronę (wraz z nagłówkami HTML itp.) informującą o ograniczonym dostępie. Parametr $level określa poziom użytkownika, jaki byłby potrzebny do obejrzenia strony.

Jeżeli zdefiniowana jest tablica $subject, wystarczy wywołać funkcję allowaccessor_die(), która sama porówna uprawnienia użytkownika z ograniczeniami dostępu do danego tematu i w razie odmowy wyświetli stosowny komunikat i zakończy skrypt.

function admin_log ($sql, $opis=”)

Funkcja zapisze login aktualnie zalogowanego administratora, datę operacji oraz opisy zawarte w parametrach $sql i $opis do bazy danych. Skrócony wyciąg z tak powstających logów można oglądać w panelu administracyjnym.

Najlepiej logować wszystkie komendy SQL zmieniające bazę, przekazując je w parametrze $sql dokładnie tak, jak „poszły” do bazy danych.

Parametr $opis zawiera wyjaśnienie operacji przyjazne dla użytkownika, a dokładniej administratora przeglądającego zapisy operacji w panelu administracyjnym. Dlatego operacje z pustym $opisem nie będą widoczne w panelu administracyjnym, choć zostaną skrupulatnie zapisane w bazie.

Jeżeli jakaś operacja administratora powoduje wiele zmian w bazie danych, najlepiej logować wszystkie komendy SQL, ale zdefiniować opis tylko dla jednej z serii, aby nie zaśmiecać panelu administracyjnego.

W razie wątpliwości zaawansowany administrator może sprawdzić zawartość tabeli w bazie danych.