• Setting include path to a dicon file
• __set() Setter Injection
• PHP Configuration File Format dicon File
  • components Section
  • component Section
    • arg Settings
    • property Settings
    • init_method Settings
    • destroy_method Settings
    • aspect Settings
    • meta Settings
    • Miscellaneous
• Database Connection
  • Concerning DataSource
    • peardb.dicon Template
    • How to use
  • Using TxIntereceptor
  • Using SimpleDaoInterceptor (This function has been moved to S2Dao.PHP5)
    • Returning an Array
    • Returning an Object
• S2Unit
  • Examples

path attribute in an include tag in a dicon file may reference a constant by surrounding the constant name with a %

define(DICON_DIR,'/path/to/dir');   // constant definition

<components>
    <include path="%DICON_DIR%/bar.dicon"/>
</components>
Warning: only path name starting with %...% is evaluated.

Setter injection may be used with the newly introduced __set() in PHP5.

• Property is explicitly specified (property tag is specified in the dicon file)
• Sette method is not implemented by the class that is the target of injection
• Target class of injection implements __set()

• Define setter method (setMessageA)
• Implement __set()
• Implement showMessage()

Setter method for $messageB property is not defined

<?php
class HelloImpl {

    private $messageA = "";
    private $messageB = "";

    function HelloImpl() {}
    
    function setMessageA($messageA){
        $this->messageA = $messageA;	
    }

    function __set($name,$val){
        $this->$name = $val;	
    }
    
    function showMessage(){
        print "{$this->messageA} {$this->messageB} \n";
    }
}
?>

• Define a component using component tag
• Set property value of a component in property tag which is a child of a component tag

s2container.php5/src/examples/extension/uuset/uuset.dicon

<components>
    <component class="HelloImpl">
        <property name="messageA">"Hello"</property>
        <property name="messageB">"World"</property>
    </component>
</components>

• Create S2Container by invoking S2ContainerFactory#create($path)
• Get component from the S2Container by invoking getComponent()
• Invoke on the method in the acquired component

s2container.php5/src/examples/extension/uuset/uusetClient.php

<?php
require_once(dirname(__FILE__) . '/uuset.inc.php');
$PATH = EXAMPLE_DIR . "/extension/uuset/uuset.dicon";
$container = S2ContainerFactory::create($PATH);
$hello = $container->getComponent('HelloImpl');
$hello->showMessage();
?>

Value of a property tag should be outputted as below:

% php uusetClient.php
Hello World
%

dicon file is written in the same format as PHP configuration file (e.g. php.ini)
There are components section and sections for each component.

[components]
namespace = "dao"
.....
.....
.....
[componentA]                ＋
class = "A"                 ｜
.....                       ｜
.....                       ｜  component selection
[componentB]                ｜
.....                       ｜
.....                       ｜
.....                       ▽

components section has 3 configuration items. If it is not necessary to specifgy configuration values in a components section, components section may be omitted.

[components]
namespace = "dao"
include{0} = "/path/to/aaa.dicon"
include{1} = "/path/to/bbb.dicon"
meta{0}{name} = "metaA"
meta{0}{val}  = "meta data"
・・・
・・・
・・・

Set component name in component section to a component name. If class name is omitted, class name will default to the name of the component. Following 10 items may also be set in the component section:

[hello]
class = "Hello"
instance = "singleton"
autobinding = "auto"

arg{0}{val} = "hello world"
arg{1}{ref} = "bye"

property{0}{name} = "message"
property{0}{val} = "hello world 2 !!"

init_method{0}{name} = "initialize"
init_method{0}{arg{0}{val}} = "-1"

aspect{0}{pointcut} = "showMessage"
aspect{0}{exp} = "new TraceInterceptor()"

meta{0}{name} = "helloMeta"
meta{0}{ref} = "bye"

[bye]
class = "Bye"

...
...
...

[hello]
class=Hello
arg{0}{val} = "hello world"
arg{1}{ref} = bye
arg{2}{exp} = "array('hello','world','!!')"

[bye]
class = Bye

[hello]
class=Hello

