Create Business Code
-We start the design with the database, the entity relationships are shown -in the diagram below.
- -Now we can begin to create and test some business code. Let us begin -with the Project defintions. First, we add some properties or fields.
-All the fields should be self explainatory. The ManagerUserName -is the user name of the project manager. Notice that the fields -are public, later on, we can change some or all of them to be private and -provide some accessor and mutators (i.e. getters and setters). If we want -we can let the Project class inherit TComponent such -that the getters and setters can be used like properties, such as those -found in Prado.
- -Business Services, test case first
-Next we want to add users to the project. For this, we start with some -unit tests. We are going to design the business logic around the concept of -Data Access Objects (DAO).
- -So what are we doing here? First we create a new Project named -"Project 1". Then we create a new ProjectDao so we can insert new projects -and retrieve it. We assert that a project will be create sucessfully using -assertTrue($do->createNewProject(...)). We also assert that -getProjectByID(1) will return an instance of Project class -with same data (the reference may be different).
- -If we run the above unit test case, nothing is going to pass since we have -not even defined the ProjectDao class. So lets do that first and import -the class in the tests as well.
- -We will create a base Dao class as follows, and we save as BaseDao.php -in our APP_CODE directory.
-And finally our ProjectDao class.
-If we run the unit test again, we get an error message something like -"Fatal error: Call to undefined method ProjectDao::createNewProject() in ...". -So let us, fix this. -
-Run the unit test again, we see a different type of error now. This time -the unit test runner complians that the test fails.
-Write Test, Run Test, Repeat
-
-At this point, you may notice a repetition
-
--
-
- write some test code, -
- run the test, test gives an error, -
- write some actual code to only remove the previous error, -
- goto step 1 to repeat. -
We shall see how we can make this test pass in the next section.
-Database Design
-The design steps we take in the sample application is a data centric -approach. That is, we shall consider the application from the view -point of data structures, data relationships and data integrity. -Other designs starting from object and class design are also possible but is -not the approach taken in this guide. -
- -Entity Relationship
-We start with the following entity relationship diagram. -The bold text in each entity indicate required fields. The underline -text indicates the entity's primary key, also denoted as PK. -Entity relationships are indicated with arrows between entities and -each relationship field is denoted with FK.
- -The four entities: Project, Categories, TimeEntry -and ProjectMembers -makes up the time tracker application. While the other entities: -Users, UserRoles, RoleTypes and Signon are -usually found in applications where membership or user management is required.
- -Info:
-See Database Normalization
-for a quick reference regarding database design and normalization, especially the
-3rd normal form (3NF).
-
-
-MySQL database
-We shall concentrate on the MySQL database for this sample application. -Other database engines are also possible and can be quite easily inter-changed. -The SQL script to initialize the MySQL database is given below. The following -SQL script was created using MySQL version 4.1.7. -
- -Installation
-There are a few pieces of tools and software needed throughout the development -of the application. First we shall setup the environment for coding and testing. We -shall from here on assume that you have access to a working installation of a web server with -PHP and possibilly a MySQL database server. The first thing to do is install Prado and some -testing tools.
- -Download and Install Prado
-The minimum requirement by PRADO is that the Web server support PHP 5. - For the Time Tracker sample application, you need Prado version 3.1 or greater.
-Installation of PRADO mainly involves downloading and unpacking.
--
-
- Go to pradosoft.com to grab the latest version of PRADO. -
- Unpack the PRADO release file to a Web-accessible directory. -
You should at least first check that the demos bundled with the Prado distribution are - working. See the - quickstart tutorial for further instructions on running the demos. -
- -Help! Nothing is working!
-If you encounter problems in downloading, unpacking and running the demo applications, please - visit the forum to seek help. Please - do a search on the forum first or read the PDF version of the quickstart. - The friendly and wonderful people at the forum can better assist you if you can provide as much detail regarding your problem. - You should include in your post your server configuration details, the steps you took to reproduce your problem, and any error messages encountered.
- -Create a new Prado application
-Prado is bundled with a command line tool to create the necessary directory structure to run a hello world application. -The command tool prado-cli.php is a php script and can be found in the prado/framework/ directory. -To create a new application, go to your document root and type the following command in console. -
-Tip:
-For linux and OS X environments, you can chmod u+x prado-cli.php
-and change the first line of prado-cli.php to the location of your
-PHP command line interpreter. Now, you may call the script from command line
-like an executable.
-
-
-A directory named time-tracker will be created containing the following.
-
The time-tracker directory is where we are going to put all our code for the Time Tracker application. -Since -t was passed into the prado-cli.php script, unit and functional test - skeletons are also created.
-Prado Time Tracker Implementation Guide
- -Introduction
- -The Time Tracker is a fully functional sample application designed to - introduce you to many of Prado's features. This guide is a step by step - walkthrough starting from installation to deployment. The Time Tracker - application is based on the - ASP.NET's Time Tracker Starter Kit. -
- -Time Tracker Overview
-The Time Tracker is a business web application for keeping track of hours spent -on a project, with ability to handle multiple resources as well as multiple projects.
-Basic Application Requirements
-The functional requirements of the Time Tracker is based on the - ASP.NET's Time Tracker Starter Kit - description.
--
Create projects
--
-
- Define projection information like due dates, hours to complete, project - resources, and more. -
- Break down projects into tasks and track work on per-task basis. -
Create and track tasks
--
-
- Track time spent each day by category and project. -
Use reports to track progress
--
-
- Track overall progress across multiple projects, including estimated and actual work. -
- Track total work for team resources across multiple projects. -
Technologies and Design Approached Demonstrated
--
-
- Prado event-driven component framework -
- Separation of concerns: persistent storage, business logic, presentation -
- Object-Relational mapping using SQLMap -
- Unit testing and functional testing -
- Promote code reuse -
Requirements
-The Time Tracker web application requires the following software and knowledge.
-Software requirements
-It is assumed that you are able to obtain and install the following pieces of software.
--
-
- PHP version 5.0.4 or greater -
- A web server, such as Apache, able to run PHP scripts -
- MySQL database server version 4.1 or greater (alternatively SQLite or Postgres) -
- Prado version 3.1 or later -
In addition to software requirements, we assumed that you have some of the following knowledge.
--
-
- Access the internet to download packaged code, and unzip these code. -
- Understand the basic concepts of Object-Oriented programming in PHP such as - classes, objects, methods, etc. -
- Basic understanding of relational databases and Structured Query Language (SQL). -
- Knows how to have fun, this is mandatory. -
-
-
-PRADO Time Tracker Guide
-
-|
- |
-
-
-
- |
-
Finishing up test case
-Up to this point, you should have the follow pieces of files and code.
- class="figure" />
-
So what else can we test for at this point? A few reasonable -tests are to see what happens if the project already exists, and what if -the username does not exists.
- -First we shall refactor our test code since much of the setup code -for the mocked connection will need to be repeated in other test assertions. -We change the test case to have these three new methods. -
- -Our refactored test method testProjectDaoCanCreateNewProject() -is as follows.
-To test that the project already exists, we modify the mock -connection and test for an exception.
-Other test method for testing missing customer and manager users -are done similarly. At this point, the test case file looks quite large. -We shall not add more tests to this case and we should rename the file -from ProjectDaoTestCase.php to CreateNewProjectTestCase.php. - -
Note:
-A heirachical exception class may be more useful in testing for specific
-exceptions. For simplicity, we decided to use only TimeTrackerException
-for this small project.
-
-
-Tip:Class, method and file naming is very
-important to any project, the name should inform you at first glance what
-is to be expected from the class, method or file. In addition, the naming
-scheme should be uniform over the project.
-
-
-Comment:
-These test may be too ridget as any changes to the implementation may
-actually cause the tests to fail. This is the case with grey-box/white-box
-testing, you are actually testing the implementation. Black box tests may
-be more preferable, as it should only test the class interface (the method or
-function details such as parameters and may be return values). However,
-with the use of database connection to retrive data within the objects under test,
-it may be more suitable to do intergration tests.
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/demos/time-tracker/protected/pages/Docs/UserClassAndExceptions.page b/demos/time-tracker/protected/pages/Docs/UserClassAndExceptions.page
deleted file mode 100644
index f85e00be..00000000
--- a/demos/time-tracker/protected/pages/Docs/UserClassAndExceptions.page
+++ /dev/null
@@ -1,202 +0,0 @@
-More complete ProjectTestCase
--In creating a new project, we need to check the following: -
-
-
- that the project does not already exists, i.e. no duplicate project name -
- that the project creator and project manager exists when a new project is created -
It may seem very weird that there is so much code in the tests -and why we even bother to write all these test codes. Well, using the -above test code we have the following advantages.
-Advantages of Mock
-
-
--
-
- we don't need a real database base connection to test the code, - this means we can start relying on tested code ealier -
- when a test fails we know that problem is not part of the database -
- when a test fail, we can quickly pin point the problem -
- the test suite gives us the confidence to refactor our code -
Of couse, the test will not be able to cover the higher interactions, such as -the user interface, so intergration or functional web test will be used later on. -
- -So how did we come up with the above tests? We started simple, then we -ask what sort of things it should handle. We assume that the connection object -work as expect or known to be unexpected and see how the method we want to test handle -these situations.
- -If we run the above test, we will be faced with numerous errors. First will be -that the TimeTrackerUser can not be found.
- -Creating a new User Class
-Notice that the Project class contains CreatorUserName
-and ManagerUserName properties. So at some point we
-are going to need at least one User class. We shall name the class as
-TimeTrackerUser and save it as APP_CODE/TimeTrackerUser.php
-
Custom Exceptions
-We enforce that the ID of the user to be read-only once it has been -set by throwing a custom exception. Prado's exception classes -uses a string key to find a localized exception string containing more -detailed description of the exception. The default exception messages -are stored in the framework/Exceptions/messages.txt. This -file location can be changed by overriding the getErrorMessageFile() -method of TException class. We define a custom exception class -for all Time Tracker application exceptions as TimeTrackerException -and save the class as APP_CODE/TimeTrackerException.php.
- -We then create a exceptions.txt file in the APP_CODE -directory with the following content.
- -Additional parameters passed in the exception constructor can be -added the message string using {0} as the first additional parameter, -and {1} as the second additional parameter, and so on. -For example, suppose we want to raise the follow exception. -
- -The exception error message in exceptions.txt may contain something like:
-Completing the test case
-From the unit test code, we can pretty much see what the implementation -for createNewProject() will look like.
- -Tip:
-A hierachy of exception class can be used to have fine exception handling.
-Since this is a small project and for simplicity, we shall use the application level
-TimeTrackerException exception class for most exception cases.
-
-
-Using SQLMap Data Mapper
-Before proceeding with write the code to pass the test in the previous section, we shall -make a design decision. We shall use SQLMap as our data access layer. Note -that SQLMap is only available offically in Prado 3.1 or later.
- -SQLMap is an PHP implemenation of an Object/Relational -data mapper. SQLMap has the following basic features: -
-
-
- collects all the Structured Query Language -(SQL) statements in an external XML file -
- Maps data return from database queries into PHP objects -
- Takes PHP objects as parameters in SQL queries -
SQLMap can be seen as a generic data mapper, rather than an -Object Relational Mapping (ORM) solution.
- -The SQLMap API consists of the following methods. See the SQLMap manual -for further details.
- -Fetch and Inserting Data Using SQLMap
-Back to our ProjectDao class, for testing we shall write the code -assuming we have an SQLMap client instance. The SQLMap client or connection -will be mocked or faked using a proxy. Later on, we shall extend our tests, -to become an intergration test, to include -a test database connection.
- -Creating a SQLMap connection
-We can test the ProjectDao using mock objects (see SimpleTest documentation -regarding mock objects) or using a real database connection. In PHP version -5.0.x, the sqlite database client is bundled by default. For version 5.1 or later -the sqlite database client is available as an extension. We shall use a sqlite -database to conduct our unit tests because the database can be restored to -the orginal state by just reloading the orginal database file.
- -Comment:
-Unit tests using mocked objects may be too ridget as we need to mock
-the connection object and thus the test is of the grey-box/white-box variaity.
-That is, you are actually testing the implementation of the object under test
-consideration. Thus, any changes to the implementation of the objects
-under tests may actually cause the tests to fail. Black box tests may
-be more preferable, as it should only test the class interface (the method or
-function details such as parameters and may be return values). A further
-disadvantage when using mocks for complex database connection is the complexity
-required in setting the mocks for testing.
-
-
-First, let us define the database table for projects.
-The corresponding SQLite query to create the table is given below.
- -Testing with Mocked Database Connection
-At this point, we have said nothing about databases. To create some unit tests -for the ProjectDao class, we are not going to use real database connections -but using a Mocked TSqlMapper. We modifiy the test as follows. -
-The test code looks slight more complicated because later on we want to -test the same assertions against some real data.
--In the first two lines above, we simply import the business code and the TSqlMapper class. -We generate a MockTSqlMapper, a mock class or TSqlMapper using -Mock::generate('TSqlMapper'). The method Mock::generate() is available from -the SimpleTest unit testing framework. An instance of MockTSqlMapper -will be used as our test connection for the DAO objects. This allows us to interogate the -internal workings of our ProjectDao class. -
- -In the setup() (this method is called before every test method), we create an instance of -ProjectDao and set the connection to an instance of MockTSqlMapper. -
- -Testing internal workings of ProjectDao
- -So how do we test the internal workings of the ProjectDao createNewProject method? -First, we assume that the connection object will perform the correct database insertion and queries. -Then, we set the return value of the MockTSqlMapper instance to return what we have assumed. -In addition, we expect that the TSqlMapper method queryForObject is called only once with -the parameters we have assumed (e.g. $project). See the SimpleTest tutorial for further details regarding -unit testing with Mocks. -
- -In our assertions and expectations, we have
-
We now run the unit tests, we see that there are some failures or errors. Since we
-have not created any code in ProjectDao that performs what we want, the tests will fail.
-So lets make these test pass, we add some code to ProjectDao class.
-
-
If we run the unit tests again, we should see a green bar indicating that the tests have passed. -We can now proceed further and add more tests. Of course, the above test does not cover many -conditions, such as, what happens if the project already exists?, the details of these -tests is the subject of the next section. The full test suite can be found in the source. -
-Writing a Functional Web Test
-In addition to unit testing, we shall also do some functional -testing or web testing. Functional tests are, in this case, basically automated tests that will -interact with the overall web application, as if it was the user, while checking the output for correctness. -The functional test tool we shall use here is based on Selenium where the test cases can be written and run using PHP and SimpleTest. -
-Save the code as HelloPradoTestCase.php in the document_root/time-tracker/tests/functional/ -directory.
- --Functional test cases are written very similar to unit test cases. The method such as -open($url) are those found in Selenium. All the methods available in Selenium are available. -
- -Run your first unit test case from your browser
-Point your browser to your development server's unit test case runner, e.g.
- http://web-server-address/time-tracker/tests/functional.php. You should see the following
- 
-
Figure 4: Functional test runner
-
-Clicking on the All button, you should see
- 
-
Figure 5: Functional test success
-
-
-Writing a Unit Test
-Before we begin to write our business logic and code, we shall -proceed with the path of test driven development (TDD), or at least take -some part of that process.
- -Unit testing is a useful tool when we want to start to test - our individual business logic classes. - The tests/unit directory will be used to hold the unit test - cases and tests/functional directory - to hold the function test cases. -
- -Write a unit test case
-We will start be writing a very simple unit test case. Notice -that we are writing the test case first.
-Save the code as ProjectTestCase.php in the document_root/time-tracker/tests/unit/ -directory.
- -Run your first unit test case from your browser
-Point your browser to your development server's unit test case runner, e.g.
- http://web-server-address/time-tracker/tests/unit.php. You should see the following
-
-
Figure 1: Unit test runner
-
-Clicking on the ProjectTestCase.php link, you should see
-
-
Figure 2: Unit test failure
-
-
-Smallest step to make the test pass.
- -Since we only wrote the test case and nothing else we expected -that the test case will fail at some point. Obviously, we need create -a class Project, so lets define the Project class.
-We save the above code as time-tracker/protected/pages/APP_CODE/Project.php. - Where the APP_CODE directory will contain most of the business logic code - for the Time Tracker application.
-Now, we also need to add the following line in our test case so as to -include the Project class file when running the tests.
- -Info:
-The statement Prado::using('Application.APP_CODE.Project') basically
-loads the Project.php class file. It assumes that a class name Project has filename Project.php.
-For futher details regarding Prado::using can be found in Prado Namespaces documentation.
-
-
-Run the unit test runner again, we see that the test has passed.
- 
-
Figure 3: Unit test success
-
--Later on, we shall write more test cases. See the -SimpleTest documentation -for detailed tutorial on writing test cases.
- -Prado Time Tracker
-This documentation is complete walk-through guide detailing the -steps involved in implementating of the Prado Time Tracker web application. -
-Target Audience
-The guide is intended for readers who has some experience -using PHP version 5 and some basic concepts of Object-Oriented application -design. The guide will assume that the reader understands the primary concepts -of class, methods, class inheritance, and other basic features offered by PHP -version 5 or later.
-Questions and Comments
-Readers are encouraged to ask questions as the forum regarding any -particular aspect of this documentation. Comment and constructive criticisms -are most welcome. Questions and comments may be directed at -http://www.pradosoft.com/forum/. -
- -Help
-Implementation Guide
Projects and Time Entries
@@ -132,37 +131,6 @@- -
Appendix A - Manually Managing Members and Roles
-- Your Time Tracker Web site allows visitors to register as members. - Members have specific privileges defined by a role you assign to them. - A special administrative role has rights to perform all functions in the site.
-- To create a user (member):
--
-
- Login as administrator, click Create New User. - -
- ... -
- To modify an existing member's role:
--
-
- Login as administrator, click List Users. - -
- ... -
- -
Appendix B - Publishing Your Site
-- When you are ready to share the Web site with others, you can copy it to your Web server. - You need to know the File Transfer Protocol (FTP) address of your server, and if required, the user name and password assigned to you.
--
-
- ... -