The OOP & refactor project weekly report 4

Hello, in this week I have finished my works on templates of table related scripts. They are covered in PR 1700.

Files Covered In This Week

  • TableSearch.class.php
  • tbl_columns_definitions_form.lib.php
  • tbl_gis_visualization.lib.php
  • tbl_indexes.lib.php
  • tbl_relation.lib.php

Outcomes In This Week

Templates for table related scripts
Firstly, the tbl_indexes.lib.php and tbl_gis_visualization.lib.php is the two easiest for me. The most challenging script is the TableSearch.class.php, since HTML generation functions are usually reference to private helper functions and member variables by using $this. To solve this problem, I took out HTMLs from these helper functions and integrate them into where there were referenced before. Further, I kept contents from some of these function as common templates. By templating on table related scripts, it will be easier for me to move on in the next phase of work.

The Problem I am Facing

There are so many assertion on HTML tags in unit test. For example, the following code will fail the test below but it just work fine in our browser:

<form method="post"
action="tbl_create.php"
class="create_table _form ajax lockpage">

The unit test code:

$this->assertContains('<form method="post" action="tbl_create.php" '
. 'class="create_table _form ajax lockpage">', $result);

Maybe we could use a more effective way to test front-end components (templates, pages, etc) in the future, though I haven’t figure out how to achieve this goal yet.
Could you give me some suggestions about this?

What will I Do Next

Since I have two final examations in the next week, I will leave from work temporarily until June 5th. By the moment I will start working on creating preliminary classes of table related scripts.

Advertisements
The OOP & refactor project weekly report 4

The OOP & refactor project weekly report 3

During this week I updated the template system by changing its support extension to “.phtml”. Also, I have templated some scripts.

Files Covered In This Week

  • Template.class.php
  • tbl_indexes.lib.php
  • scripts/update-po
  • tbl_printview.lib.php

Outcomes In This Week

Change template extension to “.phtml”
After thinking about conversations involved in the PR 1642, I decided to change the template extension to “.phtml” since it’s clearer to show these files are used to render but not being executed. Using “.phtml” as extension has no security risk because everyone can access phpMyAdmin’s source code anywhere.
Further, I have changed a tranlation related script (scripts.update-po) to let it include template scripts.

Add tests for Template class
The problem of lack of tests for the Template class was solved.

Complete templates for db designer module
Templates on db designer was completed. Now it should be clearer!

Template for tbl_indexes.lib.php, tbl_printview.lib.php
In recent two days I complete tests on the tbl_indexes.lib.php and tbl_printview.lib.php. Their template correspond to index_form.phtml and printview directory in the templates folder respectively. Once I complete the template scripts for tbl_column_definitions.lib.php, then I will open a pull request.

What will I Do Next

I will continue working on templates of table related scripts next week.

The OOP & refactor project weekly report 3

The OOP & refactor project weekly report 2

Hello everyone, one week soon come to an end, and here is my weekly report on what did I do in the last week. During last week, I was working on the Template class and try to fix the test problems in the PR 1642.

Files Covered In This Week

  • PMA_SystemDatabase_test.php
  • PMA_DatabaseInterface_test.php
  • Template.class.php

Outcomes In This Week

Introduce trim($string) to Template class
public static function trim($string)
and
public function render($data = array(), $trim = true)

I implemented a trim method for Template class because I found Javascript often reference value of HTML tags. Sometimes there may have some whitespaces in these tag values (Perhaps, for better readability of template codes), then we cannot get correct value of that tag by using $().html() in Javascript.
The trim method is default applied to all templates after it gets rendered. If you don’t want it be trimed, you can simply set the boolean field $trim in render method to false.
The trim method is designed to be static, so it can also be used as an utility for trim spaces in HTML pages.

Fix on PR 1642
Firstly I feel so sorry for taking so long to fix the problem of the pull request. I over estimated my knowledge on the phpunit test framework, eventually I have to spend a lot of more time to learn how to use it again.
Tests involve functions originally in tbl_views.lib.php was moved from PMA_tbl_views_lib_test.php to PMA_SystemDatabase_test.php and PMA_DatabaseInterface_test.php.

