{"id":12148,"date":"2010-02-17T20:52:31","date_gmt":"2010-02-17T18:52:31","guid":{"rendered":"https:\/\/mamchenkov.net\/wordpress\/?p=12148"},"modified":"2010-02-17T20:52:31","modified_gmt":"2010-02-17T18:52:31","slug":"cakephp-building-factories-with-models-and-behaviors","status":"publish","type":"post","link":"https:\/\/mamchenkov.net\/wordpress\/2010\/02\/17\/cakephp-building-factories-with-models-and-behaviors\/","title":{"rendered":"CakePHP : Building factories with models and behaviors"},"content":{"rendered":"\n

CakePHP<\/a> is a wonderful framework. \u00a0 Recently I proved it to myself once again (not that I need much of that proof anyway). \u00a0The problem that we had at work was a whole lot of code in once place and no obvious way of how to break that code into smaller, more manageable pieces. \u00a0MVC is a fine architecture, but it wasn’t obvious to me how to apply it to larger projects.<\/p>\n

In our particular case, we happen to have several data types, which are very similar to each other, yet should be treated differently. \u00a0Two examples are:<\/p>\n

    \n
  1. Client account registrations. \u00a0 Our application supports different types of accounts and each type has its own processing, forms, validations, etc. \u00a0However, each type of account is still an account registration.<\/li>\n
  2. Financial transactions. \u00a0Our clients can send us money via a number of payment methods – credit cards, PayPal, bank wires, etc. \u00a0Each type of the transaction has its own processing, forms, validations, etc. \u00a0However, each type of the transaction is still a financial transaction of money coming in.<\/li>\n<\/ol>\n

    Having a separate model for each type of account or for each type of transaction seems\u00a0excessive. \u00a0There are differences between each type, but not enough to justify a separate model. \u00a0Having a single model though means that it’ll continue to grow with each and every difference that needs to be coded in. \u00a0Something like a class factory design pattern would solve the problem nicely, but the question is how to fit it into an existing MVC architecture. \u00a0Read the rest of this post for a demonstration.<\/p>\n

    <\/p>\n

    CakePHP supports a notion of behaviors, which are a sort of modifier for a model. \u00a0Things that bloat a model can easily be moved out into a behavior. \u00a0So, for each type of our financial transaction we can create a separate behavior. \u00a0That would help, but how would we keep behaviors consistent and how can we share common code between them? \u00a0With a base model. \u00a0And furthermore, if we want to make sure that each behavior actually implements certain methods, we can force an interface constraint upon the behavior. \u00a0Enough of this blah blah blah. \u00a0Here comes the code.<\/p>\n

    First, let’s create a table for our transactions with some sample data.<\/p>\n

    \r\nDROP TABLE transactions;\r\nCREATE TABLE transactions (\r\n\tid INTEGER UNIQUE AUTO_INCREMENT PRIMARY KEY,\r\n\tmethod CHAR(2) NOT NULL,\r\n\tamount DECIMAL(10,2) NOT NULL DEFAULT 0,\r\n\tcurrency CHAR(3) NOT NULL);\r\nINSERT INTO transactions SET method='CC', amount=100, currency='USD';\r\nINSERT INTO transactions SET method='BW', amount=1500, currency='GBP';\r\nINSERT INTO transactions SET method='PP', amount=21.50, currency='EUR';\r\n<\/pre>\n
    Needless to say, I am trying to simplify things, hence such a short table definition. \u00a0Method here is a two character description of the payment method (“CC” for credit card, “PP” for PayPal, “BW” for bank wire, etc).<\/p>\n
    Second, let’s create a couple of views, to get them out of the way.  One to add a transaction (in app\/views\/transactions\/add.ctp) with the following content:<\/p>\n
    \r\n<h1>Add transaction<\/h1>\r\n<?php\r\necho $form->create('Transaction');\r\necho $form->input('method');\r\necho $form->input('amount');\r\necho $form->input('currency');\r\necho $form->end('Save Transaction');\r\n?>\r\n<\/pre>\n
    And another one to view all transactions (in app\/views\/transactions\/index.ctp) with the following content:<\/p>\n
    \r\n<h1>Transactions<\/h1>\r\n<a href="\/transactions\/add">Add transaction<\/a>\r\n<table>\r\n\t<tr>\r\n\t\t<th>ID<\/th>\r\n\t\t<th>method<\/th>\r\n\t\t<th>amount<\/th>\r\n\t\t<th>currency<\/th>\r\n\t<\/tr>\r\n\t<?php\r\n\t\tforeach ($transactions as $transaction) {\r\n\t\t\techo "<tr>";\t\r\n\t\t\techo "<td>{$transaction['Transaction']['id']}<\/td>";\r\n\t\t\techo "<td>{$transaction['Transaction']['method']}<\/td>";\r\n\t\t\techo "<td>{$transaction['Transaction']['amount']}<\/td>";\r\n\t\t\techo "<td>{$transaction['Transaction']['currency']}<\/td>";\r\n\t\t\techo "<\/tr>";\t\r\n\t\t}\r\n\t?>\r\n<\/table>\r\n<\/pre>\n
    Nothing fancy, just good enough for us to see what we have in the database.<\/p>\n
    The next simplest thing is the transactions controller.  Again, nothing fancy in here, just two actions for the above views.  Here is the code for app\/controllers\/transactions_controller.php :<\/p>\n
    \r\n<?php\r\nclass TransactionsController extends AppController {\r\n\tvar $name = 'Transactions';\r\n\r\n\tfunction index() {\r\n\t\t$this->set('transactions', $this->Transaction->find('all'));\r\n\t}\r\n\r\n\tfunction add() {\r\n\t\tif (!empty($this->data)) {\r\n\t\t\tif ($this->Transaction->save($this->data)) {\r\n\t\t\t\t$processed = $this->Transaction->process();\r\n\t\t\t\tif ($processed) {\r\n\t\t\t\t\t$this->Session->setFlash("Your transaction has been saved and processed ($processed)");\r\n\t\t\t\t}\r\n\t\t\t\telse {\r\n\t\t\t\t\t$this->Session->setFlash("Your transaction has been saved but failed to process ($processed)");\r\n\t\t\t\t}\r\n\t\t\t\t$this->redirect(array('action'=>'index'));\r\n\t\t\t}\r\n\t\t}\r\n\t}\r\n}\r\n<\/pre>\n
    Simplest possible listing of items in the database.  As for the addition of the new ones, we want to validate the form submission, save data in the database, and then, if everything was OK, call a process() method, so that an appropriate processing logic is triggered.  For the simplicity of the example, our transaction processing logic will just return a string – a different one for each transaction type.  And we’ll display that string in the flash message.<\/p>\n
    Now, for the main course – transaction model (app\/models\/transaction.php):<\/p>\n
    \r\n<?php\r\nclass Transaction extends AppModel {\r\n\tconst BEHAVIOR_PREFIX = 'Trnx';\r\n\r\n\tvar $allowedMethods = array('CC','PP','BW');\r\n\tvar $allowedCurrencies = array('USD','EUR','GBP','CHF','JPY');\r\n\r\n\tvar $name = 'Transaction';\r\n\tvar $validate =  array(\r\n\t\t\t\t\t\t'method' => array(\r\n\t\t\t\t\t\t\t\t\t\t'notEmpty' => array(\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'rule' => 'notEmpty',\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t\t\t\t\t'allowedMethod' => array(\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'rule' => array('checkAllowedMethod'),\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'message' => 'This method is not allowed',\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t'amount' => array(\r\n\t\t\t\t\t\t\t\t\t\t'notEmpty' => array(\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'rule' => 'notEmpty',\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t\t\t\t\t'allowedAmount' => array(\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'rule' => array('checkAllowedAmount'),\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'message' => 'This amount is invalid',\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t'currency' => array(\r\n\t\t\t\t\t\t\t\t\t\t'notEmpty' => array(\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'rule' => 'notEmpty',\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t\t\t\t\t\t'allowedCurrency' => array(\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'rule' => array('checkAllowedCurrency'),\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t'message' => 'This currency is not allowed',\r\n\t\t\t\t\t\t\t\t\t\t\t\t\t),\r\n\r\n\t\t\t\t\t\t\t\t\t),\r\n\t\t\t\t\t);\r\n\r\n\tfunction beforeValidate() {\r\n\t\t$method = '';\r\n\t\tif (!empty($this->data['Transaction']['method'])) {\r\n\t\t\t$method = $this->data['Transaction']['method'];\r\n\t\t}\r\n\t\tif (in_array($method, $this->allowedMethods)) {\r\n\t\t\t$this->pushBehavior($method);\r\n\t\t}\r\n\t\treturn true;\r\n\t}\r\n\r\n\tfunction nameBehavior($method) {\r\n\t\treturn self::BEHAVIOR_PREFIX . strtolower($method);\r\n\t}\r\n\r\n\tfunction pushBehavior($method) {\r\n\t\t$behavior = $this->nameBehavior($method);\r\n\t\t$this->Behaviors->attach($behavior);\r\n\t\t$this->Behaviors->enable($behavior);\r\n\t}\r\n\r\n\tfunction popBehavior($method) {\r\n\t\t$behavior = $this->nameBehavior($method);\r\n\t\t$this->Behaviors->disable($behavior);\r\n\t\t$this->Behaviors->detach($behavior);\r\n\t}\r\n\r\n\tfunction checkAllowedMethod($check) {\r\n\t\t$allowed =  in_array($check['method'], $this->allowedMethods);\r\n\t\treturn $allowed;\r\n\t}\r\n\r\n\tfunction checkAllowedAmount($check) {\r\n\t\t$result = false;\r\n\r\n\t\tif (method_exists($this, 'get_max_amount')) {\r\n\t\t\t$maxAmount = $this->get_max_amount();\r\n\t\t\tdebug("maxAmount = $maxAmount");\r\n\t\t\tif (is_numeric($check['amount']) && $check['amount'] > 0 && $check['amount'] <= $maxAmount) {\r\n\t\t\t\t$result = true;\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t\treturn $result;\r\n\t}\r\n\r\n\tfunction checkAllowedCurrency($check) {\r\n\t\treturn in_array($check['currency'], $this->allowedCurrencies);\r\n\t}\r\n}\r\n\r\n?>\r\n<\/pre>\n
    So, what do we have here?  Let’s take a closer look.<\/p>\n
      \n
    1. Class constant BEHAVIOR_PREFIX.  We’ll use it to help us with the naming convention.  Nothing more.<\/li>\n
    2. Arrays with valid options.  The simplest possible data for the validation process.<\/li>\n
    3. Validation rules.  We’ll just check that specified transaction currency and transaction methods are sensible, and that transaction amount is between zero and maximum allowed amount.  Here is a tricky bit: we want a different maximum amount limit for each different payment method.  Stay tuned.<\/li>\n
    4. beforeValidate() . That’s an important bit.  CakePHP will call this method before the form validation kicks in.  Which will kick in before the data is actually saved to the database.  And that’s precisely the place where we want to identify transaction method and load an appropriate behavior.  Note that this method should always return true.<\/li>\n
    5. nameBehavior() . That’s a little helper method I use to keep construct the name of the behavior from a specified parameter, in this case – a transaction method.<\/li>\n
    6. pushBehavior() and popBehavior() are two methods which, for the lack of better naming, attach\/enable and disable\/detach a specific behavior to\/from the model.  While pushBehavior() is called automatically from beforeValidate(), I can always use these methods manually from other places in the model or even from the controller.  Handy.<\/li>\n
    7. checkAllowedMethod() and checkAllowedCurrency() are two simple validation checks that compare a given value against a valid items list.<\/li>\n
    8. checkAllowedAmount() – that’s the part where we check that specified amount is within appropriate limits.  To get a higher limit we call getMaxAmount() method, which is common for all transaction types (stay tuned for definition).  That method returns a number, which is different for each type of the transaction.  And we add some extra logic to check if getmaxAmount() method actually exists, because if an invalid transaction method will be specified, then beforeValidation() will fail to load any sensible behavior and we’ll get a PHP complain here, when it will try to call an undefined method.<\/li>\n<\/ol>\n
      Now, let’s see the behaviors.  Behaviors should extend the ModelBehavior class of CakePHP and they should have a setup() method that will be called when they are loaded.  But since we need a number of behaviors that behave the same way, what we do instead is create a base transaction behavior, which the rest of the behaviors extend.  Here is the base behavior as defined in app\/models\/behaviors\/trnxbase.php :<\/p>\n
      \r\n<?php\r\nrequire_once dirname(__FILE__) . DS . 'interfaces' . DS . 'transaction.php';\r\n\r\nabstract class TrnxbaseBehavior extends ModelBehavior implements iTransaction {\r\n\r\n\tvar $settings;\r\n\tvar $max_amount = 500;\r\n\r\n\tfunction setup(&$Model, $settings) {\r\n\t\tif (!isset($this->settings[$Model->alias])) {\r\n\t\t\t$this->settings[$Model->alias] = array();\r\n\t\t}\r\n\t\t$this->settings[$Model->alias] = array_merge($this->settings[$Model->alias], (array) $settings);\r\n\t}\r\n\r\n\tfunction getMaxAmount(&$Model) {\r\n\t\treturn $this->max_amount;\r\n\t}\r\n}\r\n?>\r\n<\/pre>\n
      Important things to see here:<\/p>\n
        \n
      1. We use an abstract class here.  We won’t have a “base” transaction method and nobody should really instantiate the TrnxbaseBehavior class.<\/li>\n
      2. We also implement an iTransaction interface, which we also require.  This is a very convenient bit which helps us to make sure that all behaviors that extend the base also implement all required methods.<\/li>\n
      3. We set a default value for our maximum amount validation.  This value will be used in case one of the behaviors will not override it.<\/li>\n
      4. setup() method is common to all transaction behaviors, so we put it here.<\/li>\n
      5. getMaxAmount() is common to all transactions as well.<\/li>\n<\/ol>\n
        Before I forget it, here is the contents of the app\/models\/behaviors\/interfaces\/transaction.php – we only require each transaction behavior to define the process() method.<\/p>\n
        \r\n<?php\r\n\r\ninterface iTransaction {\r\n\tpublic function process();\r\n}\r\n?>\r\n<\/pre>\n
        So, now all we need to do is create our behaviors – one for each transaction method.  Here’s one for the credit cards (app\/models\/behaviors\/trnxcc.php):<\/p>\n
        \r\n<?php\r\nrequire_once dirname(__FILE__) . DS . 'trnxbase.php';\r\n\r\nclass TrnxccBehavior extends TrnxbaseBehavior {\r\n\r\n\tvar $max_amount = 2500;\r\n\r\n\tfunction process() {\r\n\t\treturn 'Charging the credit card';\r\n\t}\r\n}\r\n?>\r\n<\/pre>\n
        Notice how we require and extend a base transaction behavior, how we set a different limit for the maximum amount limit, and how we have to define the process() method.  If we forget to define the process() method, PHP will fail with a lot of noise.  Try it at home.<\/p>\n
        In the meantime, here is a very similar behavior for a PayPal transaction (app\/models\/behaviors\/trnxpp.php):<\/p>\n
        \r\n<?php\r\nrequire_once dirname(__FILE__) . DS . 'trnxbase.php';\r\n\r\nclass TrnxppBehavior extends TrnxbaseBehavior {\r\n\r\n\tvar $max_amount = 10000;\r\n\r\n\tfunction process() {\r\n\t\treturn 'Processing PayPal transaction';\r\n\t}\r\n}\r\n?>\r\n<\/pre>\n
        And then another one for bank wires (app\/models\/behaviors\/trnxbw.php):<\/p>\n
        \r\n<?php\r\nrequire_once dirname(__FILE__) . DS . 'trnxbase.php';\r\n\r\nclass TrnxbwBehavior extends TrnxbaseBehavior {\r\n\r\n\tvar $max_amount = 100000;\r\n\r\n\tfunction process() {\r\n\t\treturn 'Generating bank wire instructions PDF';\r\n\t}\r\n}\r\n?>\r\n<\/pre>\n
        And that’s it.  So just to review the above, here is what we get:<\/p>\n