InfoPay v5 (IP5) Developers’ ManualUpdated 2014-02-10

Table of ContentsIntroduction.................................................................................................................................................3

Tools............................................................................................................................................................3

NetBeans.................................................................................................................................................3

ActiveCollab.............................................................................................................................................3

Git............................................................................................................................................................4

PuTTYgen.................................................................................................................................................6

Task Scopes.................................................................................................................................................8

Credentials and Access Controls..................................................................................................................8

Coding Standards.........................................................................................................................................8

PHP..........................................................................................................................................................8

Comments...........................................................................................................................................8

Errors and Exceptions..........................................................................................................................9

File Paths.............................................................................................................................................9

Naming Conventions...........................................................................................................................9

Code Style..........................................................................................................................................10

Code Libraries....................................................................................................................................10

JavaScript...............................................................................................................................................11

Code Style..........................................................................................................................................11

Code Libraries....................................................................................................................................11

Markup..................................................................................................................................................11

Codebase Layout.......................................................................................................................................11

Core.......................................................................................................................................................11

Frontend................................................................................................................................................12

Yii...............................................................................................................................................................12

Basics.....................................................................................................................................................12

File Locations.........................................................................................................................................12

Models and Repositories.......................................................................................................................12

Controllers and Actions.........................................................................................................................13

Widgets.................................................................................................................................................13

2

IntroductionVersion 5 represents an evolutionary leap for the InfoPay system. Engineered from the ground up for stability, maintainability, extensibility, and scalability, the system will help propel business growth for years to come.

In order to make this a reality, it is essential that code be clean, efficient, maintainable, and easy for other developers to read, understand, and modify. To help ensure this, a number of standards and practices need to be followed.

This manual serves as you guide to the principles, practices, methods, and procedures that govern the development of IP5. It also provides an introduction to the available tools and codebase layout to help you hit the ground running.

Tools

NetBeansNetBeans is the preferred editor for InfoPay v5 development. The IDE is freely available at http://www.netbeans.org. While you are not required to use NetBeans, it is strongly encouraged and is the only editor that we can officially support.

When creating a new project in NetBeans, be sure to check the “Put NetBeans metadata into a separate directory” checkbox on the second step and ensure that the “Sources Folder” is set to the “source” subdirectory of the “Metadata Folder”. This will keep your NetBeans project files out of version control. A video showing the steps involved is available at http:// REDACTED. Be sure to finish reading the manual for the correct repository locations, etc., as they may have changed since the video was created. Make sure that when you set up the upload location, you choose to upload manually (not on save). The “dev” path for SFTP uploads is “REDACTED”.

Note that the default editor formatting settings in NetBeans do not comply with the coding standards listed in this document. You will need to ensure that NetBeans is properly configured so that it does not replace tabs with spaces, places brackets correctly, etc. The Coding Standards section details the proper conventions.

ActiveCollabThe main project management tool for the InfoPay v5 project is ActiveCollab. All tasks will be assigned and monitored in AC, so it’s essential that all developers make optimum use of this resource.

Tasks are created by management with the label “DRAFT”. Tasks labeled as drafts are not finalized, and should not be started. Once the details are finalized, management will assign the task to a developer and change the label to “ASSIGNED”.

3

Once a story is assigned to you with the label “ASSIGNED”, you are free to start work on that task as soon as your previous tasks are completed. When you start work on a story, change the label to “INPROGRESS”. Once you’ve finished a task and committed / pushed your code, change the label to “DELIVERED” and add a comment indicating which Git branch contains your work on the task. A manager will then review your work and either approve it, or reject it with comments indicating what needs to be changed.

If you need to make additional changes after a task has been submitted but hasn’t been reviewed yet, please add a note to the task, indicating what changes you feel you need to make, and then wait for a response. Please do not make further changes after delivering a task without checking first, as a merge for deployment may already be in progress.