What will I Do Next

In next few days I will submit my works on template of the Designer Module. Also, I will post a new blog on dependency calculation on TableSearch.class.php.
The major job in next week will be starting template on table related scripts.

The OOP & refactor project weekly report 2

The OOP & refactor project weekly report 1

After a whole week of work, I have almost finished the job of first phase — calculate dependencies. Firstly I used automated tools like doxygen and phpstorm to determine where the functions is called. Then I can decide how to refactor it.

Files covered in this week

  • tbl_chart.lib.php
  • tbl_indexes.lib.php
  • tbl_relation.lib.php
  • tbl_printview.lib.php
  • tbl_gis_visualization.lib.php
  • tbl_columns_definition_form.lib.php
  • Table.class.php

But the works on tbl_relation.lib.php and Table.class.php are not finished yet. Also the TableSearch.class.php will be covered in less than 2 days.

Outcomes in this week

libraries/tbl_chart.lib.php

PMA_getHtmlForTableChartDisplay:31
Function to get html for displaying table chart
Callers:
tbl_chart.php:136

libraries/tbl_indexes.lib.php

PMA_getNameAndTypeOfTheColumns:20
Function to get the name and type of the columns of a table
Callers:
tbl_indexes.php:50

PMA_handleCreateOrEditIndex:47
Function to handle the creation or edit of an index
Callers:
tbl_indexes.php:28

PMA_getSqlQueryForIndexCreateOrEdit:93
Function to get the sql query for index creation or edit
Callers:
tbl_indexes.php:51

PMA_prepareFormValues:185
Function to prepare the form values for index
Callers:
tbl_indexes.php:21

PMA_getNumberOfFieldsForForm:208
Function to get the number of fields for the form
Callers:
tbl_indexes.php:37

PMA_getFormParameters:236
Function to get form parameters
Callers:
tbl_indexes.php:39

PMA_getHtmlForIndexForm:264
Function to get html for displaying the index form
Callers:
tbl_indexes.php:53

libraries/tbl_columns_definition_form.lib.php

PMA_getFormsParameters:23
Get table related parameters from $_REQUEST object
Callers:
*libraries/tbl_columns_definition_form.inc.php:54*

PMA_getHeaderCells:315
Get header cells for showing table
Callers:
PMA_getHtmlForCreateNewColumn
at
libraries/normalization.lib.php:81
libraries/tbl_columns_definition_form.inc.php:76

PMA_getMoveColumns:396
Function for moving, load all available column names
Callers:
libraries/tbl_columns_definition_form.inc.php:68

PMA_getRowDataForRegeneration:417
Get row data for regenerating previous when error occurred
Callers:
PMA_handleRegeneration
at
libraries/tbl_columns_definition_form.lib.php:532

PMA_getSubmitPropertiesForRegeneration:497
Get submit properties for regenerating previous when error occurred
Callers:
PMA_handleRegeneration
at
libraries/tbl_columns_definition_form.lib.php:537

PMA_handleRegeneration:529
An error happened with previous inputs, so we will restore the data * to embed it once again in this form
Callers:
libraries/tbl_columns_definition_form.inc.php:105

PMA_getFormParamsForOldColumn:1400
Get form parameters for old column
Callers:
libraries/tbl_columns_definition_form.inc.php:165

libraries/tbl_gis_visualization.lib.php

PMA_GIS_modifyQuery
Returns a modified query iwht only the label column and spatical columns
Callers:
tbl_gis_visualization.php:70

PMA_GIS_visualizationResults
Formats a visualization for the GIS query results
Callers:
gis_data_editor.php:92
gis_data_editor.php:95
tbl_gis_visualization.php:109

PMA_GIS_saveToFile
Generate visualization for GIS query results and save it to a file
Callers:
tbl_gis_visualization.php:82

Notes on Table.class.php