property{0}{name} = "messageA"     --- set value "Hello" to messageA property
property{0}{val} = "Hello"
property{1}{name} = "messageB"     --- set "World" to messageB property
property{1}{val} = "World"
property{2}{name} = "bye"          --- set component "bye" to bye property
property{2}{ref} = "bye"

[bye]
class = Bye

[hello]
class=Hello

init_method{0}{name} = "showMessage"
init_method{0}{arg{0}{val}} = "Hello"
init_method{0}{arg{1}{val}} = "World"

init_method{1}{exp} = "$component->initialize()"

Similar to setting init_method

[hello]
class=Hello

aspect{0}{pointcut} = "showMessage"
aspect{0}{ref} = "trace"

[trace]
class = "TraceInterceptor"

meta{index}{name} sets meta name、meta{index}{val} sets a value

[components]
meta{0}{name} = "metaA"
meta{0}{val} = "5"
meta{1}{name} = "metaB"
meta{1}{ref} = hello
meta{2}{name} = "metaC"
meta{2}{exp} = "array('a','b','c')"

[hello]
class = HelloImpl

• Single and double quoation may not be used in an item name (e.g. arg{0}{'val'}、arg{0}{"val"})
• If a value is surrounded by double quotes, line returns becomes effective
• index starts from value 0
• Both XML format and PHP configuration format dicon configuration files for examples under folder s2container.php5/src/examples/ are included.

Include database connection framework using extension

Following example uses the sample database table defined below. SQL script file (demo.sql) to create these tables is located in s2container.php5/src/s2container.php5/org/seasar/extension/db/sql/ folder.

dicon configuration files containing native database connection configuration (DataSource) for MySQL, PostgreSQL, Pear DB, and ADOdb are available in the s2container.php5/src/s2container.php5/org/seasar/extension/db/ folder.

Following is the content of peardb.dicon template. Properties of dataSource component should be set to values to properly connect to the database. If dsn properly is set, it will take precedence and be used.

XML format peardb.dicon file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR//DTD S2Container//EN"
"components21.dtd">
<components namespace="peardb">
    <component name="dataSource" class="PearDBDataSource">
        <property name="dsn">                                  
            "mysql://hoge:hoge@localhost:3306/s2container"       
        </property>                                            
    </component>

    <component class="PearDBSqlHandler"/>
    <component name="dbtx" class="PearDBTxInterceptor"/>
    <component name="dao" class="SimpleDaoInterceptor"/>
    <component class="DaoMetaDataFactoryImpl"/>
    <component name="session" class="DBSessionImpl"/>
</components>

INI format peardb.ini file

[components]
namespace="peardb"

[dataSource]
class="PearDBDataSource"

property{0}{name}="dsn"                                         
property{0}{val} ="mysql://hoge:hoge@localhost:3306/s2container"

[PearDBSqlHandler]

[dbtx]
class="PearDBTxInterceptor"

[dao]
class="SimpleDaoInterceptor"

[DaoMetaDataFactoryImpl]

[session]
class="DBSessionImpl"

In this example, DEPT table is queries with a key passed by an argument. A DOA to return the result is implemented.
Files in this example is available in the s2container.php5/src/examples/extension/db/ folder.

Interface Definition

• Define DeptDao interface
• Define findDeptByDeptno method that will search by DEPTNO

<?php
interface DeptDao {
    function findDeptByDeptno($deptno);
}
?>

Create execution class

• Create DeptDaoImpl class that implements DeptDao interface
• Pass DataSource as a constructor argument
• Implemnet findDeptByDeptno method. Obtain database connection using DataSource.

<?php
class DeptDaoImpl implements DeptDao {

    private $dataSource;

    function DeptDaoImpl(DataSource $dataSource) {
        $this->dataSource = $dataSource;
    }
    
    function findDeptByDeptno($deptno){
        $db = $this->dataSource->getConnection();
        $result = $db->query("select * from dept where deptno = '{$deptno}';"); 
        $row = $result->fetchRow();
        $this->dataSource->disconnect($db);
        return $row;
    }
}
?>

Create dicon file

Create a dicon file to use Pear DB. Specify peardb.dicon in an include tag.

