An introduction to m2f 2.0 code

I thought it would be a good idea for our budding developers if I put together an introductory tour of the code in m2f 2.0. It will make things easier for you in the early stages, and act as a point of reference which we can all refer to in the future.

Installation

M2f requires a PHP version of 5.2 or greater, with PDO extension enabled (with at least the Sqlite driver).

We use a Sourceforge SVN repository for all the code. As the code is written using Unit Tests, commits to the repository are only allowed when all the tests pass. This means that a checkout from the repository will generally result in a stable snapshot at any moment in time.

Instructions for accessing the repository can be found on the Sourceforge Site. The repository root has a number of directories, each with code from a different vendor. These are the 3rd-party libraries I am currently using in m2f. The m2f code itself can be found in /m2f/trunk. 

To install, run a SVN checkout:

svn co https://m2f.svn.sourceforge.net/svnroot/m2f/m2f/trunk m2f

This will download not only the m2f code, but all the required 3rd-party libraries, which will be added automatically into the /includes directory (using the magic of svn:externals).

You should copy the whole directory to your webserver. Before you can start to play with m2f, you need to do a few bits of administration. Firstly, enable write access for the webserver to the following directories:
/cache
/config
/models
/tests/files
Secondly, you need to copy /tests/config.php.dist to /tests/config.php, and edit the file for your setup. This is configuration for the Test Suite only. You need to edit fields for the URL to your test server (can be localhost), the database connection details for testing (I would strongly recommend an sqlite database located in the /tests/files directory, which already has write permissions - it will be created automatically), and the details for your test installations of phpBB2 and phpBB3, which should be on the same server.

To communicate with phpBB2, the following files need to be copied from the m2f directory to the phpBB2 root:
[m2f]/external/Phpbb2/m2f.php => [phpBB2]/m2f.php
[m2f]/external/Phpbb2/m2f/InsertPost.php => [phpBB2]/m2f/InsertPost.php
[m2f]/lib/M2f/Receiver.php => [phpBB2]/m2f/Receiver.php

Run Tests

You may visit either /tests or /test-suite in your browser to run the m2f tests - they are identical in function but slightly different in aesthetic. In simple terms, there is no point proceeding with your m2f work until ALL the test pass! Any errors should be reported to georgec on the mailing list.

Directory structure

The following list refers to the root of a standard m2f download:

/application

the web User Interface for the administration control panel

/cache

um… the cache

/config

contains the configuration file for the Admin CP (N.B. this is different to the config file for running the tests)

/di

configuration files for Dependency Injection

/external

files not needed by m2f, but required by 3rd-party software such as phpBB2. These files need to be moved into the 3rd-party directories in order for m2f to communicate back and forth.

/includes

3rd-party library files used by m2f

/lib

the core m2f code

/models

database models, used by Doctrine ORM system

/test-suite

JavaScript-enabled test runner

/tests

contains all the tests, plus a more simple test runner

m2f Library Files

Let’s have a look at the contents of the /lib directory. We use ZEND-style naming conventions for all m2f library classes, so the class names directly map to files in the /lib directory:
M2f => /lib/M2f.php
M2f_Message => /lib/M2f/Message.php
M2f_Module_Channel_Phpbb2_Export => /lib/M2f/Module/Channel/Phpbb2/Export.php

I will now talk through the major areas of the m2f library, using class names as reference.

M2f

static helper function, such as autoload()

M2f_Cache

interface to Zend Framework’s Cache system. Stores cache files in /cache

M2f_Chain

the ‘guts’ of m2f. Like a Distribution List in v1.2. Add import and export channels to a chain, and everything happens when the chain is run.

M2f_Db

interface to Doctrine ORM system. Sets up a PDO object, passes it to Doctrine. Also responsible for installing the m2f tables

M2f_Di

interface to Crafty Dependency Injection system

M2f_Element

base class for objects which may be added to a chain (Channel, Filter, etc.)

M2f_Element_Config

configuration object for each instance of M2f_Element

M2f_Facade

not currently used

M2f_Filter_Parser_Tokenizer

splits message text strings into tokens based on rules (such as BBCode)

M2f_Filter_Parser_Assembler

assemble tokenized string into M2f_Message style XML

M2f_Message

basic message class, passed between elements in a chain

M2f_Message_List

Container for instances of M2f_Message. Each Chain, Channel and Filter is passed a Message List

M2f_Model

base class for Doctrine Models (each model corresponds to a database table)

M2f_Persistable

base class for objects which need to be saved in the database

M2f_Receiver

receives and decodes cURL connections from 3rd-party software, such as phpBB

M2f_TransferObject

basic objects which hold an array of data

M2f_Transport

initiates cURL connections with 3rd-party software, such as phpBB

The directory I have missed out is the big one! Inside /modules you will find all the Channels, Filters (and more later!) which give m2f its functionality.