I suggest that PMA_Table should be created by PMA_DatabaseInterface::getTable($db, $table) and the PMA_DatabaseInterface objecct should be injected as a parameter in constructor. And there will be some changes for the class:
These functions are used to handle errors or messages in an array, but we can use a throw statement for that

  • getLastError
  • getLastMessage

These functions are not used, so we can remove them:

  • set
  • get

These functions are static methods, and we needs to make them a member function

  • isView
  • isUpdatableView
  • analyzeStructure
  • isMerge
  • getStatusInfo
  • countRecords

These functions are not table related actions. They are UI related actions, therefore I’d like to move them into other classes (maybe PMA\Template?)

  • getUiProp
  • setUiProp
  • removeUiProp

The public $cache property should be moved into PMA_DatabaseInterface.

That’s all for this week! I will fix issues mentioned by my mentor in the PR 1642 as soon as possible.

The OOP & refactor project weekly report 1

Details on the “OOP and refactoring” project

As it mentioned in the phpMyAdmin GSoC 2015 idea list, the project is majorly about refactoring the code base to object-oriented. But I’d like to take one more step. I am going to build a basic template system first, which is helpful for our refactoring process.

Simple template system

As the HTML response are treated as PHP strings now, it’s pretty horrible to maintain such a long-long string variable. We can never know whether the HTML in it is correct or not until we execute it. So our first task is to build a basic template system. It is not necessary to apply the template system to the whole phpMyAdmin project immediately, but we can use it to manage codes that we needed to refactor this time easily.

You can see the template branch in my fork for more detail:

https://github.com/gzzhanghao/phpmyadmin/tree/template

It create a PMA_template method in libraries/template.lib.php and I’ve applied this feature to the designer module. Here is the commit information:

https://github.com/gzzhanghao/phpmyadmin/commit/214028c85d7278b4f76a4c4f9b99d1dcc0ae1d0e

The designer module should be much “clearer” now.

It should be noticed that the template system is isolated from phpMyAdmin current codebase. That is, the introduction of template system is painless and it just makes it easier for us to refactor codes. After refactoring, the HTML strings should be moved out from the Table related scripts and form template scripts.

Object-oriented design and refactoring

Currently our logical functions are separated in files with “.lib” and “.class” postfixes. But most of these files are poor designed and needs to be refactored. As the idea list specified, the project is pretty huge and it’s open-ended. So I’d like to separate the task into three steps:

Build a source code dependency graph for files involved in the refactoring project
It’s worthwhile to make a detailed plan before we start working. That is, for this project, we need to build a source dependency graph with details of functions we needs to refactor. A source dependency graph should contains the following things:

  1. Dependencies of the function
  2. Callers of the function
  3. Classification of the function
  4. A brief description on the function

Since the project is so huge that we can hardly handle all of files in this project, we should control our scope in Table related functionalities in the project. During this duration, we will also create template scripts to extract HTML strings from php codes.

Packaging the relative functions into classes

After we building the source code dependency graph, we can safely move the functions into classes. We can apply some object-oriented design pattern in this step, but it just only a little. Actually, all we need to do in this step is just putting the functions into the related classes, just like the way figured out in the Table class:

https://github.com/phpmyadmin/phpmyadmin/blob/master/libraries/Table.class.php

We can reserve some procedural features in this step for convenience.

Refining classes

After the classes have been built, we need to refine them with some OO design patterns. For the Table class we have talked above, we can package the $db and $table parameters into the class as private members for re-usability. And the ways to refactor the class structures is depended on the features of specified class.

To make a class well-designed, we can apply following few steps for each class:

  1. Encapsulate relative variables to keep the API concise
  2. Pick redundant parameters in member functions and make them be private members
  3. Extract duplicated pieces of code and put them into member functions

But when we refining these classes, we should always remember that it’s important to keep the code base simple and clean. So we must not over-design these classes. Basically I think the factory pattern is good enough for our project this time.

Deliverables

  1. A simple template system
  2. A source dependency graph for relative files
  3. Well-designed, and OOPed classes
Details on the “OOP and refactoring” project