Development Environment
Maestro is a web application coded using the PHP Yii framework, with a MySQL-compatible back-end database. This page shows how to create a suitable Windows-based development environment for Maestro. However, it is only a suggestion and you are free to create your own environment based on your own specific needs and tastes. For example, although I'm generally coding Maestro using NetBeans on Windows, I test on a local virtual machine running FreeBSD.
Maestro code is managed using Git, a distributed version control system (DVCS). Git Extensions provides a convenient GUI-based interface to Git, which is a CLI application.
- Download and install Git Extensions. The Git Extensions installer includes and will also install msysgit (for low-level functionally) and KDiff3 (a three-way merge tool).
- In the Git Extensions installer "Select Components" dialog, select "Simple context menu (Registry based)" with "Git Bash Here" and "Git GUI Here" (for consistency with other users). In the Git installer, accept the default "Checkout Windows-style, commit Unix-style line endings" (typical for mixed environments).
- Launch Git Extensions and configure user information (Settings -> Settings, Global settings tab, User name, User email, Editor (e.g. notepad++.exe).
- Confirm ~\.gitconfig has ANSI encoding using Notepad++ (Encoding -> Convert to ANSI). Depending on the file system, Git Extensions may save ~/.gitconfig in UTF8 encoding and NetBeans may report the file as missing or unreadable. If this happens, check the encoding of ~/.gitconfig and convert it to ANSI encoding if necessary. See https://netbeans.org/bugzilla/show_bug.cgi?id=218793.
- To upgrade Git Extensions, first uninstall Git Extensions, Git and KDiff3, and then install the updated version of Git Extensions.
If you are checking in files to Git on a Windows development, set your Windows global Git config (~/.gitconfig) to ignore file mode changes (and also check the repository configuration to ensure that your global configuration will not be overridden by the repository configuration).
A subtle difference between a Unix file systems and Windows file system is the file mode. If the mode of a file is set to executable and committed to a Git repository in a Unix environment (e.g. shell script), then the repository cloned to a Windows environment, the file will be reported by Git in Windows as having been modified - based on its mode. This is because Windows and unix have different specifications for file mode, and the conversions necessary when moving files between systems. Committing the "modified" file in Windows and pushing the repository changes back to the Unix repository will result in the file mode no longer being executable.
Check global and local (repository) configs:
$ git config --global core.filemode $ cd maestro $ git config core.filemode
Set global and local (repository) configs to ignore file mode changes:
$ git config --global core.filemode false $ cd maestro $ git config core.filemode false
Many developers can't live without color-coded command-line output, but you may find (as I do) that less than perfect color vision combined with high ambient lighting and some screen glare results in a display that is essentially incompressible. To disable color-coded command line output from Git:
$ git config --global color.ui false $ git config --global color.diff false $ git config --global color.status false $ git config --global color.branch false $ git config --global color.interactive false
This section is for information, the Maestro .gitignore file is already configured as described here.
The Yii framework itself writes files during application execution that should not be stored in the Git repository. NetBeans also stores metadata in the application directory that should not be stored in the Git repository. The following .gitignore file will result in Git ignoring both Yii runtime and NetBeans metadata files, and also assumes .gitignore files were created in empty directories to be preserved (e.g. by specifying git when creating a new Yii skeleton app).
# temporary files *.bak # Yii framework assets/* !assets/.gitignore protected/runtime/* !protected/runtime/.gitignore protected/data/*.db
If you are using a different IDE than NetBeans, add the appropriate patterns to your user global ~/gitignore file (rather than modifying the Maestro project .gitignore).
Testing Maestro code requires a web server and database server, and XAMPP is an easy-to-use installer for Apache (web server) and MySQL (database server), and also includes the PHP server side language processor.
Restart Apache after making any changes to the Apache httpd.conf or PHP php.ini configuration files.
- Download and install XAMPP.
- Install to default location C:\xampp and configure XAMPP to run as administrator (Right-click XAMPP icon -> Properties -> Shortcut tab -> Advanced... -> Run as administrator). You can also install Apache and MySQL as system services if desired (i.e. always running).
- Add the XAMPP PHP and MySql utilities to your Windows command path for access in a Git Bash command shell (XAMPP correctly configures the Windows command shell started by the Shell button in the XAMPP Control Panel).
- My Computer -> Properties -> Advanced system settings -> Environment Variables -> User variables for xxx -> PATH "C:\xampp\;C:\xampp\php;C:\xampp\mysql\bin"
- Edit C:\xampp\php\php.ini and configure the PHP XDebug extension for unit testing and code coverage analysis.
zend_extension = "C:\xampp\php\ext\php_xdebug.dll" xdebug.remote_enable = 1 xdebug.remote_handler = "dbgp"
- Edit C:\xampp\php\php.ini and configure the PHP curl extension for functional testing using Selenium.
extension=php_curl.dll
- Install PHPUnit, PHPUnit_SkeletonGenerator, and PHPUnit_Selenium packages for PHPUnit testing. Use a Command Prompt shell started using the XAMPP Control Panel Shell button for PEAR to run correctly on Windows systems.
# pear channel-discover pear.phpunit.de # pear channel-discover components.ez.no # pear install pear.phpunit.de/PHPUnit # pear install phpunit/DbUnit # pear install phpunit/PHPUnit_SkeletonGenerator # pear install phpunit/PHPUnit_Selenium
If you are using a unix test or production server, PuTTY provides a secure terminal (command line) connection from a Windows system to a unix system. It is a free implementation of Telnet and SSH for Windows and Unix platforms, combined with an xterm terminal emulator. Utilities are also included for creating and managing ssh keys, required for pushing commits to the Maestro GitHub repository.
- Download and install PuTTY.
- Create a public/private ssh key pair using PuTTYgen for authenticating yourself
- Access the PuTTYgen utility (Start > All Programs > PuTTY > PuTTYgen)
- Create an SSH-2 RSA 1024 bit key pair and save the keys to your Windows "~/.ssh" directory. Although not required, you can encrypt your private key with a passphrase for added security.
- PuTTY private key: ~/.ssh/id_rsa.ppk ("Save private key" button)
- Public key: ~/.ssh/id_rsa.pub ("Save public key" button) This file is not used in the Maestro workflow, but is saved for potential future use.
- Create an OpenSSH authorized_keys file containing your public key
- Right-click on the key in the "Public key for pasting into OpenSSH authorized_keys file" area and select Select All, then right-click again and select Copy
- Open a text editor (e.g. Notepad), paste your public key from the Windows clipboard, and save as "authorized_keys" (no extension) in your Windows ~/.ssh directory.
- Export your private key in OpenSSH format for Git Bash and NetBeans, and save to your Windows "~/.ssh" directory .
- OpenSSH private key: ~/.ssh/id_rsa
NetBeans is a free IDE for developing PHP applications (among other languages, most notably Java). NetBeans can be configured for code completion and high-lighting, PHP and Yii framework pop-up documentation, and single-step debugging and variable viewing. It also includes interfaces to Git and MySQL.
NetBeans must be restarted after modifying its configuration. For more information on using NetBeans for Yii-based projects, see NetBeans IDE and Yii projects.
- Download and install the NetBeans IDE PHP Bundle.
- Configure tab behavior in the editor
- Open "Tools > Options > Editor" and Unselect "Expand tabs to spaces" and set "Number of Spaces per Indent" and "Tab Size" to 4.
Install Yii NetBeans plugin by accessing menu "Tools > Plugins > Available Plugins", and search for Plugin.
- "Selenium Module for PHP".
- "PHP Yii Framework"
- Go To Action / Go To View
- Code completion on the view file ($this means controller)
- New Yii Project wizard
- PHPUnit Test Init action
- Init Action : add file for code completion
- Hyperlink navigation to view file
NetBeans includes the Database Explorer, which lets you connect to databases and view their content. You can create, modify, and delete tables, columns, and indices in your databases directly from within NetBeans.
Create a database service for the local (XAMPP) MySQL server by accessing the Services window, right-click on Databases and register the local MySQL server.
NetBeans provides the following shortcuts for code completion and hinting:
- To show suggestions: Ctrl-Space
- To show Function parameters: Ctrl-P
- access the menu "File > Project properties > PHP Include Path", or
- right-click on maestro in the NetBeans Project window and select "Properties > PHP Include Path > Add Folder... "
Configure NetBeans to ignore yiilite.php to avoid doubled (and missing) documentation. Access menu Tools > Options > Miscellaneous > Files, and edit "Files Ignored by the IDE"
^(yiilite\.php|CVS|SCCS|....
For full code completion, it is also necessary to create yii.php in the application/protected/ directory.
Reference: http://www.yiiframework.com/wiki/453/phpstorm-netbeans-autocomplete-problem
Note that the Maestro code repo already includes yii.php.
class Yii extends YiiBase
{
/**
* Returns the application singleton or null if the singleton has not been created yet.
* @return CWebApplication the application singleton, null if the singleton has not been created yet.
*/
public static function app()
{
return self::app();
}
}
You can test code completion by typing Yii::app()->user->check<ctrl+space>.
To have code completion in view files, add the following PHPDoc statement at the head of the file (also include passed parameters as needed)
/* @var $this PostController */ /* @var $model Post */ $this->getSomeProValue(); // possible with code completion $model->author; // possible with code completion
For more information on PHPDoc style comments, see the example on PHPDoc.org.
For running functional tests and unit tests, the following project options must be configured.
- Access menu "File > Project properties > PHP Include Path" and add the PHPUnit framework "C:\xampp\php\pear\PHPUnit"
- Access menu "File > Project properties > Sources" and set "Test Folder" to "C:\xampp\htdocs\maestro\protected\tests"
- Access menu "File > Project properties > PHPUnit", select "Use Bootstrap", and set "Test Folder" to "C:\xampp\htdocs\maestro\protected\tests"
- Access menu "File > Project properties > PHPUnit", select "Use XML Configuration", and set "Use XML Configuration" to "C:\xampp\htdocs\maestro\protected\tests\phpunit.xml"
- Open "Tools > Options > PHP > Unit Testing" and set the path to the PHPUnit launch script file "C:\xampp\php\phpunit.bat".
- Also in "Tools > Options > PHP > Unit Testing", set the path to the PHPUnit skeleton generator script file "C:\xampp\php\phpunit-skelgen.bat"
- http://www.yiiframework.com/wiki/83/netbeans-ide-and-yii-projects/
- http://ratatouille90.wordpress.com/2012/11/26/setting-up-phpunit-with-xampp/
For code debugging, configure NetBeans to not stop at the first line when debugging (otherwise the debugger will always stop on the first line in the Yii bootstrap file instead of proceding to a breakpoint). Access menu Tools > Options > PHP > Debugging, and uncheck "Stop at First Line".
If you have manually created or edited .gitnore and NetBeans reports a Java error "can't read .../.gitignore", it may be due to .gitignore being in a non-ASCII format. Open .gitignore in Notepad++ and convert it to ANSI encoding if it isn't (Git Extensions may save .gitignore in UTF-8 format depending on the file system it is saved on).
Reference: http://www.yiiframework.com/wiki/83/netbeans-ide-and-yii-projects/
The GnuWin project provides a set of Win32-versions of GNU tools, such as coreutils (fileutils, sh-utils, stat, textutils), diffutils, findutils, gawk, grep, less, sed, tar, etc., which may be useful in development. Git-Extensions includes many of the GNU tools for use in a Git Bash terminal, but any missing but desired are likely available from the GnuWin project. Also, GnuWin project tools include man pages and other documentation not provided by Git-Extensions (the only help for tools included with Git-Extensions is that built in to each tool, e.g. "$ grep --help")
Notepad++ is a free programming file editor that is useful for viewing or editing individual files. It includes some features not in NetBeans (e.g. wrapping text blocks at 72 columns and converting between text file encodings and EOL conventions), and is handy for a lightweight editor when you don't want to wait for NetBeans to startup.
Pencil is a free utility for creating wireframe designs of graphical user interfaces (e.g. web applications).
MySQL Workbench is a free utility for managing MySQL servers and databases, as well as for ERD-type database design.
VirtualWin is a free virtual Windows desktop utility, enabling you to put different work onto different virtual desktops.
- Download and install VirtuaWin
- Configure hotkeys if desired for switching between virtual windows (right-click on the VirtualWin icon in the system tray > Setup > Hotkeys tab)
WinSCP is a file transfer application, providing an SFTP, SCP, FTPS, and FTP client integrated into one application for transferring files between a Windows host and secure SFTP or FTP server. It can also be used to browse directories and view or edit files on the server (with appropriate user permissions). WinSCP is bundled with PuTTY utilities Pagaent and KeyGen for creating and managing ssh keys.
Use the ssh keys you created when installing PuTTY.
- Download and install WinSCP.
- Start Pageant (either from the WinSCP installation "Start > All Programs > WinSCP > Key tools > Pagaent", or from the PuTTY installation), and load your private key (you will be prompted for the passphrase if used).
- Connect to a server using WinSCP and confirm you are authenticated automatically using your ssh key (you will still need to type your user name at the login prompt, but authentication will be done using your ssh key).
If you are using Windows for development with a unix Maestro server for testing, you may wish to "map a network drive" to the Windows-compatible file share on the Maestro server (a Maestro server is typically configured with Samba to provide a network file share for master files and document vaulting). The unix Maestro server can be running locally as a virtual machine on Windows, or separately.
Trust and TransparencyTM, MaestroTM, and The ERP for EngineersTM are used under license.