Legyen saját Drupal API oldalad!

Az új Drupal stabil kiadásához közeledve hasznos lehet, ha az ember újragondolja, átnézi a fejlesztéseit, hiszen a legtöbb esetben mindenképpen módosítani kell az általa kifejlesztett, egyedi funkcionalítást adó modulon, hogy használható legyen a Drupal 6 alatt is. Ilyenkor nagy segítséget jelent az api.drupal.org, ahol könnyen lehet keresni a használható függvények között, megnézni a paraméterezését, vagy a működését.
Viszont nem mindenkinek áll a rendelkezésére az Internet, mint ahogy jómagam is ebben a helyzetben voltam évekig, így szeretném bemutatni az ilyenkor használható hűséges segítőtársamat: az API modult, amelyet teljesen offline működésre fogunk bírni.

A megoldást Linux operációs rendszer alatt teszteltem, és ott is használom, így azokról az esetleges eltérésekről, amelyek a Microsoft Windows alatt jelentkezhetnek (pl. a fájlrendszer elérése), nem tudok nyilatkozni.
Amire szükségünk lesz:

  • Egy feltelepített Drupal rendszerre, mivel erről a kézikönyv is hosszasan ír, ezért inkább itt nem taglalnám
  • Az API modulra, ugyan a modul nem rendelkezik még magyar fordítással, de enélkül is könnyen érthető a felülete
  • Kell még a PHP függvények rövid leírása, amelyet itt fogunk megtalálni, mentsük le funcsummary.txt néven (a download linkre kell kattintani)
  • A minél teljesebb dokumentációhoz szükséges még néhány dokumentáció (pl. Form API), és egyéb példakódok, ezeket a következő paranccsal tudjuk kinyerni a Drupal tárolóból:
    cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-5 contributions/docs/developer
  • Végül pedig szükséges még a PHP dokumentáció, itt fontos, hogy a több fájlból álló változatot válasszuk, amely innen tölthető le magyar nyelven.

Ha ezek megvannak, akkor minden szükséges dolgot letöltöttünk, vigyük haza, és lássunk munkához!

Először is, a webszerver által használt gyökérkönyvtárban hozzunk létre egy alkönyvtárat phpdoc néven, és oda tömörítsük ki a PHP dokumentációt, majd ebben a könyvtárban hozzunk létre egy fájlt .htaccess névvel, amelynek a tartalma legyen a következő:

<IfModule mod_rewrite.c>
    RewriteEngine on
 
    RewriteBase /phpdoc/html
 
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} ^(.*)_(.*)$
    RewriteRule ^(.*)_(.*)$ $1-$2
 
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^([0-9A-Za-z\-]*)$ function.$1.html [L]
</IfModule>

Ezzel elértük azt, hogy a http://localhost/phpdoc/html/is_array címen megjelenik az is_array PHP függvény leírása, ez amúgy többféle módon is megoldható, érdemes elolvasni a Weblabor kapcsolódó cikkét. Szintén ebbe a phpdoc könyvtárba másoljuk be a korábban lementett funcsummary.txt állományt.

Az api modul bekapcsolása után az adminisztrációs oldal "webhely beállítása" részében megjelent egy új menüpont "API reference" néven, itt tudjuk a modul működését szabályozni.
Az első megadandó dolog a "Short name", ezt majd a címek generálásakor használja a Drupal, így nem tartalmazhat szóközt, vagy olyan karaktert, amely nem megengedett az internet-címekben.
A következő a "Long name", ez lesz a blokk látható neve, fontos szerepe van akkor, ha egyszerre több Drupal dokumentációját, mondjuk a stabil és a fejlesztői változatét kívánjuk elkészíteni.
A "Directory name" helyen kell megadnunk az indexelni kívánt Drupal abszolút elérési útvonalát, akár egyszerre többet is, kettősponttal elválasztva.
A "Maximun files to scan per cron run" helyen állíthatjuk be, hogy az időzített feladatok futása közben egy-egy alkalommal hány fájlt dolgozzon fel. Ezt érdemes az alapértelmezett 10 értéken hagyni, így nem futnak ki folyamatok az engedélyezett időből.
A "Save changes" gombra kattintva elmenthetjük az itt megadott adatokat, így lehetőség nyílik másik telepítés leindexelésére is, majd ha többet is beállítottunk, a "Default branch" rádiógomb alatt lehetséges az alapértelmezettet kiválasztani. Fontos, hogy miután megjelent a "Changes saved." felirat, akkor mégegyszer nyomjuk meg ezt a gombot, mert ekkor menti el a "Default branch" tartalmát, ennek hiánya esetlegesen galibát okozhat.

A "PHP Manual" résznél az első helyre írjuk be a funcsummary.txt elérési helyét: http://localhost/phpdoc/html/funcsummary.txt
A második résznél pedig megadhatjuk PHP dokumentáció helyét a gépünkön, a "!function" karaktersorozattal kiegészítve (ide kerül majd a függvény neve), tehát:
http://localhost/phpdoc/html/!function

Majd ha ezek megvannak, kattintás az "Index PHP manual pages" gombra, és egy kis várakozás. Ha végzett, és mindent helyesen állítottunk be, akkor a "Reindex" gombra kattintva megkezdődik a megadott Drupal rendszerek forrásának feldolgozása.
Most nincs más dolgunk, mint szorgosan futtatni az időzített feladatokat, akár böngészőből:
http://localhost/ahol_van_az_oldalunk/cron.php,

akár konzolból a
wget -O - -q http://localhost/ahol_van_az_oldalunk/cron.php

parancsot futtatva.
Annyiszor kell ezt végrehajtani, amíg a hozzáférési naplóban az api modulhoz tartozóan a "Parsing" kezdetű üzenetek el nem fogynak.
Ezek után már csak egy lépés választ el minket a sikertől:
Az adminisztrációs oldal "Blokkok" részében kapcsoljuk be az "API navigation" és az "API search" blokkokat, majd a főoldalra lépve legyünk boldogok, és válljék egészségünkre a gépünkön üzemelő Drupal API dokumentációs rendszer.

Frissítve (2010.06.08):
Drupal 6 hoz a következő CVS paranccsal lehet kinyerni a dokumentációt:
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 contributions/docs/developer