When one of your tasks is rejected, don’t be discouraged. It may mean that there were some problems in the code that need to be addressed, or it may just mean that the task’s creator forgot something, and needs you to take care of the oversight. Either way, read the comments, change the label back to “INPROGRESS”, and start the process again.

GitThe main codebase for InfoPay is stored in the IP5 Git repository located at ssh://REDACTED. When accessing the repositories, you’ll always use the username “REDACTED”. All developers should maintain local copies of the repository on which to work.

The Git workflow is as follows:

1. Clone the repository into the “sources” folder of your project. This creates a full local repository, as well as a working copy of HEAD. To clone in NetBeans:

a. Create your project first, and ensure the sources folder is empty (delete the “index.php” file that NetBeans creates automatically).

b. From the menu bar, select “Team” -> “Git” -> “Clone”c. Enter the proper repository address for the project you’re cloning, specifying the

username “git” and your Git private key, then click “Next”.d. Select all remote branches and click “Next”.e. For the “Parent Directory”, choose your project directory. For the “Clone Name” type

“source”. This will clone the repository into the source directory of your project. Ensure you’re checking out “master*” with remote name “origin”. Uncheck the “Scan for NetBeans Projects after Clone” box – you’ve already created your project, and the repository doesn’t contain project files. Finally, click “Next” and the repository will be cloned.

f. A video showing the steps for the main project is available at http:// REDACTED2. All development work will be done on branches, keeping “master” clean for deployment to the

live servers. Work for each task will be committed to its own branch. To create a new branch (when a task doesn’t already have a branch), right-click the project’s “Source Files” node and choose “Git” -> “Branch” -> “Create Branch”. Give the branch a name appropriate to the task

4

you’re working on, using upper camel-case. Ensure that “Revision” is “master” and click “Create”. Once the branch is created, you can switch to it by right-clicking the project’s “Source Files” node and selecting “Git” -> “Branch” -> “Switch To Branch”. Choose the branch you want to switch to, make sure that “Checkout as New Branch” is NOT selected, and click “Switch”. Any commits you make will now be on the selected branch. A video showing the steps to create and switch to a branch is available at http:// REDACTED

3. To commit in NetBeans, right-click the project’s “Source Files” node, and choose “Git” -> “Commit”. Provide a descriptive commit message indicating what you worked on. Make sure that Author and Committer are both set to “Firstname Lastname <youremail@example.com>" (without the quotes, of course). The email address should be the email address you use for work – your accucomcorp.com email address if you have one, or the email address you generally use for work-related communication otherwise. Click the “Commit” button to make the commit. Video: http:// REDACTED.

4. Commits in Git are to your local repository – you need to do a remote push to origin to upload your commits to the central repository. To do this in NetBeans:

a. Right-click the project’s “Source Files” node and select “Git” -> “Remote” -> “Push”.b. Select the preconfigured origin remote (this will be the location from which you cloned

the project) and click “Next”. c. For local branches, choose the branches you’ve worked on. Make sure that you don’t

select master – this will cause your push to fail, as master is a protected branch. d. On the final screen, ensure the branches you’ve worked on are selected and click

“Finish”. Your commits will be pushed to the central repository.e. Video: http:// REDACTED

5. To update your local repository from the central repository and merge changes, do a pull from origin.

a. Right-click the project’s “Source Files” node and select “Git” -> “Remote” -> “Pull”.b. Select the preconfigured origin remote (this will be the location from which you cloned

the project) and click “Next”. c. Choose all remote branches and click “Finish”. All commits made on the central

repository will be pulled into your local repository, and your working copy will be updated to with the latest changes.

d. Video: http:// REDACTED

There are a couple important principles concerning optimal use of Git:

1. Pull frequently – at least once per day. This ensures that you’re always working on the most recent code version and reduces your chances of creating conflicts.

2. Commit and Push regularly. In general, you should commit every time you complete a task, and at the end of every day. Push after each commit, so that your changes are reflected in the central repository.

