Programmer's guide for wifidog newbie

This guide is intended as an introduction for programmers who are new to the code. It gives a brief idea of how the code is structured, where some functionalities can be found and may help to get a head start in the code. It is not exhaustive. For that, there is the phpDoc. And it does not discuss the logic of the application. Many technical issues are discussed throughout the wiki.

Generalities

The wifidog auth server requires php 5. It is object oriented. Most classes use the singleton pattern, with static methods and attributes. There is no bootstrapping in the wifidog auth server, and every php script that can be called directly from the web browser contains the necessary logic and calls to classes to return what it is intented to return..

The classes

Attached to this page is a class diagram of wifidog as of revision [1420] and the link between classes (this is not exhaustive)

Classes representing objects that can be administered either implement the GenericObject interface or inherit from the GenericDataObject class.

Typically a class contains all the setters and getters for its properties. Each object (with unique id) is a singleton, so each different object is fetched only once from the database. The first time a specific object is requested through a static getObject($id) method, a row is fetched from the database and assigned to the object's attribute "row". Getters just return the right value from that row. Each setter updates the database and refreshes the row (from the database).

Also, a class contains the code to build the user interface (all the necessary html is there). These functions are called somethingUI() and are most often static (though not always).

The reason why the html code is embedded into the class is a matter of sharing contributions. It used to be different but... Templates and themes are considered purely "look and feel" that people build for their own needs but that are not necessarily shared with the community. And in some themes were made nice adjustements and additions that added flexibility to the interface. But those improvements would never be shared. In a project like wifidog with a small developer's community, we hoped to get more contributions by putting the html in the code itself. The "look and feel" of the page can be configured through css and what fields to show can mostly be done through configuration options. Or else you're welcome to program it! ;-)

Each class contains all the logic that involves it and the main php scripts merely call those functions.

Central classes in the system (those that a new developer should understand) are Network, Node and User. They are used in most if not all scripts. The MainUI class is necessary to understand the system as well. It is the main class that is used by every server script who returns an html page.

When permissions are required to perform certain operation or to access some data, those permissions are verified in the classes themselves. The main scripts don't have to bother verifying permissions and it allows programmers to change the permission logic right at the class level. When permissions are missing, a SecurityException is thrown and handled by the wifidog_exception_handler function found in the class MainUI (that must be included in all main scripts that display something) before aborting the execution. The default behavior is to show the login screen and invite the user to login with an account that has the required permissions.

Entry points of wifidog auth server

/admin/*.php except admin_common.php

scripts that allow administrative tasks on the server. Most notably generic_object_admin that is used to administer any object of a class that inherits from GenericDataObject or implement the GenericObject interface.

/auth/index.php

script used by the gateway to communicate with the auth server using the wifidog gateway protocol

/login/index.php

main login script

/ping/index.php

another gateway/server communication to indicate that the gateway is still up.

/portal/index.php

the portal page for a hotspot. This is where the user is redirected after authentication.

/profile/index.php

Displays a user profile

/clickthrough.php

simple redirector that tells the server a user has clicked on some content on the page and wants to be redirected there.

/geocoder.php

simple script that returns the geocoded coordinates of a point from a postal code in an xml string <geo></geo>

/gw_message.php

allows the server to display to the user a specific message from the gateway.

/hotspot_status.php

returns just the list of hotspots and their status in xml or html format

/node_list.php

returns the list of hotspots as a full html page with MainUI

The following are explicit enough:

/help.php
/hotspot_map.php
/index.php
/install.php
/lost_password.php
/lost_username.php
/resend_validation.php
/signup.php
/validate.php

Class diagram