XML format deptDao.dicon

<components>
    <include path="%S2CONTAINER_PHP5%/org/seasar/extension/db/peardb.dicon"/>
    <component name ="deptDao" class="DeptDaoImpl"/>
</components>

INI format deptDao.ini

[components]
include{0} = "%S2CONTAINER_PHP5%/org/seasar/extension/db/peardb.dicon"

[deptDao]
class="DeptDaoImpl"

Create execution script

• Create a container using configuration file deptDao.dicon
• Get deptDao component from the container
• Invoke findDeptByDeptno to query on DEPTNO=10

dataSourceClient.php

<?php
require_once(dirname(__FILE__) . '/db.inc.php');
$PATH = EXAMPLE_DIR . "/extension/db/deptDao.dicon";
//$PATH = EXAMPLE_DIR . "/extension/db/deptDao.ini";

$container = S2ContainerFactory::create($PATH);
$dao = $container->getComponent('deptDao');
$result = $dao->findDeptByDeptno(10);

print_r($result);
?>

Result

% php dataSourceClient.php
Array
(
    [0] => 10
    [1] => ACCOUNTING
    [2] => NEW YORK
    [3] => 0
)
%

Use TxInterceptor to manage database transaction.
Files in this example is available in the s2container.php5/src/examples/extension/db/ folder.

Interface Definition

• Define DeptDao interface
• Define findDeptByDeptno method that inquires DEPTNO.

<?php
interface DeptDao {
    function findDeptByDeptno($deptno);
}
?>

Create execution class

• Create TxDeptDaoImpl class that implements DeptDao interface
• Set a constructor to take DBSession as an argument
• Implement findDeptByDeptno method. Obtain database connection from DBSession

<?php
class TxDeptDaoImpl implements DeptDao {

    private $session;

    function TxDeptDaoImpl(DBSession $session) {
        $this->session = $session;
    }
    
    function findDeptByDeptno($deptno){
        $db = $this->session->getConnection();
        $result = $db->query("select * from dept where deptno = '{$deptno}';"); 
        $row = $result->fetchRow();

        return $row;
    }
}
?>

Creating a dicon file

Use a dicon file for Pear DB. Specify peardb.dicon in an include tag. Aspect dbtx(PearDBTxInterceptor) to the findDeptByDeptno method.

XML format txDeptDao.dicon

<components>
    <include path="%S2CONTAINER_PHP5%/org/seasar/extension/db/peardb.dicon"/>
    <component name ="deptDao" class="TxDeptDaoImpl">
        <aspect pointcut="findDeptByDeptno">
            dbtx
        </aspect>
    </component>
</components>

INI format txDeptDao.ini

[components]
include{0} = "%S2CONTAINER_PHP5%/org/seasar/extension/db/peardb.dicon"

[deptDao]
class="TxDeptDaoImpl"
aspect{0}{pointcut} = "findDeptByDeptno"
aspect{0}{ref} = "dbtx"

Create execution script

• Create a container using configuration file txDeptDao.dicon
• Get deptDao component from the container
• Invoke findDeptByDeptno to query on DEPTNO=10

txClient.php

<?php
require_once(dirname(__FILE__) . '/db.inc.php');

$PATH = EXAMPLE_DIR . "/extension/db/txDeptDao.dicon";
//$PATH = EXAMPLE_DIR . "/extension/db/txDeptDao.ini";

$container = S2ContainerFactory::create($PATH);
$dao = $container->getComponent('deptDao');
$result = $dao->findDeptByDeptno(10);
print_r($result);
?>

Result

% php dataSourceClient.php
Array
(
    [0] => 10
    [1] => ACCOUNTING
    [2] => NEW YORK
    [3] => 0
)
%

Using SimpleDaoInterceptor (This function has moved to S2Dao.PHP5)

Define interfaces and connect to a database using SQL statement
Files in this example is available in the s2container.php5/src/examples/extension/db/ folder.

Retrieve result of database query in an array

Interface definition

• Define DeptDao interface
• Define findDeptByDeptno method to query by DEPTNO
• Set SQL statement using constant annotation (QUERY)

