Array
(
    [responseMsg] => Array
        (
            [status] => ok
            [message] => Service call was successful
        )
    [allColors] => Array
        (
            [0] => blue
            [1] => green
            [2] => black
            [3] => white
            [4] => yellow
            [5] => red
            [6] => beige
        )
)

Now that we have the basic idea, we need to create the WSDL file. Remember, it is very important to think of WSDL files as of reading from bottom to top. The final WSDl file is located here. Here is the basic idea of the WSDL file I created (going from the bottom to the top):

1. Service: This houses the binding, the location, the port, and the name.
2. Binding: This houses the functions that will be exposed, the operation and the input and output encoding. Most of the time these will be similar with only the names being different.
3. Port Type: Here is where I define the operations and the input/output definitions
4. Message: These are individual nodes for the Request and Response messages for all functions. These will usually have two message nodes per function, and they will define the structure for each action
5. Types: This defines each structure that has been mentioned in the Message and any subsequent structures that have to be defined. This is usually the area where most struggles occur.
   • This structure will be encompassed by schema target namespace
   • Import the XML namespaces to help build the structures in the reasponse
   • For each complex type, it should either mention a specific data type (xsd:), or a new defined structure (tns:)
   • Each structure that is an array should be defined as a SOAP-ENC:Array with a wsdl:arrayType parameter

So that is the WSDL. The one I have created defines the 2 functions, the input, the output, and the structure of each. Now we can move on to the Server code.

Using PHP SOAP can be as easy as you make it or as hard as you make it. First off, we need to define the functions in the file. I called my server file, server.php. I want to set the cache to null, and then define those functions.

<?php
ini_set('soap.wsdl_cache_enabled', false);

function getColors($which = null){
. . .
}

function getNames($set = null){
. . .
}

The next part it to get the server going. Hopefully, before doing this you have read the PHP manual online and read the parts about the SOAP server, and you will find this to be fairly easy. First we need to instantiate the new Server class, and pass to it the URL for the WSDL as a parameter. This is what I am doing for this example, but there are other ways and parameters that one could use. Next, we need to add the functions to the class, so that we can expose those out to the clients. Finally, we need to call the function to handle the calls from the client. Although this may sound a bit much, here is the code to get it done, with this example:

// Set up the PHP SOAP server
$server = new SoapServer("http://www.hirdweb.com/soap/hirdweb.wsdl");
// Add the exposable functions
$server->addFunction("getColors");
$server->addFunction("getNames");
// Handle the request
$server->handle();

And just like that, you have the server set up. What I am not showing here is the code for the functions. These are basic, and at the end of this post, will be the link to the code files. Basically each function takes the static array, and returns the data to the client. There is one extra function that I put in that build the Response header array. The getNames function just does a SWITCH statement to check to see which part of the static array to return.

Now to the client. Again, another easy implementation. First, we are not going to cache the WSDL. We are going to set up the client and point to the WSDL, setting trace to true in case we need the last response and request for debugging. I am also going to show which functions are available, so I will print that out. Next we need to call the functions, and set parameters if needed. So the code for this is again fairly easy.

// Set to disable caching of the wsdl file
ini_set('soap.wsdl_cache_enabled', false);

// Create the SOAP client
$client = new SoapClient("hirdweb.wsdl", array('trace' => 1));

// Show all possible functions that can be used
show($client->__getFunctions()); 

// Make a call to the getColors method and print out the results
$info = $client->__soapCall("getColors", array());
show($info); 

// Make a call to the getNames method and print out the results
$names = $client->__soapCall("getNames", array("set" => "all"));
show($names); 

And the client is done. I created another function here called “show” which just wraps the array in “pre” tags. And now the client is complete. Make sure you test your WSDL file, and for complete compatibility, check the webservice in something like SoapUI and build a quick C# console app to make sure that can read from it. Once that happens, your webservice should be able to talk to any app, even if it does not use PHP on the back end. So have fun coding and building these webservices.

All Code Files and Examples, WSDL, etc

The sample data is in a MS SQL Server database. The table contains a record ID, title id, author id, genre, type, last check out date, and edit date. It is possible to have duplicate title, author IDs in the table. We need to extract all DISTINCT title IDs, along with the other information listed where the type is not a paperback, and provide a paginated list. I am sure this would be better architected if needed in the real world. Paginate will only get us so far, as this would only show all records.

class BooksController extends AppController {
    var $paginate = array(
        'order'        => array('Book.id' => 'desc'),
        'fields'    => array('Book.id', 'Book.title_id', 'Book.author_id', 'Book.genre_id', 'Book.type', 'Book.check_date', 'Book.edit_date'),
        'limit'        => 15,
    );
    . . .
    function index(){
        $this->set('hardback_books', $this->paginate());
    }
}

We need to use more to build a conditional query so the paginate will query against this. We can use CakePHP’s data source to help in this. Now, we could also just write this query out ourselves, but this is helpful to know so when you have to build sub-queries for other items. All data is in MS SQL Server, and we can use normal SQL expressions, but we need to grab DISTINCT data, which goes by rows, not columns, which means we will need to do 2 sub-queries in addition to the main one. So we first need to grab a list of the TOP 1 items. This will be our inner query.

        SELECT TOP 1 *
        FROM [books] AS [bk_inner]
        WHERE
            [bk_inner].[title_id] = [Book].[title_id]
            AND
            [bk_inner].[type] <> 'paperback' 

Next, we need to encapsulate that query with an outer one that will select all items which match up to the main query ID.

    SELECT * FROM
    (
        SELECT TOP 1 *
        FROM [books] AS [bk_inner]
        WHERE
            [bk_inner].[title_id] = [Book].[title_id]
            AND
            [bk_inner].[type] <> 'paperback'
    ) AS [bk_outer]
    WHERE bk_outer.[title_id] = Book.[title_id] 

So we have the queries, and it needs the main query needs to constrain the results that exists in the sub-queries.

SELECT TOP 15
    [Book].[id],
    [Book].[title_id],
    [Book].[author_id],
    [Book].[genre_id],
    [Book].[type],
    CONVERT(VARCHAR(20), [Book].[check_date], 20)
    CONVERT(VARCHAR(20), [Book].[edit_date], 20)
FROM [books] AS [Book]
WHERE EXISTS
(
    SELECT * FROM
    (
        SELECT TOP 1 *
        FROM [books] AS [bk_inner]
        WHERE
            [bk_inner].[title_id] = [Book].[title_id]
            AND
            [bk_inner].[type] <> 'paperback'
    ) AS [bk_outer]
    WHERE bk_outer.[title_id] = Book.[title_id]
)
ORDER BY [Book].[id] desc

We have the final full query. Now how do we get that? First, we need to invoke the getDataSource() method.

