Difference between revisions of "GOCDB/Regional Module Technical Documentation"

From EGIWiki
Jump to: navigation, search
(Writing Tests)
m (Download)
 
(91 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
== Download  ==
 
== Download  ==
  
'''LATEST VERSION: GOCDBv5''' <br>  
+
'''LATEST VERSION: GOCDBv5.6''' <br>  
 +
https://github.com/GOCDB/gocdb
  
*A packaged V5 release will also be made available for download soon.  
+
For install see:
*In the meantime, early adopters can check out the v5 src from svn:
+
https://github.com/GOCDB/gocdb/blob/master/INSTALL.md
<pre>svn checkout https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/branches/gocdb/Doctrine%20Web%20Portal
+
 
 +
<!--
 +
*Packaged V5.2: https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/tags/gocdb/GOCDB-5.2/GocDB-5.2.zip
 +
*svn v5.2:
 +
<pre>svn co https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/tags/gocdb/GOCDB-5.2
 
</pre>  
 
</pre>  
Note, if you are asked to authenticate with a client certificate as below, you can dismiss by pressing Enter  
+
*Latest dev/trunk svn:
 +
<pre>svn checkout https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/branches/gocdb/MultipleEndpointsGocDB/</pre>
 +
-->
 +
 
 +
<!--<pre>svn checkout https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/branches/gocdb/Doctrine%20Web%20Portal</pre> -->
 +
<!--Note, for svn co, if you are asked to authenticate with a client certificate as below, you can dismiss by pressing Enter  
 
<pre>Authentication realm: https://www.sysadmin.hep.ac.uk:443
 
<pre>Authentication realm: https://www.sysadmin.hep.ac.uk:443
 
Client certificate filename: &lt;ENTER to dismiss&gt;
 
Client certificate filename: &lt;ENTER to dismiss&gt;
Line 18: Line 28:
  
 
<br>  
 
<br>  
 +
-->
 +
<br>
  
<br>
+
<!--
 
+
== Prerequisites==
== Deployment  ==
 
'''<font color="red">(Under Construction - more details comming soon)</font>'''
 
 
=== System prerequisites  ===
 
=== System prerequisites  ===
  
Line 29: Line 39:
 
==== Database  ====
 
==== Database  ====
  
Version 5 of GocDB uses Doctrine ORM (Object Relational Mapping) as it's interface to the datastore. This allows GocDB to be deployed to either a Oracle, MySQL or SQLite database (Postgres comming soon).  
+
Version 5 of GocDB uses Doctrine ORM (Object Relational Mapping) as it's interface to the datastore. This allows GocDB to be deployed to either a Oracle or MySQL database (Doctrine also supports other DBs but these are untested).  
  
 
Oracle:  
 
Oracle:  
Line 44: Line 54:
 
*Required space: See MySQL install guide:http://dev.mysql.com/doc/refman/5.7/en/installing.html
 
*Required space: See MySQL install guide:http://dev.mysql.com/doc/refman/5.7/en/installing.html
  
<br>  
+
<br>
  
SQLite:
 
 
*Required database: SQLite 3.x.x or higher. SQLite is produced as an open source database and all versions are free to use.
 
*Required: See the SQLite documentation: www.sqlite.org/docs.html
 
<br>
 
 
==== Web frontend  ====
 
==== Web frontend  ====
  
Line 56: Line 61:
  
 
*'''Apache http server'''&nbsp;version 2.2 or higher.  
 
*'''Apache http server'''&nbsp;version 2.2 or higher.  
*'''PHP'''&nbsp;version 5.3 or higher (version &lt;=5.2 has some OOP related bugs).  
+
*'''PHP''' version 5.3 or higher (version &lt;=5.2 has some OOP related bugs).  
**'''PHP'''&nbsp;oci8 extension<br>
+
**If using Oracle: '''PHP oci8 extension''' and Oracle Instant client v10 or higher (downloadable from Oracle website)
*<span style="line-height: 1.5em;">a X509 host certificate for the machine</span>
+
**'''libxml2 and DOM support''' for PHP (Note: On RHEL, PHP requires the PHP XML RPM to be installed for this component to function).  
 +
**'''OpenSSL Extension''' for PHP
 +
*'''An X509 host certificate''' for the machine
  
<br>  
+
<br>
  
 
==== Optional  ====
 
==== Optional  ====
Line 72: Line 79:
 
=== Database preparation  ===
 
=== Database preparation  ===
  
GocDB v5 comes with deploy script which will setup the schema required for GocDB. The only preperation is that you have setup a database in your chosen database provider and have the user access details which are required later in the installation when configuring GocDB for deployment.&nbsp;
+
GocDB v5 comes with deploy script which will create the DB schema for GocDB (i.e. export the DDL to create the tables and sequences in the DB). The only preperation is that you have setup a database user/account in your chosen RDBMS and have the user access details which are required later in the installation when configuring GocDB for deployment.&nbsp;
  
<br>
+
Details for creating GOCDB user on specific RDBMS:
 +
* [[GOCDB/Regional_Module_Technical_Documentation/DeployOnOracle|Deploy on Oracle Details]]
 +
* [[GOCDB/Regional_Module_Technical_Documentation/DeployOnMySQL|Deploy on MySQL Details]]
  
 
=== GOCDB file system  ===
 
=== GOCDB file system  ===
Line 102: Line 111:
 
<pre>$pear install --alldeps doctrine/DoctrineORM
 
<pre>$pear install --alldeps doctrine/DoctrineORM
 
</pre>  
 
</pre>  
Verify the Doctrine installation by running "doctrine --version" on the command line:  
+
Verify the Doctrine installation by running "doctrine --version" on the command line (or doctrine.bat --version if on Win):  
 
<pre>$ doctrine --version
 
<pre>$ doctrine --version
 
Doctrine Command Line Interface version 2.3.3
 
Doctrine Command Line Interface version 2.3.3
 
</pre>  
 
</pre>  
<span style="line-height: 1.5em;">See the possible errors and troubleshooting section if you encounter errors at this point.</span>
+
[http://docs.doctrine-project.org/en/latest/ More information on Doctrine can be found here at the Doctrine2 site.]
 
 
=== Apache  ===
 
 
 
Apache http server version 2.2 or higher.
 
  
 
=== PHPUnit  ===
 
=== PHPUnit  ===
Line 122: Line 127:
 
<pre>$ phpunit --version
 
<pre>$ phpunit --version
 
PHPUnit 3.7.27 by Sebastian Bergmann.
 
PHPUnit 3.7.27 by Sebastian Bergmann.
</pre>  
+
</pre>
 +
[http://phpunit.de/manual/current/en/automating-tests.html More information on PHPUnit can be found via the PHPUnit documenation here.]
 +
 
 
== Deploying GOCDB5  ==
 
== Deploying GOCDB5  ==
  
=== Configuration of the database connection ===
+
=== Database Connection ===
 +
You should now have all the required blocks in place to deploy GOCDB V5. To Deploy the database schema to your desired database using Doctrine:
 +
* Navigate to to '<gocDBSrcHome>/lib/Doctrine' folder.
 +
* Locate the provided template file: ''bootstrap_doctrine_TEMPLATE.php''. In this file you will find three blocks of code commented out, once for each of the supported databased, SQLite, Oracle and MySQL as shown below:
 +
* '''Copy this file to''' ''bootstrap_doctrine.php'' in the same dir as the template file and modify to specify your chosen DB connection details.
 +
 
 +
<pre>
 +
Un-comment the area for your chosen database and fill in the details for your chosen database.
 +
 
 +
        ///////////////////////SQLITE CONNECTION DETAILS/////////////////////////////////////////////
 +
//      $conn = array(
 +
//         'driver' => 'pdo_sqlite',
 +
//         'path' => __DIR__ . '/db.sqlite',
 +
//      );
 +
        /////////////////////////////////////////////////////////////////////////////////////////////
 +
 
 +
 +
///////////////////////ORACLE CONNECTION DETAILS////////////////////////////////////////////
 +
// $conn = array(
 +
// 'driver' => 'oci8',
 +
// 'user' => 'docsvn',
 +
// 'password' => 'doc',
 +
// 'host' => 'localhost',
 +
// 'port' => 1521,
 +
        //              /*'service' = true,*/  //This may be needed depending on your Oracle server
 +
// 'dbname' => 'XE'
 +
// );
 +
//  // Need to explicitly set the Oracle session date format [1]
 +
//  $evm = new EventManager();
 +
//  $evm->addEventSubscriber(new OracleSessionInit(array('NLS_TIME_FORMAT' => 'HH24:MI:SS')));
 +
        /////////////////////////////////////////////////////////////////////////////////////////////
 +
 
 +
 +
///////////////////////MYSQL CONNECTION DETAILS////////////////////////////////////////////
 +
// $conn = array(
 +
// 'driver' => 'pdo_mysql',
 +
// 'user' => 'doctrine',
 +
// 'password' => 'doc',
 +
// 'host' => 'localhost',
 +
// 'dbname' => 'doctrine'
 +
//  );
 +
        /////////////////////////////////////////////////////////////////////////////////////////////
 +
</pre>
  
You should now have all the required blocks in place to deploy GOCDB V5. To Deploy the database schema to your desired database using Doctrine navigate to to gocDBSrc/lib/Doctrine/Deploy folder. In this folder you will configure the database connection details for your database. Depending on the type of database you are using open the bootstrap_doctrine.php file your database:
 
<pre>bootstrap_doctrine.php.mysql  -&gt; For MySQL databases
 
bootstrap_doctrine.php.oci    -&gt; For Oracle databases
 
bootstrap_doctrine.php.sqlite -&gt; For SQLite databases
 
</pre>
 
In the bootstrap_doctrine file complete the connection details for your database.
 
  
For Oracle:
 
<pre>$conn = array(
 
        'driver' =&gt; 'oci8',
 
        'user' =&gt; 'doctrine',
 
'password' =&gt; 'password',
 
'host' =&gt; 'localhost',
 
'port' =&gt; 1521,
 
        /*'service' = true,*/ 
 
'dbname' =&gt; 'XE'
 
);
 
# Note, you may need to add 'service' = true as commented out above depending on your Oracle server
 
</pre>
 
For MySQL:
 
<pre>$conn = array(
 
    'driver' =&gt; 'pdo_mysql',
 
    'user' =&gt; 'Doctrine',
 
    'password' =&gt; 'password',
 
    'host' =&gt; '127.0.0.1',
 
    'dbname' =&gt; 'doctrine'
 
);
 
</pre>
 
For SQLite:
 
<pre>$conn = array(
 
    'driver' =&gt; 'pdo_sqlite',
 
    'path' =&gt; __DIR__ . '/db.sqlite',
 
);
 
</pre>
 
 
Note: Doctrine can use APC caching however this is not suitable for all deployments. To disable comment out the APC configuration lines within the bootstrap_doctrine.php file:  
 
Note: Doctrine can use APC caching however this is not suitable for all deployments. To disable comment out the APC configuration lines within the bootstrap_doctrine.php file:  
 
<pre>$config-&gt;setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcCache());
 
<pre>$config-&gt;setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcCache());
 
$config-&gt;setQueryCacheImpl(new \Doctrine\Common\Cache\ApcCache());
 
$config-&gt;setQueryCacheImpl(new \Doctrine\Common\Cache\ApcCache());
</pre>  
+
</pre>
 +
 
 
=== Deploying GOCDB  ===
 
=== Deploying GOCDB  ===
  
To deploy GocDB can be deployed as a blank instance ready for use of as a sample instance with a small set of example data to demonstrate GocDB. There are three deploy scripts provided for each database supported, these can be found in the ''/lib/Doctrine/deploy'' folder:<br>
+
GocDB can be deployed as a blank instance ready for use or as a sample instance with a small amount of example data to demonstrate GocDB. The deploy script can be found at ''/lib/Doctrine/deploy/deploy.sh'':<br>
 +
 
 +
'''Windows Users:''' These scripts are designed for deployment on a Linux machine (Cygwin on Windows is ok). 
  
<pre>oracleDeploy.sh
 
mysqlDeploy.sh
 
sqliteDeploy.sh
 
</pre>
 
  
 
By supplying a flag when executing the script you can deploy either a new empty database or a sample database eg:
 
By supplying a flag when executing the script you can deploy either a new empty database or a sample database eg:
  
 
<pre>
 
<pre>
$ ./oracleDeploy.sh -s
+
$./deploy.sh -s
  
 
Deploying GocDB with sample data
 
Deploying GocDB with sample data
Line 184: Line 199:
 
or
 
or
 
<pre>
 
<pre>
$ ./oracleDeploy.sh -n
+
$./deploy.sh -n
  
 
Deploying new empty GocDB instance
 
Deploying new empty GocDB instance
Line 190: Line 205:
  
 
=== Apache Configuration  ===
 
=== Apache Configuration  ===
 +
 +
Now that your database is deployed the final step is to configure Apache.
 +
 +
==== /etc/sysconfig/httpd - Oracle configuration ====
 +
 +
The Oracle environment must be set correctly before starting Apache so that PHP OCI8 works correctly. In general you should set the same variables that are set by the ''$ORACLE_HOME/bin/oracle_env.sh'' script. The necessary environment variables can be set in Apache's environment configuration file.
 +
On RedHat Linux and its derivatives with the default httpd package, this is ''/etc/sysconfig/httpd''.
 +
<pre>
 +
export ORACLE_HOME=/u01/app/oracle/product/12.1    # Adjust pathname to match your installation
 +
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH
 +
</pre>
  
 
==== httpd.conf  ====
 
==== httpd.conf  ====
 
Now that your database is deployed the final step is to configure Apache.
 
  
 
A few modules need to be enabled for GOCDB to work, check these are enabled on your Apache and if not enable them.&nbsp;  
 
A few modules need to be enabled for GOCDB to work, check these are enabled on your Apache and if not enable them.&nbsp;  
Line 199: Line 223:
 
In ''httpd.conf'' enable ssl_module by un-commenting these lines:  
 
In ''httpd.conf'' enable ssl_module by un-commenting these lines:  
 
<pre>LoadModule ssl_module modules/mod_ssl.so</pre>  
 
<pre>LoadModule ssl_module modules/mod_ssl.so</pre>  
and
+
 
<pre>extension=php_openssl.dll</pre>
+
 
Depending on the database you are using the supporting module may also need to be enabled. For example Oracle requires the oracle module to be uncommented:
+
 
<pre>extension=php_oci8_11g.dll</pre>
 
Take the file ''gocdbssl.conf'' and place this file in the apache/conf/extra folder. In ''httpd.conf'' include the ''gocdbssl.con'' by adding the following line under the heading ''Supplemental Configuration'':
 
<pre>Include conf/extra/gocdbssl.conf
 
</pre>
 
 
==== gocdbssl.conf  ====
 
==== gocdbssl.conf  ====
 
+
A sample ''gocdbssl.conf'' is provided in GocDBSrc/config. This file will define the alias and SSL settings used by Apache to connect to GocDB.
This file defines the location of resources required by GocDB.  
 
  
 
===== Paths  =====
 
===== Paths  =====
Line 216: Line 235:
 
===== SSL Keys  =====
 
===== SSL Keys  =====
  
The ''SSLCertificateFile'' should point to the location of your server SSL key file. The ''SSLCertificateKeyFile'' -- The ''SSLCACertificationPath'' should point to the location of your CA certificates which can be obtained from: //Ask Dave
+
The ''SSLCertificateFile'' should point to the location of your server SSL key file. The ''SSLCertificateKeyFile'' -- The ''SSLCACertificationPath'' should point to the location of your CA certificates.
  
For development the ''SSLCertificatedFile'' and ''SSLCertificateKeyFile'' can be self signed certificates. However these must not be used in production.  
+
For development the ''SSLCertificatedFile'' and ''SSLCertificateKeyFile'' can be self signed certificates. However these must not be used in production.
  
 
===== Aliases  =====
 
===== Aliases  =====
Line 241: Line 260:
 
<pre>Alias "/gocdbpi/private" "/gocDBsrc/htdocs/PI/private"
 
<pre>Alias "/gocdbpi/private" "/gocDBsrc/htdocs/PI/private"
 
&lt;Directory "/gocDBsrc/htdocs/PI/private"&gt;
 
&lt;Directory "/gocDBsrc/htdocs/PI/private"&gt;
</pre>  
+
</pre>
 +
 
 +
=== Compiled Entities ===
 +
This step is optional, but for production servers this step is strongly recommended. When Doctrine uses an entity it creates a compiled version of the entity which by default is stored in the machines temporary folder. This is un-suitable for production machines as this may well be emptied. To avoid this uncomment the following line in bootstrap_doctrine.php:
 +
<pre>
 +
$config->setProxyDir(__DIR__."/compiledEntities");
 +
</pre>
 +
 
 +
You now need to create this folder in the same directory as the ''bootstrap_doctrine.php'' file:
 +
<pre>
 +
$mkdir compiledEntities
 +
</pre>
 +
 
 +
Once this folder is created it, your apache server needs write permissions (the exact command may change depending on your apache server):
 +
 
 +
<pre>
 +
$chown apache compiledEntities/
 +
</pre>
 +
 
 +
<pre>
 +
$ls -ltrh
 +
total 28
 +
drwxr--r-- 2 apache root 4.0K Nov 20 16:11 entities
 +
-rw-r--r-- 1 apache root  131 Nov 20 16:11 README.txt
 +
-rw-r--r-- 1 apache root  219 Nov 20 16:11 cli-config.php
 +
-rw-r--r-- 1 apache root 1.6K Nov 20 16:11 bootstrap.php
 +
-rw-r--r-- 1 apache root 3.0K Nov 20 16:11 bootstrap_doctrine_TEMPLATE.php
 +
-rw-r--r-- 1 apache root 2.8K Nov 27 09:38 bootstrap_doctrine.php
 +
drwxr--r-- 2 apache root 4.0K Nov 27 09:39 compiledEntities
 +
</pre>
 +
 
 +
Finally use the doctrine command line client to generate the compiled entities and store them in the folder:
 +
<pre>
 +
doctrine orm:generate-proxies compiledEntities/
 +
</pre>
 +
 
 +
This folder is now configured with the compiledEntites. It can be copied and used for new instances of GocDB as long as there have been no changes made to any of the entities, or it can be recreated as demonstrated each time.
 +
 
 
=== First Use  ===
 
=== First Use  ===
  
You should now be able to navigate to the GocDB webportal on your host using the URL defined in your alias. You will need to install a browser certificate that is suitable for the SSL keys you defined for your host to be able to view GocDB.  
+
You should now be able to navigate to the GocDB webportal on your host using the URL defined in your alias. You will need to install a browser certificate that is suitable for the SSL keys you defined for your host to be able to view GocDB.
 +
<pre>
 +
https://localhost/portal
 +
https://localhost/portal/GOCDB_monitor/index.php
 +
</pre>
 +
 
 +
====Local_Info.xml====
 +
GocDB picks up a number of its settings and variables from the local_info.xml file located in the ''config'' folder. The ''web_portal_url'' will be output in the PI to create links from PI objects back to Portal views. The ''pi_url'' and ''server_base_url'' will both be used by the monitor. The monitor is a quick look status check for GocDB. The mointor can be found at your web_portal_url/GOCDB_monitor/. If these URL's are not set in the local config this feature will not work correctly.
 +
 
 +
''default_scope'' defines which scope if any will be used if no scope is specified when running PI queries. This can be left blank or set to a scope of your choosing. ''default_scope_match'' is again used if no scope_match parameter is supplied with PI queries. This can be either all or any. The ''minimum_scopes'' section declares how many scopes an NGI, site, service or service group must have at creation. This can be left as 0 or set as 1 if you want all your users entities to belong to at least one scope or more as dictated by your use of GocDB.
 +
 
 +
It's important at this point to understand how the scopes work with GocDB v5 especially in relation to the output of the PI. If you specify a default scope within your local_info but none of your entities have this scope then nothing will show in the PI. For an in-depth look at the scopes mechanism the section please read the section 'Multiple Scopes and Projects' in the [https://wiki.egi.eu/w/images/d/d3/GOCDB5_Grid_Topology_Information_System.pdf GOCDB5 Grid Topology Information System] document on page 5.
 +
 
 +
====Setup an Admin User====
 +
 
 +
To get started with GocDB you will need an admin user. This is done by first registering as a user on GocDB by clicking the 'Register' link on the left menu bar at the bottom. Once you have registered yourself you will then need to set yourself as an admin. To do this you need to change the user record directly in your database. The users table has a field called 'isAdmin' which by default is set to 0. To change a user to admin set this to 1. Below is a sample of the SQL query used when using an Oracle database to set a user as admin.
 +
 
 +
<pre>
 +
UPDATE users SET isadmin=1 WHERE forename='John' AND surname='Doe'
 +
</pre>
 +
 
 +
Once you have an admin user you can create Projects and NGI's and grant roles to other users over these entities to allow them to add to GocDB.
  
 
== Testing ==
 
== Testing ==
  
 
GocDB v5 comes with a suite of tests that can be run to validate the install and check that Doctrine and your chosen database are operating as expected. These tests require PHPUnit, the install instructions for this can be found in section 3.6. The tests can be found in the GocDB/tests/ folder.  
 
GocDB v5 comes with a suite of tests that can be run to validate the install and check that Doctrine and your chosen database are operating as expected. These tests require PHPUnit, the install instructions for this can be found in section 3.6. The tests can be found in the GocDB/tests/ folder.  
 +
 +
===Install the Oracle OCI drivers for PDO===
 +
To run tests you will also need to install the Oracle OCI8 PDO (PHP Data Object) drivers for PHP since the DBUnit tests
 +
use PDO for their execution to validate that the results that Doctrine is returning are true. To install the OCI8 drivers for pdo. See: http://www.php.net/manual/en/pdo.drivers.php
 +
 +
You can test that you have the OCI8 pdo drivers installed via php info. This can be called on the command line with $php -i or via a script with phpinfo(). There will be a section that lists your enabled pdo drivers, e.g. as below:
 +
<pre>
 +
            |-----------------------------|
 +
            |            PDO            |
 +
            |-----------------------------|
 +
            | PDO support enabled  |
 +
            | PDO drivers mysql,oci |
 +
            |-----------------------------|
 +
</pre>
  
 
=== Deploying a Test Database ===
 
=== Deploying a Test Database ===
  
We recommend that you deploy a second database that will be used for testing. Once you have created your second database input the connection details into the bootstrap_doctrine.php file found in GocDB/tests/doctrine. Within this file there are 3 sets of connection configurations, once for MySQL, Oracle and SQLite. Complete the section for your database and ensure that the other connection details are deleted or commented out. In addition to the standard Doctrine connection to the database the tests make use of a PDO connection to validate that the results that Doctrine is returning are true. To setup the pdo connection open 'bootstrap_pdo.php'. Within this file you will again find 3 connection blocks. Complete the details for the connection details for your database and ensure that the other 2 connections are either deleted or commented out.
+
We STRONGLY recommend that you deploy a second database with different connection details that will be used for testing.  
 +
* Create a second DB account/user for your test database (e.g. GOCDB5TEST).
 +
* Copy ''bootstrap_doctrine_TEMPLATE.php'' file found in tests/doctrine to ''bootstrap_doctrine.php'' (in the same dir).
 +
* Modify ''bootstrap_doctrine.php'' to specify your GOCDB5TEST account/user. Complete the section for your database and ensure that the other connection details are deleted or commented out.
 +
* Copy ''bootstrap_pdo_TEMPLATE.php'' to ''bootstrap_pdo.php''. Complete the details for the connection details for your database and ensure that the other 2 connections are either deleted or commented out, see below:
  
 
<pre>
 
<pre>
Line 276: Line 371:
 
=== Running the Test Suite ===
 
=== Running the Test Suite ===
  
A initial test suite is provided that will excercise core functions of GocDB and Doctrine, this suite can be ran using the command:
+
A initial test suite is provided that will excercise core functions of GocDB and Doctrine. This suite can be ran using the command:
 
<pre>
 
<pre>
 
phpunit DoctrineTestSuite1.php
 
phpunit DoctrineTestSuite1.php
 
</pre>
 
</pre>
  
You will be prompted to continue as this operation will drop any tables in your test database and then recreate the schema ready to run the tests. These tests should return with no errors to demonstrate that GocDB and Doctrine are installed correctly and are working as expected.  
+
You will be prompted to continue as this operation will drop any tables in your test database and then recreate the schema ready to run the tests. These tests should return with no errors to demonstrate that GocDB and Doctrine are installed correctly and are working as expected.
  
 
=== Running Individual Tests ===
 
=== Running Individual Tests ===
  
Individual tests can be run by calling phpunit testName.php. It is advised that at the beginning of a testing session you drop and recreate the database by running:
+
Individual tests can be run by calling:
 +
<pre>phpunit <testNameFile>.php</pre>
 +
It is advised that at the beginning of a testing session you drop and recreate the database by running the recreateTestDB.sh script.
 +
 
 +
===Recreating the Test DB===
 +
You can run the following script found in the ''tests/doctrine'' folder to Drop and Recreate the test database whenever required:  
 
<pre>
 
<pre>
 
./recreateTestDB.sh
 
./recreateTestDB.sh
 
</pre>
 
</pre>
Found in the GocDB/tests/doctrine folder.
 
  
 
=== Writing Tests ===
 
=== Writing Tests ===
Line 303: Line 402:
 
<pre>
 
<pre>
 
bootstrap_doctrine.php
 
bootstrap_doctrine.php
truncateDataTables
+
truncateDataTables.xml
 
</pre>
 
</pre>
  
 
The first holds your connection details and the second will initialize the database with the correct tables ready for testing.  
 
The first holds your connection details and the second will initialize the database with the correct tables ready for testing.  
  
You can write multiple test functions at the bottom of this skeleton file.  
+
You can write multiple test functions at the bottom of this skeleton file.
 +
 
 +
==== Doctrine Test Example ====
 +
 
 +
'DoctrineTestExample.php' shows the following example test. In this test we will create a site, populate the site with some data and then assert that the data is correct.
 +
 
 +
'''This test will make use of the 'TestUtil.php' file which contains a few helper methods to quickly create objects. This file is located in GocDBSrc/test/doctrine. When following this tutorial execute 'DoctrineTestExample.php' from GocDBSrc/test/doctrine.'''
 +
 
 +
Creating the site:
 +
<pre>
 +
    public function testDoctrineExample() {
 +
        print __METHOD__ . "\n";
 +
 
 +
        //Create a site
 +
    $ourSite = TestUtil::createSampleSite("Our Example Site");
 +
 +
    }
 +
</pre>
 +
 
 +
We now have a site and will add some extra information to the site utilizing setters methods defined in the site entity which can be found in GocDBSrc/lib/Doctrine/entites. We will add an email, telephone and location to the site:
 +
 
 +
<pre>
 +
//Create a site
 +
    $ourSite = TestUtil::createSampleSite("Our Example Site");
 +
 +
//Set some details of the site
 +
$ourSite->setEmail("myTest@email.com");
 +
$ourSite->setTelephone("012345678910");
 +
$ourSite->setLocation("United Kingdom");
 +
</pre>
 +
 
 +
 
 +
We now must persist this object in memory by calling '$this->em->persist($outSite);'
 +
 
 +
However this now only exist in memory - it is not yet in the database. To check this we can query the database directly using the PDO connection we setup:
 +
 
 +
<pre>
 +
//Get the site ID from the object
 +
$siteId = $ourSite->getId(); 
 +
 +
//Get a database connection    
 +
    $con = $this->getConnection();
 +
 +
//Search the database for this site
 +
$sql = "SELECT 1 FROM sites WHERE ID = '$siteId'";
 +
$result = $con->createQueryTable('', $sql);
 +
 
 +
        //We expect this query to return no rows as the site does not exist in the database yet
 +
$this->assertEquals(0, $result->getRowCount());
 +
</pre>
 +
 
 +
When running the test at this point the outcome should be:
 +
<pre>
 +
OK (1 test, 1 assertion)
 +
</pre>
 +
 
 +
Our assertion was correct, there were no sites with that ID in the database yet as it has not been committed, the site only exists in memory at the moment. To commit the site to the database we must call:
 +
 
 +
<pre>
 +
      $this->em->flush();
 +
</pre>
 +
 
 +
Now if we run the query again we expect one result:
 +
<pre>
 +
//Search the database for this site again
 +
$sql = "SELECT 1 FROM sites WHERE ID = '$siteId'";
 +
$result = $con->createQueryTable('', $sql);
 +
 +
//We expect this query to return 1 rows as the site now exists in the database
 +
$this->assertEquals(1, $result->getRowCount());
 +
 
 +
</pre>
 +
 
 +
This shows the process of creating an entity, using its get and set methods to enter and retrieve data and then committing it to the database. It also shows the process of using the PDO connection to check that the data exists in the database as we expect.
 +
 
 +
-->
 +
 
  
  
 +
  
 
[[Category:GOCDB]]
 
[[Category:GOCDB]]

Latest revision as of 16:02, 9 November 2016