<?php
interface DeptDao {
    const findDeptByDeptno_QUERY = 'select * from dept where deptno = \'{$deptno}\'';
    //const findDeptByDeptno_FILE = '%PATH_PREFIX%/path/to/sql/file';
                                                  // specify external SQL file
    function findDeptByDeptno($deptno);
}
?>

There are 3 methods to specify SQL statement that is executed by a method:
- write SQL statement directly in constant annotation : method name_QUERY (above sample)
- Reference external file in constant annotation : method name_FILE (path of the external file is specified between %...%)
- Create file with SQL statements that is named interface name_method name.sql in the same folder as the interface definition file.

Create implementation class

There isn't any implementation class in this example

Create a dicon file

Create a dicon file for to connect with ADOdb。include adodb.dicon file by specifying in an include tag. Apply aspect dao(SimpleDaoInterceptor) to findDeptByDeptno method.

XML format simpleDeptDao.dicon

<components>
    <include path="%S2CONTAINER_PHP5%/org/seasar/extension/db/adodb.dicon"/>
    <component name ="deptDao" class="DeptDao">
        <aspect pointcut="findDeptByDeptno">
            dao
        </aspect>
    </component>
</components>

INI format simpleDeptDao.ini

[components]
include{0} = "%S2CONTAINER_PHP5%/org/seasar/extension/db/adodb.dicon"

[deptDao]
class="DeptDao"
aspect{0}{pointcut} = "findDeptByDeptno"
aspect{0}{ref} = dao

Create execution script

• Create a container using configuration file simpleDeptDao.dicon
• Get deptDao component from the container
• Invoke method findDeptByDeptno with DEPTNO(10)

simpleClient.php

<?php
require_once(dirname(__FILE__) . '/db.inc.php');
$PATH = EXAMPLE_DIR . "/extension/db/simpleDeptDao.dicon";
//$PATH = EXAMPLE_DIR . "/extension/db/simpleDeptDao.ini";

$container = S2ContainerFactory::create($PATH);
$dao = $container->getComponent('deptDao');
$result = $dao->findDeptByDeptno(10);
print_r($result);
?>

Result

% php simpleClient.php
Array
(
    [0] => Array
        (
            [0] => 10
            [1] => ACCOUNTING
            [2] => NEW YORK
            [3] => 0
        )
)
%

Get property value as an object referencing result from database query

Interface definition

• Define interface BeanDeptDao
• Define findDeptByDeptno method that searches by column DEPTNO
• Set DTO(Data Transfer Object) using constant annotation (BEAN)

<?php
interface BeanDeptDao {
    const BEAN = "DeptDto";
    function findDeptByDeptno($deptno);
}
?>

There are 3 methods to specify a SQL statement:
- write SQL statement directly in constant annotation : method name_QUERY
- Reference external file in constant annotation : method name_FILE (path of the external file is specified between %...%)
- Create file with SQL statements that is named interface name_method name.sql in the same folder as the interface definition file.

This example uses the third method and creates BeanDeptDao_findDeptByDeptno.sql file containing SQL statement to be executed by findDeptByDeptno and places this file in the same folder as BeanDeptDao interface definition file.

select * from dept where deptno = '{$deptno}'

Create execution class

Create DTO specified by constant annotation (BEAN)

<?php
class DeptDto {
    private $deptno;
    private $dname;
    
    function DeptDto() {}
    
    function setDeptno($deptno){
    	$this->deptno = $deptno;
    }
    function getDeptno(){
        return $this->deptno;	
    }
    
    function setDname($dname){
    	$this->dname = $dname;
    }
    function getDname(){
        return $this->dname;
    }

    function __toString(){
    	$str = "deptno = " . $this->deptno . ", dname = " . $this->dname;
        return $str;	
    }
}
?>

Set DTO property specified by constant annotation (BEAN) to column name, DTO property, and setter method name that are result of a database query.

Create dicon file

Create a dicon file for ADOdb. include adodb.dicon by specifying the name in the include tag. Apply aspect dao(SimpleDaoInterceptor) to findDeptByDeptno method. (When using Pear DB, include peardb.dicon file instead.)