class Book extends AppModel {
    . . .
    function getHardbackBooks(){
        $dbo = $this->getDataSource();

Next we need to use the buildStatement() to build each statement. Since CakePHP will build a sub query with this, we have to do this twice: once for the inner query, and once for the outer query. The “table” for subquery2 will actually be subquery1, so we need to add that as a “table” in the array.

$subquery1 = $dbo->buildStatement(
	array(
		'fields' => array('TOP 1 *'),
        'table' => $dbo->fullTableName($this),
        'alias' => 'bk_inner',
        'limit' => null,
        'offset' => null,
        'joins' => array(),
        'conditions' => 'bk_inner.title_id = Book.title_id AND bk_inner.type <> \'paperback\'',
        'order' => null,
        'group' => null

	),
	$this
);

$subQuery2 = $dbo->buildStatement(
    array(
        'fields' => array('*'),
        'table' => '(' . $subquery1 . ')',
        'alias' => 'bk_outer',
        'limit' => null,
        'offset' => null,
        'joins' => array(),
        'conditions' => 'bk_outer.[title_id] = Book.[title_id]',
        'order' => null,
        'group' => null
    ),
    $this
);

Now, we need to make sure we add an EXISTS:

$subQuery = ' EXISTS (' . $subQuery2 . ') ';
return $subQuery;

Return the data from the model to the controller. In the controller function we need to add a new condition to the paginate. In the conditions, we do not need to use a paired item value to set it, we can use the straight SQL returned from the model.

class BooksController extends AppController {
    var $paginate = array(
        'order'        => array('Book.id' => 'desc'),
        'fields'    => array('Book.id', 'Book.title_id', 'Book.author_id', 'Book.genre_id', 'Book.type', 'Book.check_date', 'Book.edit_date'),
        'limit'        => 15,
    );
    . . .
    function index(){
        $data = $this->Book->getHardbackBooks();
        // Set to the paginate object conditions
        $this->paginate['conditions'] = array($data);
        $this->set('hardback_books', $this->paginate());
    }
}

And it returns the items based on the paginate parameters, ready to use in the view. It provides a DISTINCT list. And yes, I know I used more than 400 words in this one. It was closer to 500 without the code. Oh well, maybe tomorrow will be shorter.

CakePHP

CakePHP provides some functionality for finding the data, this is done using the “find” method. You can read more about this at the Cookbook. Using this, one can grab data from many different tables if needed, or just one table. For this exercise, I am going to use dummy data to show how to find data, using simplistic finds, and using joins, and sub-queries. So first lets examine the data tables. Not all of these are going to be connected. This is a very simplistic, quickly drawn up solution to a lending library

Sample Tables

In the image above, shows some sample tables, and these are just made up, and contain sample rows that may exist in those tables. The BOOKS and AUTHORS tables are a HABTM relationship, with a connecting table. The PUBLISHERS has many BOOKS. And the INVEN_ITEMS contains a multiple list of books that show whether the book is available or not. So we can start grabbing the data.

First we need to get a count for all books.

$total_books = $this->Book->find('count'); 

Now grab all authors, age, bio, book name, total pages, publish date for a single book with the ID of 212:

$details = $this->Book->find('first',
    array(
        'conditions' => array(
            'Book.id' => '212',
        ),
        'fields' =>array(
            'Book.name',
            'Book.pages',
            'Book.publish_date',
            'Author.name',
            'Author.age',
            'Author.bio',
        ),
        'recursive' => 0,
    )
);

This will create a query statement to grab the data for the set fields, and only for the book id that equals 212. Recursive is set to 0 so it will grab all related data. Remember that this is a HABTM item, so CakePHP will take that into account and grab all authors for the book. We can leave off the recursive, I just find it is best practice to put this in in order to make the query more readable by someone who did not develop the application.

Find all Publishers:

$publishers = $this->Publisher->find('all'); 

Now three example of using the find technique in a basic way. More examples are available in the cookbook. Now what if we need to grab all the detailed information on the inventory items, and the tables are not connected in a CakePHP relationship? Without using a framework, the query statement would need to contain JOIN statements to get all the data we need. So the following is an example of this, again getting detailed info for the Book ID of 212:

$details = $this->find('first',
    array(
        'joins' =>array(
            array(
                'table' => 'books',
                'alias' => 'Book',
                'type' => 'LEFT',
                'conditions' => array(
                    'Book.id = Inven_item.book_id',
                ),
                'recursive' => -1
            ),
            array(
                'table' => 'books_authors',
                'alias' => 'BookAuthor',
                'type' => 'LEFT',
                'conditions' => array(
                    'BookAuthor.book_id = Book.id',
                ),
                'recursive' => -1
            ),
            array(
                'table' => 'authors',
                'alias' => 'Author',
                'type' => 'LEFT',
                'conditions' => array(
                    'Author.id = BookAuthor.author_id',
                ),
                'recursive' => -1
            ),
            array(
                'table' => 'publishers',
                'alias' => 'Publisher',
                'type' => 'LEFT',
                'conditions' => array(
                    'Publisher.id = Book.publisher_id',
                ),
                'recursive' => -1
            ),
        ),
        'conditions' => array(
            'InvenItem.book_id' => '212',
        ),
        'fields' =>array(
            'Book.name',
            'Book.pages',
            'Book.publish_date',
            'Book.quick_overview',
            'Author.name',
            'Author.age',
            'Author.bio',
            'Author.country',
            'Publisher.name',
            'Publisher.location',
            'Publisher.state',
            'Publisher.country',
            'InvenItem.isbn',
            'InvenItem.available',
        ),
        'recursive' => -1
    )
);

For whatever reason, the Inventory was not connected to the other tables, and so we force a join on the query. In the JOINS, we set this to a -1 recursive so it does not pull in all the other data. Now this is only one solution to put an example of a JOIN on a query. We have the tables, joined in tables, conditions, and recursive set. Once you get the data, then it will show all inventory items, details for the book, and whether or not the copy is available at the present time.

Now this may not be the best way to grab the data, and this is just for example purposes as well. Next week I will go further into detail about setting multiple conditions using ‘OR’ instead of ‘AND’, creating a simple search on possible conditional search terms and areas, and I may even create a quick little app to demonstrate this in real life.

The data we need for this application includes some basic information: movie title, genre(s), stars, directors, writers, story information, rating, release year, rent price. We can include a lot more data if we really needed to, but for the purpose of this, we will keep it a little simple. A possible way of modeling this data is to create a table that stores all of this information, and have one table in the database. But now when we need to add something else, we have to add columns to the table. For example, in a few months the company decided to add related titles, sequels and sets, etc. It would require a refactor of the data in order to handle this, as well as refactor of the code. So lets split this out.

In the image below, I divided the content based on a few things: Title data, Talent Data, Genre Data, Rating Data

Starting the data model design

I now have the four main tables, but we need to figure out how these are related. First lets tackle the Rating Data, as that will be a simple design. I am linking to the IMDB so you can look at the data. The ratings available in the United States, at least the ones we will include, are: G (General Audiences), PG (Parental Guidance suggested), PG-13 (Parents strongly cautioned) and R (Restricted, no one under 17 allowed without a parent, or as I call it, PG-17). So each rating will be housed in this table. We will need an identifier, the rating, the explanation, and some data to track creation and modification. We do not need those last two, but it is just good practice to include those if there is ever going to modification on data. Using our example film, it is rated “R”. And since any film title object (Titles) will ever only have one rating (for the sake of this example) there is an easy relation of a hasOne relation to the Ratings table. We need to add a foreign key to the Titles table and connect these.

Title hasOne Rating

Easy to connect those. Now, we need to tackle the Genres. This is a little more complicated, but we can get through this. The Genres table will house the genres we need to display. This list can be as big or small as needed. Our example movie is in the “Drama” genre according to IMDB. However, in our application, the business has decided the movie is classified as Drama and Action. So now a title is going to have many genres. And a genre can belong to many titles. The “Drama” genre may belong to multiple titles. So we can not just add a new column to the Titles table, as that will not satisfy the requirements. We need to add a connecting table, and according to the naming convention of CakePHP, the name of the connector table is the alphabetical order of the two tables it is connecting.

So we need to add a table titled “Genre_Titles”. It will have an ID, and foreign keys to both tables.

Connecting the Genre and Title tables

Now we are almost done with the HABTM set up. We made it through one of them, and that was a good thing. See it was not so difficult. Now, we need to finish this up, and connect the talent table to the title. Talent can be anything. Since the company wants to display the stars of the show, the directors and writers, we need to be able to connect these. And again, this will require a a HABTM relationship. An actor can be in many titles, just like Clint Eastwood, as he was not just in Gran Torino. So he may be listed in many titles. And, with this movie, he not only stars in it, he directed it. So now we not only need to match up this talent, we have to identify it correctly. So this adds a little complexity to this, but we can do this.

As you know from the previous example, we need to create a connecting table. The name would be “Talent_Titles”. But that still will not solve the issue of identifying Clint Eastwood as an actor and director in the title. We can add a new table “Talent_Types”. This will be a “lookup table” that houses Star, Director, Writer as values. We can then connect that to the connecting table. This relationship will be a hasMany to Talent_Titles, as a star may have many entries in the Talent_Title table.

HABTM Talent and Title

And that is the HABTM design. Using the Bake method, you can now bake this up, and set up the model. The thing to remember about the HABTM, it is not something to fear. Usually, if a connecting table is needed, you have a HABTM design. Remember to think in human terms when examining the data model. What does this belong to, what does it have. In this, the Title will have many actors, directors, etc. And the actors, directors, etc will belong to many titles.

If you Baked each object, and used the Bake methods to create the model, and associations, as well as the controllers an views, you will have some code ready to use and ready to go. After you have Baked these items, the sample code that is created is ok to begin with. However, we want to take advantage of a very important technique, and the is the centralization of code, and prevent code duplication. There is one other thing that gets to me, and this is more of an OCD thing for me in code, and that is the way that Cake does the edit check in the controller. In the base created code, it creates a section of code that checks for an ID. If it is not passed, then it redirects the page elsewhere. Like so:

function edit($id = null) {
    if (!$id && empty($this->data)) {
        $this->Session->setFlash(__('Invalid resume', true));
        $this->redirect(array('action' => 'index'));
    }
    . . . .
}

So in this code segment, if one gets to the edit form, and an ID is passed, and the form is not filled in, then it will display the actual form. And if the ID is not passed in, then it redirects to the Index page. For examples, if the site name was test.com:
www.test.com/resume/edit/2 – will result in the form being shown
www.test.com/resume/edit – will result in a redirect and the error message

Now here is where my OCD kicks in a little. . . .

If the table is housing 3 resumes, IDs of 1,2, and 3 and you go to the edit page for those resumes, it will display the resume content. But, for kicks and giggles, what if we passed in this as the URL:
www.test.com/resume/edit/350

This will display a blank form and even allow one to input data, fill it out, and submit it. Now granted, the processing of it alone will provide a new resume. However, that is why we have an “Add” function. Why not create some logic to check to see if the ID is valid to begin with? This will help on both the edit, and view methods in the controller. (as the View function will behave the same way as the edit function on display). And it is not just for this controller, but it will likely be an issue in all controllers. What I did in this case, is provide a function in the App Model code so that it can check those. Here is one way to solve this. And there can be multiple ways to resolve this issue, this is just one method I have done.
In the app/app_model.php code:

function ifExists($model = null, $id){
    if ( ($model == null) || ($model == '') ||(is_null($id)) ||($id == '') ){
        return 0;
    }
    $check = $this->find('count', array('conditions' => array($model . "." . strtolower($model) . '_id' => $id)));

    return $check;
}

The way I set up my models for the primary key is tableName_id. So for the resume table, the primary key is “resume_id”, and for the skills table it is “skill_id” and so forth. You can always modify this to use whatever naming convention you use. In this function, it checks to see if the model is passed. If it is not, returns a false. If a model is passed, then it runs a quick find query to see if that ID exists in the table. If it finds anything, then it returns a “1″ (or true), if not, then a “0″ (or false). By sticking this in the app_model.php file, it is now accessible by all models. To use this, in the edit function, for example, in the resume controller:

function edit($id = null) {
    if ( ((!$id) || (!$this->Resume->ifExists('Resume', $id))) && empty($this->data)) {
        $this->Session->setFlash(__('That Resume does not seem to exist, please try this again.', true));
        $this->redirect(array('action' => 'index'));
    }
    . . .
}

This will check for an ID, checks to see if that resume exists, and that the form is not filled in yet. If the ID does not exist in the table, then it redirects to the Index page, with a customized message. I could also redirect to the add page with no message, and this is entirely up to you on how you want to do this.

For the View function, it is very similar:

function view($id = null) {
    if ( (!$id) || (!$this->Resume->ifExists('Resume', $id)) ) {
        $this->Session->setFlash(__('That Resume ID does not seem to exist. Please try again', true));
        $this->redirect(array('action' => 'index'));
    }
    . . .
}

Again, check for an ID, and then make sure it exists in the table. If not, then redirect. A small bit of code to help keep the application from having odd behavior and keep it clean.

Next is to process the forms. By using Bake, it creates two functions, add and edit. Both process the forms as needed. Which there is nothing we can do to clean that up. However, some basic pre-commit tasks are still to be done. One thing I am highly in favor of is sanitizing the data. If there is some basic checks we need to do on the data, then we must also do that as well. For this we, will use the jobs controller/model for the example.

In each row of the job, we have a start date and an end date. In the model, we will validate these fields to be a “date”. We also need to validate these dates in another way. The end date can not be earlier than the start date. It is quite impossible to end a job three months before you even start it. So we want to keep that in check as well. And let’s say we want to do that in the controller. So now we need to sanitize the data, and check the dates. This can be redundant in the code, as it will exist in the edit and add functions. And if we need to make a change to the logic, it will cause an issue in two places. So, we can take that and put this in its own function. First we start with the sanitation of the data. At the top of the file, place

App::import('Sanitize');

Then create a new function and place the sanitation in this function:

function validateForm($data){
    $san = new Sanitize();
    // Clean the data
    $this->data = $san->clean($this->data);
    $this->data['Job']['company_name'] = $san->paranoid($this->data['Job']['company_name'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['via_company']  = $san->paranoid($this->data['Job']['via_company'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['location']     = $san->paranoid($this->data['Job']['location'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
     . . .
}

In this, I am cleaning the Company Name, the Via Company (in case it was a contract job), and Location. The next thing we need to do is create the logic to test the dates.I am just going to create a simple number using the fields from the form. Then I will compare the 2 numbers, and if the end is less than the start, then it is an error. So the entire function is:

function validateForm($data){
    $san = new Sanitize();
    // Clean the data
    $this->data = $san->clean($this->data);
    $this->data['Job']['company_name'] = $san->paranoid($this->data['Job']['company_name'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['via_company']  = $san->paranoid($this->data['Job']['via_company'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
    $this->data['Job']['location']     = $san->paranoid($this->data['Job']['location'], array(' ', '.', '/', '-', '*', '&', '(', ')',','));
     . . .   

    $errors = array();

    // Set the dates in a usuable format
    $start = $data['Job']['start_date']['year'] . $data['Job']['start_date']['month'] . $data['Job']['start_date']['day'];
    $end   = $data['Job']['end_date']['year'] . $data['Job']['end_date']['month'] . $data['Job']['end_date']['day'];
    $today = date('Ymd'); 

    // Check to make sure the start date is not later than the end date
    if ( $start >= $end ){
        // $this->Job->invalidate('start_date', "The Start Date must be earlier than then End Date");
        $error['err']['field'] = 'start_date';
        $error['err']['messg'] = 'The Start Date must be earlier than then End Date';
    }

    // Check to see whether or not to include the end date as part of the insert
    if ( $end == $today ){
        $error['end'] = 0;
    } else {
        $error['end'] = 1;
    }
    $data[error] = $error;
    return $data;
}

Now we need to be able to use that in the actual form. And we need to invoke an error in case there is an issue. If an error is found, we need to invalidate the field and provide the error message. That could be done in the following way:

function edit($id = null) {
    . . .
    if (!empty($this->data)) {
        $check = $this->validateForm($this->data);
        // Check to make sure the start date is not later than the end date
        if ( isset($check['Error']['err']) ){
            $this->Job->invalidate($check['Error']['err']['field'], $check['Error']['err']['messg']);
        }

        // Set the data to the model now
        $this->Job->set( $check['Job'] );

        if ( $this->Job->validates() ) {
            // Do the normal process/save stuff
            . . .
        }
         . . .
    }
    . . .
}

In this example, it shows how to find ways to cut down code repetition. Now I am sure we could even set this validation in the model as well. I am just giving an example of what we can do. Now using this, we can set up all the different functionality of the resume application.

In the next post, I will go through how to secure the Resume so only parts are seen by the world, and which parts you would have to log in for, and why. I will also go into a centralized query for all resume elements and be able to display.

1. The model is Topic, with a table in the DB labeled “topics”
2. Only the admin has access to add or edit the topics
3. All comments on this topic will be done through the Facebook API/Social Plugin Comments
4. Topics will have a title that will also double as the Unique ID (to be explained later)
5. Topic titles, or themes, will not be allowed to be edited, to be explained why later
6. Administration of the comments will be done by the Facebook Application admins, which differs from the site admins
7. Start Dates will determine if the topic is allowed to be visible yet
8. End dates are optional, and will be built upon later with more advanced FBML/FB JS libraries

And there it is, some basic ideas behind the whole idea. So now lets get into some of the items called out in Numbers 4 and 5

With the Facebook Comments, you can get a base idea behind what this entails at the following location:
http://developers.facebook.com/docs/reference/plugins/comments
This will give you the basic comment box to add to the site. The important part of this comment box is the “Unique ID”. This will add all the comments to the basic page. However, it must be Unique and not change. In my requirements above, I am listing the topic title as the Unique ID. I could easily generate a number for this and add a couple of letters to it to make it truly unique and allow the title to change. In this example, I want to emphasize certain elements, so that is why I chose to do it this way. You can easily do this differently and still have it work. But this leads to Number 5.

The Unique ID should not change for the page, topic, area, etc. If the ID changes, all previous comments vanish and you basically are starting over. So it is important that the IDs are unique and do not change. This way the element of participation is intact. It will always stay in your site.

Another note. This example is showing how to include Facebook API in a CakePHP application. You can follow these same techniques for just about any site, no matter what framework. Just apply the same inclusion techniques in the proper location for the different framework/php site.

Creating the base elements and DB table

So, let’s get this thing going. First you should have a CakePHP site going and ready, connecting to a DB somewhere. Bake the Model, Controller and Views for this one. The SQL for the Topics that I am using is below:

CREATE TABLE IF NOT EXISTS `topics` (
  `topic_id` int(11) NOT NULL auto_increment,
  `topic_slug` varchar(255) NOT NULL COMMENT 'Slug for use in the Facebook comments',
  `question` text NOT NULL COMMENT 'Question that is created for the different topics',
  `start_date` date NOT NULL COMMENT 'Start date for the question',
  `end_date` date default NULL COMMENT 'End date for the question',
  `created` datetime NOT NULL,
  `modified` datetime NOT NULL,
  PRIMARY KEY  (`topic_id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 COMMENT='Topics for discussions and other items' AUTO_INCREMENT=1012 ;

I baked this using the basic CRUD for the views and Controller, no Admin hooks, and the Model validation is as follows:

class Topic extends AppModel {
    var $name = 'Topic';
    var $primaryKey = 'topic_id';
    var $displayField = 'topic_slug';
    var $validate = array(
        'topic_slug' => array(
            'minlength' => array(
                'rule' => array('minlength', 3),
                'message' => 'The Topic Identifier should be longer than 3 characters',
            ),
            'maxlength' => array(
                'rule' => array('maxlength', 50),
                'message' => 'The Topic Identifier should be no longer than 50 characters',
            ),
        ),
        'question' => array(
            'minlength' => array(
                'rule' => array('minlength', 3),
                'message' => 'You need to have a question at least 3 characters long',
            ),
        ),
        'start_date' => array(
            'date' => array(
                'rule' => array('date'),
                'message' => 'Please set a valid start date for this question',
            ),
        ),
    );
}

Controller work for the Index

I removed all the links to Add, Edit and Delete from the views and kept those hidden except for the Admin. Now comes the controller. This is the important part of this, as we need to include the Facebook items, and based on the last post, we put those in the Vendors, so we need to include this. I am also using Sanitize, Auth and few others (Security and Email), along with the helpers of HTML and FORM.

<?php
App::import('Sanitize');
App::import('Vendor', 'facebook');
class TopicsController extends AppController {

    var $name = 'Topics';
    var $helpers = array('Html', 'Form');
    var $components = array('Security', 'Auth', 'Email');

it is important to import the Facebook library. I will not go over the Auth in this example, or the beforeFilter or isAuthorized functions. The first action we need to deal with is the index() function. Originally, it looks like:

function index() {
        $this->Topic->recursive = 0;
        $this->set('topics', $this->paginate());
    }

For our purposes, we want to limit the amount of posts shown to only those that have a start date that is equal to or less than today’s date. I have three examples in my DB, and you can create as many as you want for the example. Just make sure at least one is in the future. Right now when we look at the Index page, it is showing all topics. So we need to set different items in the call for paginate. To only grab those that are equal to or less than to today’s date, we will alter the call to paginate as follows:

$today = date('Y-m-d');
$cond = array('Topic.start_date <=' => $today);
$this->set('topics', $this->paginate('Topic', $cond));

This will limit all the posts to display to everyone to only those with a current (or past) start date. All those with a start date in the future will not be available until that date. But we also need to set a variable for the Admin to see all those topics waiting for the future.

$future_topics = $this->Topic->find( 'all', array('conditions' => array('Topic.start_date >' => $today)) );
$this->set('futop', $future_topics);

We now have 2 variables to work with in the view. You can do it a whole slew of different ways, and that is fine, this is just the method I prefer to do it. Now we need to get the view going. This is going to a little different, I have a few things to show Admin stuff just to admins, and show the future topics just to admins.

The Add and Edit functions

That does it for the view, now we need to do the Add and Edit functions. Remember we baked this, and let all the default take place. But, I need to get a valid Unique ID, and do not want any spaces in it. So we will alter the Add function to do this. And for the Edit function, we want to prevent any editing of the slug area.

function add() {
        if (!empty($this->data)) {
            $san = new Sanitize();

            $this->data['Topic']['topic_slug'] = $san->paranoid($this->data['Topic']['topic_slug'], array(' '));

            $this->Topic->create();
            // Slug the topic title before saving
            $this->data['Topic']['topic_slug'] = preg_replace('/ /', '_', $this->data['Topic']['topic_slug']);
            if ($this->Topic->save($this->data)) {
                $this->Session->setFlash(__('The new Topic has been saved and will be put in queue', true));
                $this->redirect(array('action' => 'index'));
            } else {
                $this->Session->setFlash(__('The Topic could not be saved. Please, try again.', true));
            }
        }
    }

I am sanitizing the data for the slug, and trusting myself for the topic details. In real life, we would apply a sanitizing effect to this field as well. I then erase all non alphanumeric characters, and replace spaces with an underscore “_”. Then save it up. I am basically leaving the “add.ctp” alone with what was baked. I removed the fields that I really do not care about.

So now we move to the edit. We want to prevent any changes to the topic_slug, so in the form, we will remove this from the form and make sure we remove the underscores when showing it. The controller is:

function edit($id = null) {
        if ( ((!$id) || (!$this->Topic->ifExists('Topic', $id))) && empty($this->data) ) {
            $this->Session->setFlash(__('The Topic you selected does not exist, please try again.', true));
            $this->redirect(array('action' => 'index'));
        }
        if (!empty($this->data)) {
            if ($this->Topic->save($this->data)) {
                $this->Session->setFlash(__('The topic has been saved', true));
                $this->redirect(array('action' => 'index'));
            } else {
                $this->Session->setFlash(__('The topic could not be saved. Please, try again.', true));
            }
        }
        if (empty($this->data)) {
            $this->data = $this->Topic->read(null, $id);
        }
    }

One quick thing to call out in this function. I added a new function to the parent app_model.php to make sure that the ID we are trying to edit exists and is valid. The basic baked function only checks for an ID, if one exists, it goes thru to the form, even if the ID does not exist in the DB. On the edit.ctp view, I removed the form element for the topic_slug and added this:

$topic_title = preg_replace('/_/', ' ', $this->data['Topic']['topic_slug']);
echo "<b>Topic Title</b>:   <h4>" . ucwords($topic_title) . "</h4>";

And now the edit form works, keeps the underscore in and saves the form. Again, in the real world, you would want to do a little more on the back end to ensure there is no changes being made. But now we get to the view area and where the Facebook API/Social Plugin comes in.

Creating the Detail View and adding in Facebook API/Social Plugin

So here is where we get to the meat of the post. All other areas were in preparing to get here. Now, all you need to do is create a few different topics to work with. We want to alter the view in such a way it will display only the items we need, and will only display the topic to an admin if it is a future topic. Otherwise return the user to the index for topics with a message saying that the topic does not exist or is not yet available. So the view function is simple:

function view($id = null) {
        if ( (!$id) || (!$this->Topic->ifExists('Topic', $id)) ) {
            $this->Session->setFlash(__('The requested topic does not exist. Please try again.', true));
            $this->redirect(array('action' => 'index'));
        }
        // Make sure this is a valid ID as well
        $topic = $this->Topic->read(null, $id);
        $topic_title = $topic['Topic']['topic_slug'];
        // Set the title without the slug
        $topic_title = preg_replace('/_/', ' ', $topic['Topic']['topic_slug']);
        $topic['Topic']['topic_title'] = ucwords($topic_title);

        // make sure this topic is valid
        if ( ($topic['Topic']['start_date'] > date('Y-m-d')) && (!$this->is_admin) ){
            $this->Session->setFlash(__('The requested topic does not seem to be available at the present moment. Try again later.', true));
            $this->redirect(array('action' => 'index'));
        }
        $this->set('topic', $topic);
    }

Again, I used the app_model.php function to make sure the topic ID exists as well as being valid. If not, a message will be displayed to the end user. It sets the topic, and now we are ready for the view.

So what I did, was wipe all the data for the list, and added my own. I set the title to the H2 element. I set the question to a paragraph tag, and added the new FBML comment tag. The information for this tag can be found at:
http://developers.facebook.com/docs/reference/fbml/comments_%28XFBML%29

Pay close attention to the different parameters you can set and how you can format this to fit your style on your site. I have set the following elements and values:
xid = $topic['Topic']['topic_slug']
width = 600
title = $topic['Topic']['topic_title']
publish_feed = false

And so the actual markup added to the page is the following, including the FBML script and div tag:

<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js#appId=APP_ID&xfbml=1"></script>
<fb:comments xid="<?php echo $topic['Topic']['topic_slug']; ?>" width="600" title="<?php echo $topic['Topic']['topic_title']; ?>" publish_feed="false"></fb:comments>

And if you go to the page you will now see the comments section, but we are missing a very important item in the comments, and that is administration. The way to add this, we will need to add the correct element to the page. This consists of adding the correct JS API to the site.

According to the documentation, you have to be listed as a developer for the application to be able to administer comments. The way we have it set up right now, we can have comments, but there is no way we can administer those. The key to this is very simple and easily overlooked. In the FBML markup that we added to the view, you will notice a specific section:

http://connect.facebook.net/en_US/all.js#appId=APP_ID&xfbml=1

You must input your application ID to this markup. Once you do that, and if you are listed as a developer, then you are able to now administer comments on your site.

See, that was easy. There is a lot of text on this post, and most of it has to do with setting up CakePHP to do this. Once we got to the Facebook API/Social Plugin section, it was very simple. With the next post, we will expand on the comments section a little further and see what else is possible.

You can see this all in action at the following:
www.stephenhird.com

So lets go ahead and dive into it. If you do not have the application ID for your Facebook application, you can get it at the following:

http://www.facebook.com/developers/apps.php

The next thing is to grab the API and code from Facebook. This can be found at the following page:

http://developers.facebook.com/docs/

This is the main page, and you will need to scroll to the bottom of the page. This will list different APIs that are available. I am going to be using the PHP and JavaScript SDKs. This will provide the back end that I will want, and will also provide a positive user experience on the front end. So be sure to download both SDKs.

After that, now we need to start getting some stuff set up. In this post, I am just going to explain how to get this set up, and working right now. It is important that we get the correct items working, and so we will be working with the “pages” area for the JS SDK, and creating a very simple controller for the PHP SDK so we can get set up and running. I am just using, for right now, the base CakePHP CSS styles and layouts. All we need is a page to display some of the basic items to ensure that we have installed the SDKs in the proper locations. So lets go.

Step 1: Download the SDK and move them to the following locations:
A. PHP SDK (facebook.php)
I put this at the following location:
./app/vendors/facebook.php
This will be used in the controllers and be imported by the controllers

B. JavaScript SDK
I put the entire “src” directory in the following location:
./app/webroot/js/src

Step 2: Create a “test” page where we can see the Facebook JS SDK to make sure it works
I just created a new file:
./app/views/pages/facebook.ctp
This will be visible at the following: http:///pages/facebook

Step 3: Copy the example in the jQuery folder, alter your default layout
Reformat the example after you copy it to the ./app/views/pages/facebook.ctp to take out the header stuff. We only need the body, and make sure you put the header stuff in the default layout. Below is the code to add to the default layout:

<!doctype html>
<html xmlns:fb="http://www.facebook.com/2008/fbml" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <?php echo $this->Html->charset(); ?>
    <title>
        <?php __('CakePHP: the rapid development php framework:'); ?>
        <?php echo $title_for_layout; ?>
    </title>
    <?php echo $this->Html->css('cake.generic'); ?>
    <?php echo $scripts_for_layout; ?>
    <style>
        body {
            font-family: 'Lucida Grande', Verdana, Arial, sans-serif;
        }
        h1 a {
            text-decoration: none;
            color: #3b5998;
        }
        h1 a:hover {
            text-decoration: underline;
        }
    </style>
</head>
<body>

Simple code to put in to test the JS API:

<h1>Connect JavaScript - jQuery Login Example</h1>
    <div>
      <button id="login">Login</button>
      <button id="logout">Logout</button>
      <button id="disconnect">Disconnect</button>
    </div>
    <div id="user-info" style="display: none;"></div>

    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>

    <div id="fb-root"></div>
    <script src="http://connect.facebook.net/en_US/all.js"></script>
    <script>
      // initialize the library with the API key
      FB.init({ apiKey: 'YOUR API KEY WOULD GO HERE' });

      // fetch the status on load
      FB.getLoginStatus(handleSessionResponse);

      $('#login').bind('click', function() {
        FB.login(handleSessionResponse);
      });

      $('#logout').bind('click', function() {
        FB.logout(handleSessionResponse);
      });

      $('#disconnect').bind('click', function() {
        FB.api({ method: 'Auth.revokeAuthorization' }, function(response) {
          clearDisplay();
        });
      });

      // no user, clear display
      function clearDisplay() {
        $('#user-info').hide('fast');
      }

      // handle a session response from any of the auth related calls
      function handleSessionResponse(response) {
        // if we dont have a session, just hide the user info
        if (!response.session) {
          clearDisplay();
          return;
        }

        // if we have a session, query for the user's profile picture and name
        FB.api(
          {
            method: 'fql.query',
            query: 'SELECT name, pic FROM profile WHERE id=' + FB.getSession().uid
          },
          function(response) {
            var user = response[0];
            $('#user-info').html('<img src="' + user.pic + '"><br />' + user.name).show('fast');
          }
        );
      }
    </script>

Now, you should be able to go to your page and see a login button, a logout button, and disconnect. If you are already logged in to Facebook, you should see your own profile image (if you allowed it). If not, click the login button, and if you have the Facebook application set up correctly, and the API correct, you should be able to log in.

Step 4: Check the PHP API
Now that we can see the JS API is working fine, we need to set up something so we can create a test for the PHP API. This is actually easier than it appears.

I first create a new layout just for the Facebook app, which I call facebook.ctp. It basically just erases all Cake icons, other special icons, and any kind of SQL output. Rename the title to “Facebook Testing:” (or whatever you want). Then create a new controller with no model. Use the App::importstatement to include the facebook.php file. Now create an index function, and copy and paste the PHP area from the example included in the PHP SDK into the “index” function. It may be similar to this:

<?php
App::import('Vendor', 'facebook');
class FbsController extends AppController {
	var $name = 'Fbs';
	var $uses = null;	

	function index() {
	    // Set the layout
        $this->layout = 'facebook';        

        // Create our Application instance (replace this with your appId and secret).
        $facebook = new Facebook(array(
            'appId'  => 'YOUR APPLICATION ID WOULD GO HERE',
            'secret' => 'YOUR SECRET KEY HERE - DO NOT DISPLAY THIS TO ANYONE',
            'cookie' => true,
        ));

        $session = $facebook->getSession();
        $appID   = $facebook->getAppId();
        $uid     = '';
        $me = null;
        // Session based API call.
        if ( $session ) {
            try {
                $uid = $facebook->getUser();
                $me = $facebook->api('/me');
            } catch (FacebookApiException $e) {
                error_log($e);
            }
        }

        $logoutUrl = '';
        $loginUrl  = '';

        // login or logout url will be needed depending on current user state.
        if ( $me ) {
            $logoutUrl = $facebook->getLogoutUrl();
        } else {
            $loginUrl = $facebook->getLoginUrl();
        }
        // Set the variables to use in the view
        $this->set(array(
            'facebook'  => $facebook,
            'session'   => $session,
            'me'        => $me,
            'logoutUrl' => $logoutUrl,
            'loginUrl'  => $loginUrl,
            'appID'     => $appID,
            'uid'       => $uid,
        ));
	}
}
?>

In this controller, we are setting the basics we need for the application. Using the SDK to see if they are logged in, getting our app id, and setting the proper variables to be used later. We set the login or logout URLs to display the proper links. Finally, we are setting the variables to be used in the view.

Now we need to create a new directory in the views area named “fbs” and a file in that directory named “index.ctp”. This view will house the base items for displaying the example. You can copy the HTML parts from the example.php and use them in this view. I modified it a little to alter what is shown.

<h2>Test Facebook File</h2>
<div id="fb-root"></div>
    <script>
      window.fbAsyncInit = function() {
        FB.init({
          appId   : '<?php echo $appID ?>',
          session : <?php echo json_encode($session); ?>, // don't refetch the session when PHP already has it
          status  : true, // check login status
          cookie  : true, // enable cookies to allow the server to access the session
          xfbml   : true // parse XFBML
        });

        // whenever the user logs in, we refresh the page
        FB.Event.subscribe('auth.login', function() {
          window.location.reload();
        });
      };

      (function() {
        var e = document.createElement('script');
        e.src = document.location.protocol + '//connect.facebook.net/en_US/all.js';
        e.async = true;
        document.getElementById('fb-root').appendChild(e);
      }());
    </script>

    <?php if ($me): ?>
        <a href="<?php echo $logoutUrl; ?>">
          <img src="http://static.ak.fbcdn.net/rsrc.php/z2Y31/hash/cxrz4k7j.gif">
        </a>
    <?php else: ?>
        <div>
          Using JavaScript & XFBML:
          <br />
          <fb:login-button></fb:login-button>
          <br /><br />
        </div>
        <div>
          Without using JavaScript & XFBML:<br />
          <a href="<?php echo $loginUrl; ?>">
            <img src="http://static.ak.fbcdn.net/rsrc.php/zB6N8/hash/4li2k73z.gif">
          </a>
        </div>
    <?php endif ?>

    <h3>Session</h3>
    <?php if ($me): ?>
        <pre><?php
        echo "session.base_domain - " .
            $session['base_domain'] . "<br />session.expires - " .
            $session['expires'] . "<br />";
        ?></pre>

        <h3>You</h3>
        <img src="https://graph.facebook.com/<?php echo $uid; ?>/picture?type=large" />
        <br />
        <?php echo $me['name']; ?>

        <h3>Your User Object</h3>
        <pre><?php print_r($me); ?></pre>
    <?php else: ?>
        <strong><em>You are not Connected.</em></strong>
    <?php endif ?>

The login button examples will show two different ways to authenticate the user to the application. The JS example will open a new window and will log them in, post it back to the page and show the login. The non JS example will take the user to the page and give them the Facebook page to log in. Once they log in, it then redirects back to the calling page.

The information on the page shows the Session info, and below that, it shows a large profile image of the person logged in, and then an array of data of all public accessible information. If the person has set their profile to be private, then it will not show a lot of information.

These two examples can be seen at the following, with screenshots below:
The JS SDK example
http://www.stephenhird.com/pages/facebook

JavaScript SDK prelogin

JavaScript SDK post-login

The PHP SDK example
http://www.stephenhird.com/fbs/

PHP SDK example pre login

PHP SDK example post login

In the next post, we will work on getting a good discussion going, which is really, really simple, we will tie it to a DB saved question that can be entered thru an admin form, and then we will examine the moderation of the Facebook comments on the discussion.

The other day I was working on an application with a simple login check and display of an error message. I would test the login function with a correct account and an incorrect account. It was driving me batty as when I logged in with wrong credentials, it would not give me the message that something was wrong. I was checking everything. I checked the controller, the model and the view. Could not pin point the issue. I could not find anything wrong. Here is what I had in the view:

if ($sess->check(errors)) {
    $sess->errors);
}

Basically, if the login is incorrect, it will set an error. The session object will read any errors, set the item in the session to display once, and then kill the error so it does not keep happening. And here is the problem, in another application using the same basic code it works fine. Could not pinpoint why this is a problem here. Until I took a brief walk away from the desk. Then I came back and understood what I needed to do.

The check function does not do any displaying of any kind. It is supposed to check the session for errors, and destroy the session element with the errors. Before it does that, it sets a variable for the errors. However, it does not display. I needed to alter it to this:

if ($sess->check(errors)) {
    echo $sess->errors);
}

And there it was! Wow, the littlest thing. I am reminded of a Simpsons episode in which Hank Scorpio tells Homer:
“Well, you can’t argue with the little things. It’s the little things that make up life.”

Indeed it does.

First I need to figure out what I want to have on my site. Since it is my name that is on the URL, I will need to create a way that this site will be an online portfolio, biography and information repository. When doing this for any site, it is important to remember your brand. Even for individual sites like this, it is important for branding, because this is who I am, I do not want it to be a classic case of slop on the web. This site before was mainly just a testing ground and now will need to be more.

A side note here, my name is the same spelling as a famous photographer based in London. His site is well put together with good descriptive links and a great example of combining minimalist ideas with styled presentation. He keeps his brand on the pages and the site does not confuse or mislead with extra peripheral items, or overuse of Flash or other heavy web technologies loading down the page. His site is located at: http://www.stephenhird.co.uk/

OK, now on to the planning and setting up the Facebook Application.

First I will list out my goals with the site, and why put it in a Facebook application. I am choosing to do this myself, however, these may not really warrant a full blown Facebook application with every site/web application.

1. Describe who I am
2. Display samples of my work, all work: code, art, etc
3. Provide a theme/question for comments and research
4. Provide contact information
5. Online Resume with ability for download (never hurts to have a resume handy)
6. Share my images from different travels and experiences
7. A place where I can see where I have been, where I am going and how to get there

This is the base ideas behind my site. This is for a more personal reflection tying into the other interests in my life.

I am planning on building the base in CakePHP, and adding the Facebook API in to the application. Which means this will also generate more posts on CakePHP application development. The back end will be a DB driven application, with all frontend interaction via Facebook login. All Admin functionality of the site will be outside of the Facebook authentication.

Now since I already have the site up, I need to create the application side in Facebook.

1. Log in to Facebook, or go to this URL: http://www.facebook.com/developers/apps.php
2. New policies for Facebook insist that you either enter a mobile number or a credit card to validate you are a real person. The phone number is what I would suggest to use.
3. After you enter the confirmation code, return to the main window to enter the name of the application and agree to terms
4. Put in the security check code
5. This will take you to the first part of the form

Now the form, it is a quick and easy form to fill out. There are four tabs and I will highlight each and a few items on each that I usually do:

1. About
   • Enter the application name, upload images, icons, etc.
   • Enter the support email or page, and put in a privacy page, very important if you want to have this application take off.
2. Web Site
   • Site url would be the site you are creating to work with the API
   • Domain is important if you want subdomains (for things like mobile domains, etc) to be authenticated using the same key
3. Facebook Integration
   • Canvas will determine how you want the page top appear inside Facebook.
   • This is also where you decide to do a FBML (their markup) or an iFrame. I usually choose iFrame mainly because in my applications the bulk of interactivity is done on the domain and not Facebook. However, you can always do FBML to keep everything in Facebook.
   • Profile tabs will enable new tabs on the app page that can be added/used on individual profile pages
4. Mobile and Devices
   • If you are developing for mobile users, enter the type of core markup to use, and the id for the iTunes app store. Important to read here if you plan on making a mobile app
5. Advanced>
   • Each section in this page holds a very important piece that may affect your application.
   • Authentication holds the sandbox keys, and where Facebook looks if a user takes your app off
   • Migrations holds the areas for callbacks, empty strings and OAuth
   • Security will allow you to enable only a few select IP addresses to access your application on the Facebook platform
   • Advertising and Advanced can do different things for ads, preloading, etc.

Above all else, read the side information if you get stuck, that is why it is there.

Once you are done, click the “Save Changes” button and it will save your data and create your application.

There, you have now just created a shell application on the Facebook platform and ready to enable the client side application.

In order to submit this application, Facebook posts this:
“Your application must have at least 5 total users or 10 monthly active users before you can submit it to the Application Directory. We cannot showcase any applications that are under construction or do not utilize the Facebook Platform.”

So do not expect to create an application and then suddenly have it spread like wildfire. It has to provide useful or entertaining “stuff”, it has to work, and it has to be used. Once it is, then it can be submitted. So we have accomplished step one of the integration. Next up is to get the API on the site, and start developing the site.

When designing the data objects, it is important to understand the data and how it relates to the application and other objects. Usually it is the planning sessions that get overlooked, or hurried, and create a problem for later on. This is why using a tool to help with this is always good. I specifically look for more of an ERD (Entity Relationship Diagram) type of tool that can help me visualize and document the data objects. Never underestimate the power of a visual diagram for data. This is worth everything when coming on a new project, or bringing in new resources to a major project. It can drastically decrease the learning curve. There are different tools out there that can help with ERD and ORM design, with the basic Visio diagrams (a Microsoft product), to more robust ERD tools that include different UML (Unified Modeling Language) tools integrated with it like MagicDraw. Each tool will have its pros and cons, no matter what the toolset is, no matter what the project is. I have found that there is not a single tool that is perfect for every project. But finding a good tool that can help in designing the database is a must. If it can even generate code, that is a lot better. One tool that is available that can help with ERD, and generate code, and help with ORM is ORM Designer. And I will examine this tool as it relates to Symfony, CakePHP and non framework applications.

First off, lets answer a few questions:

1. Why do I need to have an ORM designer if I am not using Propel or Doctrine?
   • You don’t, quite simply. The ORM Designer tool is not just for help with ORM items. It greatly helps in ORM, but is a great tool for ERD design. That may be selling it a little short, but it is very handy for that as well.
2. I use CakePHP and need to help generate the code for the models, will this help?
   • Short answer yes, long answer no. This will help you design the data objects. But if you do not understand the data objects, and how they relate with each other and the actions acted upon the data, then it will not solve those problems.You need to understand the data in order to properly design it.
3. I already have a Symfony app that I took on and am having a hard time visualizing the whole application. Will this help break down the data objects in the application if it is already written?
   • Yes, it will. In one of the examples below I examine this very thing using the Jobeet tutorial. And it is quite impressive in that vein
4. Isn’t this just another tool that requires me learning more about how this tools works and wasting more time on this instead of doing actual coding?
   • Well, I will never tell anyone how to code, nor how to do things. But learning new tools is never a bad thing. Sure it takes time to learn, and it takes patience to learn how to use any new tool. I guess the follow up question to this one is: Do you really want to spend your time coding great projects, or fixing bugs the majority of time because you failed to plan?

OK, I am sure there is more questions. However, let’s go through the actual product. One of the things I like about this product, is the ability to pull in Symfony (or non framework ORM) projects, and the application is deciphered. I used the standard Jobeet tutorial from Symfony, and imported the application. And it gave me the following.

User Object

Job Object

It was great. I could immediately see the relationships in the user object data, and the job object data. But now was the real test. I decided that I needed to add an object for the job object. This was for the benefits. So I added “jobeet_benefits” with an “id”, “benefits_title”, and “description”. I added the association over to the “jobeet_job” object. The user interface is done really well and was easy to add. So that passed. What about code generation. Would it update the code properly? And it was successful to write this over to the <doc root>/sym/config/schema.yml

Now all I need to do is run my propel scripts again, rebuild all the objects, build the DB, and the insert the fixtures and update any forms that were altered to include the new fields. And it works great. This is a great way to visually build, append, and maintain Symfony apps. It also works just as well with non framework Propel applications. I did not test this on Doctrine.

The downside to this though: no CakePHP import. I tried to do a few different ways to import a CakePHP application, and nothing worked. So that was a definite question mark when it comes to CakePHP applications. But since we can not open an existing one, let’s test the new project in CakePHP.

I just opened up the application and started to create a simple application that had a member class, that connected to a profile class. And each member can make a post. I created the objects based on the CakePHP naming convention. It created a good visual of how the entities relate to each other. and then I did an export to see what data would be created. This is the directory structure it created:

-app
 -models
  -base
     basemembers.php
     baseposts.php
     baseprofiles.php
   members.php
   posts.php
   profiles.php
  schema.module.xml

I was interested in why it created a base file set. And I am sure it is because if you put custom code in the model, and then need to update the ORM, it will not overwrite your custom code. So I decided I would test that. I put in a little function that did nothing in the posts.php file. I then went in to change the posts object to add a post title to the object. Then I exported the items again. And the custom function exists! This is a great thing for exporting the model changes. This is why the ORM Designer creates a Base file for the models, to keep custom code from being over-written.

Another good thing, and also a little bit of an area of opportunity, is the CakePHP validation. It makes validation of each field very easy. It provides a great way for each field to have a specific validation rule or rules. However, each validation rule has the same fields available which can be a little confusing to those who may not understand each validation rule. I understand why it is that way, it can just cause some issues for the more inexperienced CakePHP developer.

Now, a quick run down of what I liked about this and what I felt could be a little different:
Pros

• Cost: 99 Euros, approx 127 USD, not as expensive as other tools
• Ability to import Symfony and other Propel/Doctrine projects and be able to quickly get a feel for what the application holds
• In the Windows model it is easy to use, windows and sheets are good, and wizards are very simple to go through
• Very quickly learn time to use, design and export
• Can do a simple job, or get to more complex tasks
• Configuration of the application is easy, straightforward
• CakePHP validation made a little easier to understand
• Customization of associations, entities and fields
• Color coded models/modules makes it easier to distinguish separate modules, which is really good for the 3rd level normalized databases that grow in enterprise applications
• Does not require processor intensive and draining resources on a Windows machine
• Support is off the charts. The ORM Designer team really owns this product and really cares, so they provide some of the best support for the product.

Items that can be “areas of opportunity”

• There is no native support for Mac and Linux. Sure it works with Wine, but I just prefer my Mac apps to work natively with OSX instead of having to install more 3rd party software just to get some other 3rd party software running. Just my preference though
• The sheets to open projects, add projects, save, etc all seem to differ. I am more of a streamline type, if more than one “file” object sheet is needed, then make them all look the same
• Does not import existing CakePHP applications, which can cause some slow down if you start to use this tool after the application is already under way
• CakePHP validation seems to contain all options for every type of validation, and for someone who may not understand the details of all the different validation options, it can be a concern when it builds

Overall, this seems like a good tool. I am sure other people will find nuances as they start to use it more in the everyday world of developing. It seems like a good tool to use to help design databases. Even if the export is never done for the models/code in any framework/ORM, this is a great tool to use to help plan DBs out, view the relationships, associations.

To find out more information:
ORM Designer Main page
Documentation and Tutorials
ORM Designer on Twitter
ORM Designer Facebook
Blog ORM Designer

************** EDIT 06 Sep 2010 **************
From the ORM-Designer Team:
We‘re currently working on an automated import from database servers (MySQL, SQLServer and next major DB systems). This feature will enable users to easily import the model from their existing CakePHP (and other) projects.
(This is a huge one for the CakePHP community and one I am looking forward to)

Recently we added a new feature for CakePHP export, but this feature could be little hidden for new users and we want to propagate it more on our web in future. Besides the model files you can export also a DB structure to schema.php file which is useful for database migration.
More about this feature is on our blog.
(This is another huge win for the CakePHP community)