Contents:
  Introduction
  XML Configurations and Bindings
  Accessing a PlugIn component inside the Framework
  Preinstalled PlugIns
  Appendix A: The php.MVC PlugIn Architecture

PlugIns provide a means of loading and accessing external PHP libraries or modules within php.MVC without the need for hard-coded coupling of the external code to the php.MVC classes.

The PlugIn components are configured via plug-in elements in the php.MVC applications phpmvc-config.xml configuration file. Within each plug-in element, the element className attribute specifies the PlugIn class to load, and the key attribute specifies the unique PlugIn key string used to reference the PlugIn module. Properties on the PlugIn object can be configured using one or more set-property elements.

<?xml version="1.0" encoding="ISO-8859-1" ?>

<!DOCTYPE phpmvc-config PUBLIC "-//PHPMVC//DTD PHPMVC Configuration 1.0//EN"
          "./phpmvc-config_1_1.dtd">

<phpmvc-config>

  <!-- ========== Form Bean Definitions =================================== -->

  <form-beans>
1   <form-bean name="demoPage" 
               type="DemoPageForm"/>
  </form-beans>

  <!-- ========== Action Mapping Definitions ============================== -->

  <action-mappings>
2   <action    path = "demoPage"
               type = "DemoPageAction"
               name = "demoPage"
              scope = "request"
           validate = "true"> 
      <forward name="success" path="smartyIndex.tpl"/>
      <forward name="failure" path="demoPageError.tpl"/>
    </action>
  </action-mappings>

  <!-- ========== PlugIns ================================================= -->
  
  <!-- Load our PlugIn class here (case sensitive class name)               -->
  <!-- Note: The attribute names must match the class methods               -->
  <!-- Eg: 'key' maps to 'setKey(..)'                                       -->
3 <plug-in 
4          className="SmartyPlugInDriver"
5                key="SMARTY_PLUGIN">
    <!-- And set some custom propertied on the PlugIn class                 -->
    <!-- Note: The property name must match the class variable name exactly -->
6   <set-property property="caching"       value="1"/>
7   <set-property property="force_compile" value="False"/>
8   <set-property property="template_dir"  value="C:/WWW/phpmvc/Smarty/WEB-INF/tpl/"/>
  </plug-in>
 
</phpmvc-config>
   

The XML configuration file listed above is a standard php.MVC configuration file, with the addition of the plug-in element listed at the bottom. The <form-bean ...> element(1) specifies the ActionForm class associated with the listed <action ...> element(2). Note that the <form-bean > element is mapped to the <action > element by the name="demoPage" attributes in each element.

The <plug-in ...> element(3) is responsible for loading and configuring external PHP modules or libraries. A php.MVC configuration file can have one or more <plug-in ...> elements. Each <plug-in ...> element must specify a PlugIn class to load(4). This PlugIn class will usually be a driver or "wrapper" class that is the interface between php.MVC and the external module. In this example we load the supplied SmartyPlugInDriver driver class with the className="SmartyPlugInDriver" attribute.

Each <plug-in ...> element can contain one or more <set-property ...> elements(6). A <set-property ...> element consists of property attribute and matching value attribute. In the example above we are setting some class variables on the Smarty template engine class. The property="template_dir" attribute(8) maps to the Smarty->template_dir class variable, and the corresponding value="C:/WWW/phpmvc/Smarty/WEB-INF/tpl/" attribute specifies the value of this class variable.

// DemoPageForm.php
class DemoPageForm extends ActionForm {

   function reset($mapping, $request) { ; }

1  function validate(&$mapping, &$request) {

      // Access the Smarty PlugIn instance
      // Note the reference "=&"
2     $plugInKey = 'SMARTY_PLUGIN';
3     $smarty =& $this->actionServer->getPlugIn($plugInKey);
4     if($smarty == NULL) {
         echo 'No PlugIn found matching key: '.$plugInKey."<br>\n;
      }

      // Set some Smarty template variables	
5     $smarty->assign("FirstName",array("John","Mary","James","Henry"));
      $smarty->assign("LastName",array("Doe","Smith","Johnson","Case"));

     return;

   } 
}

   

In this example we are accessing the PlugIn in out ActionForm class DemoPageForm. This Form class was specified in the XML configuration file (above) as the ActionForm class to handle form processing for the demoPage path.

The validate(...) method (1) is called as per our XML binding: (validate = "true").

   <action     path = "demoPage"
               type = "DemoPageAction"
               name = "demoPage"
              scope = "request"
           validate = "true"> 
           ...
  </action>

Next we specify our PlugIn key $plugInKey = 'SMARTY_PLUGIN' (2), as per the configuration plug-in section above.

   <plug-in 
      className="SmartyPlugInDriver"
            key="SMARTY_PLUGIN">
            ...
   </plug-in>

Finally we can perform some operation on the PlugIn instance. In this example we assign two Smarty template variable(5).

The PlugIn instance can be accessed from any class that contains a reference to the ActionServer class. For example an Action derived class (class MyPageAction extends Action), and an ActionDispatcher derived class ( class MyActionDispatcher extends ActionDispatcher).

To access the PlugIn instance from our business classes we could pass a PlugIn reference to the business class constructor. For example:

   $plugInKey = 'SMARTY_PLUGIN';
   $smarty =& $this->actionServer->getPlugIn($plugInKey);
   $myBusinessClass = new MyBusinessClass($smarty);
   $myBusinessClass->makeMeRich(...);

The php.MVC framework currently ships with the following PlugIn drivers:

For a complete example of using the php.MVC PlugIn mechanism please look at the "Using the Smarty Compiling Template Engine in php.MVC" user guide in the documentation directory on the phpmvc.net web site.

To enable an existing external PHP class library to be used as a php.MVC PlugIn, an interface or driver class will usually be required.

The diagram above shows an overview of how external class libraries can be integrated into the php.MVC framework using the PlugIn architecture.

An abstract PlugIn class APlugIn is provided by the php.MVC framework. PlugIn driver classes should extend this abstract class and override the abstract methods as required by the specific external class library.

A example PlugIn driver can be found in the WEB-INF/classes/phpmvc/plugins/SmartyPlugInDriver class.