XML format simpleDeptDao.dicon

<components>
    <include path="%S2CONTAINER_PHP5%/org/seasar/extension/db/adodb.dicon"/>
    <component name ="beanDeptDao" class="BeanDeptDao">
        <aspect pointcut="findDeptByDeptno">
            dao
        </aspect>
    </component>
</components>

INI format simpleDeptDao.ini

[components]
include{0} = "%S2CONTAINER_PHP5%/org/seasar/extension/db/adodb.dicon"

[beanDeptDao]
class="BeanDeptDao"
aspect{0}{pointcut} = "findDeptByDeptno"
aspect{0}{ref} = dao

Create execution script

• Create a container using configuration file simpleDeptDao.dicon
• Get component beanDeptDao from the container
• Invoke findDeptByDeptno method with setting DEPTNO(10)

simpleBeanClient.php

<?php
require_once(dirname(__FILE__) . '/db.inc.php');
//$PATH = EXAMPLE_DIR . "/extension/db/simpleDeptDao.dicon";
$PATH = EXAMPLE_DIR . "/extension/db/simpleDeptDao.ini";

$container = S2ContainerFactory::create($PATH);
$dao = $container->getComponent('beanDeptDao');
$result = $dao->findDeptByDeptno(10);
print_r($result);
?>

Result

% php simpleBeanClient.php
Array
(
    [0] => DeptDto Object
        (
            [deptno:private] => 10
            [dname:private] => ACCOUNTING
        )

)
%

Values are set to properties deptno and dname in DeptDto class. Columns LOC and VERSIONNO in the query result are thrown away.

To make testing easier, S2 has a testing framework which is an extension of PHPUnit, PHPUnit2, and SimpleTest. Followings are its major features:

• Create S2Container automatically on each test method (testXxx)
• register(), getComponent(), include() for S2Container are made to available
• If there is a public field in TestCase and if there is a component in a S2Container with the same name as the field name, it is automatically set
• After the test method ends, all automatically set variables are set to null
• If a test method (testXxx) is defined that corresponds to setUpXxx() and tearDownXxx(), it is invoked after setUp() and before testDown(). Initialization and clean up processes may be specified here.

Example

Use S2PHPUnit2TestCase that extends Pear PHPUnit2.
Files in this example is available in the s2container.php5/src/examples/extension/unit/ folder.

Target of the test

s2container.php5/src/examples/extension/unit/src/foo/FooLogic.class.php

<?php
class FooLogic {

    function FooLogic() {
    }
    
    function showYear(){
    	return 2005;
    }
}
?>

dicon file

s2container.php5/src/examples/extension/unit/src/foo/foo.ini

[logic]
class = FooLogic

Test class

s2container.php5/src/examples/extension/unit/test/phpunit2/foo/FooLogicTest.class.php

<?php
class FooLogicTest extends S2PHPUnit2TestCase {

    public $logic;   //--- if there is a definition of component named "logic"
                     //--- in a dicon file, it is set
    
    function __construct($name) {
    	parent::__construct($name);
    }

    function setUp(){
        $this->includeDicon(UNIT_EXAMPLE . "/src/foo/foo.ini");   //--- include dicon file
    }

    function testShowYear(){
        $year = $this->logic->showYear();
        $this->assertEquals($year , 2005);	
    }
}
?>

s2container.php5/src/examples/extension/unit/test/phpunit2/foo/FooAllTest.class.php

<?php
class FooAllTest {

    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
    
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite();
        $suite->addTestSuite('FooLogicTest');
        return $suite;  
    }
}
?>

Execution script

s2container.php5/src/examples/extension/unit/test/phpunit2/foo/fooTests.php

<?php
define('PHPUnit2_MAIN_METHOD', 'FooAllTest::main()');
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';

FooAllTest::main();
?>

Result

% php allTests.php

TEST : FooLogicTest::testShowYear
------------------------------------

.

Time: 0.368033

OK (1 test)
%

Similar examples using Pear PHPUnit and SimpleTest are available in the s2container.php5/src/examples/extension/unit/test/ folder.