5

3. It’s always a good idea to pull right before a push. This will ensure that you have any changes made by other developers merged into your working copy before committing. This greatly reduces the changes of encountering conflicts.

PuTTYgenPuTTYgen, which can be downloaded from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html, allows easy creation of SSH keypairs, which you’ll need for SFTP upload to the dev server and to access the central Git repositories. To create an SSH keypair, open PuTTYgen and follow the steps below:

Step 1: Make sure the proper options are selected. You need to create a 1024-bit SSH-2 RSA key.

Step 2: Generate the key.

Step 3: Move the mouse randomly in the empty area until the green bar extends all the way to the right.

6

Step 4: Copy the entire contents of the top text area, and email to brent@accucomcorp.com. This is your public key, which will be uploaded to the server.

Step 5: Choose a passphrase and save your private key in PuTTY key format. Your private key must remain a secret, and must never be shared with anyone.

Step 6: Export your private key in the format required by NetBeans. This will let you upload to and download from the server from within NetBeans.

7

Each developer will need 2 separate SSH keys – one for SFTP upload to the dev server, and one for Git access. Please be sure to name your private keys in such a way that you’ll be able to tell which is which. Please do not give the keys ambiguous names like 1 and 2. Use “sftp” in the name of one, and “git” in the name of the other. Email the public key for SFTP to brent@accucomcorp.com. You’ll upload your Git public key directly through GitLab.

Task ScopesWhen working on the InfoPay v5 system, it is critical to remember that several other developers are working on the same codebase, and that one developer’s task may depend on the completion of another developer’s tasks. Because of this, it is vitally important that all developers respect the scope of assigned tasks, and not make changes to other parts of the system without prior approval.

Changes made outside the scope of an assigned task have the potential to make other, established parts of the system unusable, and may unnecessarily interfere with the work of others. They also negatively impact the timeline of a task, which may delay other developers who are waiting for the completion of that task.

If you need a change that is outside the immediate scope of your assigned task, add a comment to the story explaining the change you need and why you need it. While awaiting a response, you should always attempt to continue working on the task as much as possible.

Credentials and Access ControlsAuthentication credentials, including usernames, passwords, SSH keys, auth tokens, etc. are assigned to an individual person, and must never be shared with others. Any attempt to subvert access controls, including use of another person’s credentials, is considered unauthorized access to the system, which is strictly forbidden.

Please use common sense with the machine you’re using for development, since it has access to our core systems. When you walk away from the computer, lock it so that access isn’t available to anyone walking past. For windows computers, holding the Windows key and hitting L will lock the computer – everything will keep running, but a password will be required to use the system.

8

Coding StandardsIn order to ensure efficiency and easy maintenance, it’s essential that all developers adhere to a common set of coding standards. The standards described in this section are intended to create a common ground so that all developers can easily read each other’s code, and to avoid certain inefficiencies.

PHP

CommentsComments must be used to document all code. It should be possible to determine how and why all code functions based solely on the code itself and the comments it contains. PhpDocumentor (http://www.phpdoc.org/docs/latest/index.html) style comments must be used to document every function, method, property, and class.

Each file’s docblock should contain at least one @author annotation, indicating the person who originally created the file. When you update a file that someone else has worked on, add a new author annotation with your own info. Author annotations should have the same format as Git author / committer lines.

For comments that are not intended for phpDocumentor, such as those documenting code within a function, start the comment with slashes (not a hash symbol) then a space, then the properly capitalized comment. Using proper English makes comments much more helpful to others.

Comments must not be used to store unused code. When code is no longer needed it should be removed completely. Since all code is stored in Git, it is possible to recover code that has been removed if it is needed again in the future.

Errors and ExceptionsErrors and exceptions should never be displayed to the end user in raw form. Raw messages must be properly logged for later review. If an error condition prevents normal operation of a page, a user-friendly error message should be displayed. This message should give the user basic information about whether or not they should retry the operation, but must not reveal any potentially sensitive information.

File PathsAvoid using full file system paths when referencing local files from PHP. These would be difficult to trace and update in case the project is redeployed to a different file system path.

It is also important to note that, when a particular file is executed, the current working directory may not be the directory containing that file.

The best practice for building file paths is to use the magic constant __DIR__, which will give the directory containing the current file.

9

Note that all files to which PHP must write need to be placed in the application’s runtime directory (./runtime), which can be retrieved from within the application by using:

Yii::app()->runtimePath;

PHP scripts cannot write within the application directory or the webroot.

Naming ConventionsAll identifiers should have intuitive names that reflect their content and purpose. Please check your spelling of identifiers – misspelling an identifier name is a sure way to create bugs later when someone else accidently uses the correct spelling. Identifier names must follow the following conventions:

Constants, including class constants, must be in all capitals (e.g. “ENCRYPTION_KEY”). Class Names must use camel case with the first letter capitalized (e.g. “EmailSearch”). Variable, property, function, and method names must use camel case with the first letter lower-

cased (e.g. “$orderTotal”, “getCustomerEmail()”).

Code Style Indents must use tabs, never spaces. Make sure you set this properly in your editor / IDE, as

many (NetBeans and Notepad++, in particular) will expand tabs to spaces automatically unless you set them not to. All code should be indented in BSD-Allman (http://en.wikipedia.org/wiki/Indent_style#Allman_style) style.

The opening bracket for code blocks must always be on its own line, indented to the same level as the function definition, conditional expression, etc.

All control structures must be implemented in standard syntax (using brackets to surround the code block) NOT the alternate syntax described at http://php.net/manual/en/control-structures.alternative-syntax.php.

Conditional code blocks must always use brackets, as described above, even if only one line. Conditional code must never be placed on the line with its conditional expression, or on the line below (which must contain the properly indented bracket and nothing else).

Boolean values and the null value must be typed in all capital letters (i.e. TRUE, FALSE, and NULL).

Blank lines should be used where they increase readability (e.g. between separate logical blocks), but should not be used excessively. One blank line is sufficient to distinguish between logical code blocks – don’t use more.

Strings should be enclosed by single-quotes unless using inline variable interpolation or escape sequences. String literals must never be left bare (unquoted).

Binary operators (e.g. “==”, “>”, “=”, etc.) should have a space to each side, separating the operator from the operands.

Unary operators (like “!” or “++”) should have no space between operator and operand. Logical operators must use the symbolic form (“&&” or “||”), not the textual form (“AND”,

“OR”). Note that these operators have different precedence and will behave differently in certain edge cases.

10

Function arguments must have a space following the comma separator. No other spaces may appear within the parentheses, except inside strings.

Code LibrariesCode libraries found on the internet can provide useful functions which can save time and effort. However, they can also introduce security vulnerabilities and create dependencies on code that is difficult to maintain. Because of this double-edged sword, all code found on the internet must be reviewed and approved by management before inclusion into the project code base. Unapproved libraries will not be merged for deployment, and tasks completed using unapproved libraries will not be accepted.

JavaScript

Code StyleJavaScript must use the same code style as PHP, except where the nature of the language mandates differences. As an additional exception, the opening curly bracket in JavaScript may be placed on the same line as the conditional expression or function signature – this is just JavaScript dogma, and there’s no point fighting it.

Code LibrariesAs with code libraries for PHP, all JavaScript code libraries must be reviewed and approved by management before inclusion in the project’s codebase.

The jQuery and jQuery UI libraries are pre-approved, and may be used on any page. Please use the Google CDN URLs for these libraries (see https://developers.google.com/speed/libraries/devguide#jquery) rather than serving them directly from our servers.

MarkupAll markup returned to the browser must be well-formed, valid XHTML 1.1, including XML declaration and doctype, and must pass validation against this standard, as determined by the W3C markup validation service at http://validator.w3.org.

Codebase LayoutThere are two important top-level folders in the IP5 codebase. The core application is stored in the “app” folder, and the frontend code and static files are stored in the “www” folder.

CoreThe core application files consist of REDACTED.

Classes in the REDACTED and REDACTED namespaces are designed to be separable from the rest of the application, and should have no dependencies outside of those namespaces, except for standard PHP extensions.

11

Classes that are tightly integrated into the system and cannot be readily separated for reuse are placed in the REDACTED namespace.

Test cases are placed in the REDACTED namespace. Unit tests go under REDACTED while functional tests go under REDACTED.

The placement of models and controllers is discussed in the section on Yii, while the placement of views is covered in the section on the Frontend.

FrontendThe frontend files consist of REDACTED.

REDACTED

Static files (e.g. images, JavaScript, and CSS) should be placed in logically-named directories in the frontend file structure. Resources that are specific to a given site should be placed under a subdirectory named for that merchant, while global resources should be places in directories named for the type of resource (e.g. “img”, “js”, or “css”).

Yii

BasicsYii (http://www.yiiframework.com) provides the MVC framework used by the IP5 application. The Definitive Guide to Yii (http://www.yiiframework.com/doc/guide/1.1/en/) provides a good introduction to the basics of Yii, but be aware that we’re using the framework in a somewhat unusual manner, so many of Yii’s conventions don’t apply to this project.

File LocationsOne aspect where our implementation differs from Yii’s documentation is the location of files. In particular, configuration, controller, model, and view files are not placed in the prescribed locations. REDACTED.

Models and RepositoriesAnother deviation is our use of “repository” classes to retrieve data from the database. In Yii’s standard active record implementation, a single model class is used for both retrieving and manipulating records in the database. In our implementation, models are used to manipulate individual records, while corresponding repository classes REDACTED are used to retrieve existing records from the database. All record retrieval logic must be kept within the appropriate repository classes, to ensure easy updating when changes are made to the database.

The ODM layer persists all public properties of a model to the database on save, and populates those same properties on retrieval. Private properties may be used in models, but these will not be persisted to the database.

12

Before making any changes or additions to the document models, email brent@accucomcorp.com and CC REDACTED with a link to the task you’re working on, and a description of the changes you feel are needed. After reviewing your request, we’ll provide guidance on how to proceed. This way we can ensure that we maintain an optimal database structure, including all necessary indexes, shard keys, etc.

Full documentation on the ODM layer is available at http://canni.github.com/YiiMongoDbSuite/xhtml_single/index.html.

Controllers and ActionsAs stated previously, controllers are placed in the namespace REDACTED. Because of this nonstandard placement, controllers must be mapped to URL paths in REDACTED.

Controller actions (http://www.yiiframework.com/doc/guide/1.1/en/basics.controller#action) are implemented as discrete classes, rather than methods within the controller. Actions for a given controller are placed in the namespace REDACTED, where CONTROLLERNAME is the (unqualified) class name of the controller. Again, this is a nonstandard placement which requires special treatment. Each controller must have a method “actions()” which returns an associative array. The array keys must be the controller-relative URL paths used to access the actions, and the values must be the fully-qualified class names of the action implementations. Note that existing controllers use an array of action names which is used in both the actions() method, and for applying access control filters.

WidgetsWidgets are components that are primarily for presentation, but which can contain some programming logic. They are created by the Engineering team to provide presentational logic that the UI team can use in creating views.

Widgets are placed in REDACTED and extend REDACTED. Widget classes themselves are not namespaced. This is to keep the usage syntax for the UI team as simple as possible.

Default widget views should be placed in Frontend under the folder REDACTED where WIDGETNAME is the class name of the widget. If a specific merchant theme needs to override the default view for a widget, the theme-specific view should be placed in REDACTED.

13