Gallery2:Eclipse Tutorial - Gallery Codex
Personal tools

Gallery2:Eclipse Tutorial

From Gallery Codex

Eclipse as IDE for Gallery 2

We can use (PHP/PDT)Eclipse for:

  • Syntax highlighting
  • Live syntax check
  • Subversion Integration
  • Database queries (Quantum DB)
  • Graphical debugging (setting break points etc) (not yet tested)
  • Integrated control of webserver and DB

Installation and Configuration

By default, Eclipse can't save files that have the .class extension because Eclipse was used for Java development where .class files are binary (Java byte-code) files. There are several solutions:

  1. Don't use .class as the extension for your PHP files -> no option for G2, Eclipse's problem is no reason to change that in G2
  2. Don't install the Eclipse SDK, instead install the Eclipse Platform, which is just a minimal Eclipse version without development tools, without debugging capabilities etc. Since the platform doesn't ship with the JDT plugin, it has no pre-defined, locked file associations for .class. Drawback: you won't be able to use the graphical debugger to debug PHP.
  3. Install the Eclipse SDK, but edit the org.eclipse.jdt.core_3.1.2/plugin.xml file to remove the file association of JDT with .class . Drawback: You'll probably have to remove your change from that plugin.xml if you want to do Java development with this Eclipse instance too.
  4. If you do Java and PHP development, install two Eclipse installations. One for Java, the other for PHP. Drawback: More maintainenance needed, especially when upgrading etc.
  5. Run a minimal Eclipse platform within a debugging session in Eclipse (Eclipse in Eclipse). The performance hit is minimal, but you can't debug PHP scripts either since you're editing PHP scripts still in a simple Eclipse platform.
  6. Use Eclipse 3.2.1 with PDT 0.7 and just switch off the Java Capability when editing in Gallery and back on when working with Java projects.

Working with PDT and .class Files

Install an Eclipse PDT all-in-one build from http://www.eclipse.org/pdt/.

Version 3.3.x

  1. Add *.class to Window > Preferences > General > Content Types > Text > PHP Content Type
  2. Add *.class to Window > Preferences > General > Editors > File Associations and select PHP Editor as the default

Version 3.2.1

The procedure here does all three things for *.class files:

  1. enables syntax highlighting
  2. enables loading/saving
  3. enables text compare

After having PDT installed and before starting to work with the Gallery project open Window->Preferences->General->Capabilities from within Eclipse. Press the 'Advanced' button. In the advanced dialog expand the 'Development' capability tree and disable 'Java Development'.

This will disable other development capabilities too (these depending on the Java capability). But the important point is: it will remove the binary interpretation of *.class files, which is locked by the Java Development Capability.

Eclipse: Disabling the Java Capability

Close the dialog with OK and switch to General->Content Types. Expand the 'Text' content type tree and click on 'PHP Content type'. In 'File Associations' you'll see the predefined PHP file types *.inc, *.php etc. Add the new file type '*.class'.

Eclipse: Adding *.class to the PHP Content types

Close the Preferences Dialog with OK and you are all set to work with Gallery *.class files.

When done with Gallery and before you start working with Java projects again, just do the reverse procedure:

  1. remove *.class from the 'PHP content type'
  2. switch back on all capabilities

Working with PHPeclipse and .class Files

Adding PHP Syntax Highlighting for .class Files

Now we need to tell Eclipse to use the PHP Editor of PHPeclipse to edit .class files:

1. Close Eclipse if its running
2. Open eclipse/plugins/net.sourceforge.phpeclipse_1.1.7/plugin.xml with a text editor
3. Search for all occurrences of php4 and add there class too. That is, for comma separated lists, just add ,class and for structures like
     <fileTypes
            type="text"
            extension="php4">
      </fileTypes>

just add

     <fileTypes
            type="text"
            extension="class">
      </fileTypes>

Of course you could just replace php4 with class globally since we don't use the .php4 extension anyway, but better keep it since you want to edit non-G2 or 3rd party libraries too.

4. Save the file and start eclipse with the -clean option to tell it to re-read all plugin.xml files.
 eclipse -clean (or on windows c:\program files\eclipse\eclipse.exe -clean)
5. In Window -> Preferences -> General -> Content Types -> Text -> PHP. Add .class to PHP
6. In Window -> Preferences -> General -> Editors -> File Associations. Add .class and add PHP Editor as default for .class.

At this point, you have PHP syntax highlighting etc. for .class files but you can't save .class files yet, instead you get a "Save failed: null" error when trying to save a changed .class file.

Solving the Problem with Saving .class Files

We need to remove the file association of Java with .class files, or at least unlock this association since you can't disable / remove locked settings in Eclipse.

1. Close Eclipse
2. If your org.eclipse.jdt.core_3.1.2 plugin is not a folder in eclipse/plugins/ but instead a jar file, you must first extract/unarchive org.eclipse.jdt.core_3.1.2.jar
 Download the Java SDK (e.g. for Java 1.4.2) from http://java.sun.com/j2se/1.4.2/download.html to
   get the jar (un)archiver
 create a folder with the name org.eclipse.jdt.core_3.1.2 in eclipse/plugins/
 move org.eclipse.jdt.core_3.1.2.jar into that folder
 jar -xf org.eclipse.jdt.core_3.1.2.jar (extract the jar in that folder)
 delete the org.eclipse.jdt.core_3.1.2.jar file, we don't need it anymore
3. Open eclipse/plugins/eclipse.jdt.core_3.1.2/plugin.xml in a text editor and change it as following (just commenting out a block)
 Replace:
 <content-type id="javaClass" name="%javaClassName" 
        priority="high"				
        file-extensions="class">        
        <describer
            class="org.eclipse.core.runtime.content.BinarySignatureDescriber">
            <parameter name="signature" value="CA, FE, BA, BE"/>
        </describer>
    </content-type>
  With:
  <!--    <content-type id="javaClass" name="%javaClassName" 
        priority="high"				
        file-extensions="class">        
        <describer
            class="org.eclipse.core.runtime.content.BinarySignatureDescriber">
            <parameter name="signature" value="CA, FE, BA, BE"/>
        </describer>
    </content-type>        -->
4. Save the file and start eclipse with the -clean option as described above

At this point you can save .class files in (PHP)eclipse! :) The file association between Java and .class has not only been unlocked, it has been completely removed.

Using Compare with .class Files

You need to "patch" eclipse/plugins/org.eclipse.compare_3.1.1/plugin.xml too if you want to use the compare plugin of Eclipse.

The compare plugin/editor is e.g. very usefull before committing to CVS/SVN to review changes for a descriptive commit message. The Eclipse compare editor is very powerfull, not only showing different lines, but also the difference inside the lines.

And in the CVS/SVN synchronize perspective it automatically compares 3-way, most usefull in case of conflicting changes, as you can also view the repository version you made your changes against.

  1. Close Eclipse and open eclipse/plugins/org.eclipse.compare_3.1.1/plugin.xml in a text editor.
  2. If your org.eclipse.compare_3.1.1 plugin is not a folder in eclipse/plugins/ but instead a jar file, you must first extract/unarchive org.eclipse.compare_3.1.1.jar similar as described above
  3. In section
<extension point="org.eclipse.compare.contentMergeViewers"> Remove ,class from the extension list:

Replace

           extensions="exe,class,dll,binary,zip,jar"

with

extensions="exe,dll,binary,zip,jar"
  1. Save the file and start Eclipse with the -clean option

Here is an example of the Eclipse compare editor opened from inside the CVS synchronizing perspective. A doubleclick on a file fetches the neccessary data from CVS and displays the differing lines, indicating incoming, outgoing and conflicting changes. Navigating with the yellow down arrow jumps first to a differing line, then from partial diff to diff inside the line.


Eclipse compare editor on a conflicting *.class file.

Configuring Eclipse for the G2 Coding Style

  • Window -> Preferences -> General -> Editors (or Workspace in Eclipse 3.2): Don't forget to configure Eclipse to use ISO-8859-1 as default locale when editing G2 files. This can also be set on a per-project basis, in the Info section of the project properties.
  • In the same window, set the New Text File Line Delimiter to Default. This will work with the svn:eol-style=native property in Subversion.
  • Set tab = 8 spaces (we indent by 4 spaces per indention level, and our tabs are 8 spaces long)
  • Window -> Preferences -> General -> Editors -> Text Editors: Set the tab width to 8 spaces
  • Window -> Preferences -> PHPeclipse Web Development -> PHP: Tab Width 8 spaces, Print Margin Column 100
  • Window -> Preferences -> PHPeclipse Web Development -> PHP -> Formatter: Line Splitting tab: Maximum line length 100
  • Window -> Preferences -> PHPeclipse Web Development -> PHP -> Formatter: Style tab: Disable 'Indention is represented by a tab' and set the tab width to 8 spaces

Also configure the external tools such that the syntax checker works etc:

  • Window -> Preferences -> PHPeclipse Web Development -> PHP External Tools: Set the external parser command (you must have PHP installed on the same computer)

Setting up CVS and creating your Gallery2 Project based on our sourceforge CVS Repository

  • Change the Eclipse CVS settings (Window -> Preferences -> Team -> CVS -> Ext Connection Method: Select "Use another connection method type to connect" and select in the drop-down extssh (reason: Eclipse only uses SSH in CVS with the extssh method, but cvs.sourceforge.net only accepts ext. So in your CVS connection, you choose ext as method, but by changing this setting in Eclipse you tell it to use internally extssh if ext is used in the connection)
  • Add the gallery CVS to your repository: Window -> Show View -> Other ... -> CVS -> CVS Repositories. There, right-click and choose New -> Repository Location. Host: cvs.sourceforge.net, Repository path: /cvsroot/gallery, User: your sf.net username, Password: you can leave it empty for now, Connection Type: ext and hit finish.
  • Now you can create a new PHPEclipse project: File -> New -> Project. PHP Project: name e.g. gallery2.
  • Finally use our CVS repository for this project: right-click on your gallery2 project, click Team -> Share Project. CVS -> Use Existing Repository Location, choose your ext:username@cvs.sourceforge:/cvsroot/gallery repository. In the next view "Enter Module Name" choose "Use an existing module", pick gallery2, click next. Pick the HEAD branch, then next. When it starts to synchronize, click abort since we don't have anything in our local repository the synchronization process has nothing to do and it doesn't really checkout from CVS.
  • Then right-click on your project -> Team -> Update. To get the files with an initial checkout.

Using SVN and creating your Gallery2 Project based on our sourceforge SVN Repository

Since Gallery 2 now uses SVN (Subversion) instead of CVS as its source code control system, it will help to have SVN support added to Eclipse. SVN support is not delivered with Eclipse by default (as CVS is) but there is the Subclipse Plugin readily available from the same people who developed SVN.

It isn't absolutely neccessary to install subclipse. You can go with the command line version of SVN (or TortoiseSVN if you are using Windows), and still use Eclipse to edit. Enable Refresh automatically in Preferences -> General -> Workspace (or refresh via the context menu in the navigator view after using the command line SVN).

And, if you decide to install and use the Plugin as documented here, you may also do some SVN jobs from the command line / TortoiseSVN and other jobs (probably most) from within Eclipse (though Sourceforge discourages mixed use of SVN clients on one and the same working copy! You are warned). The Subclipse plugin integrates nicely into Eclipse, similar to the excellent CVS team support.

Installing Subclipse

Just follow the detailed steps at the Subclipse Install Instructions up to the point where you are prompted to restart Eclipse. Be sure to really restart Eclipse and not to just apply changes!

After the Eclipse restart please first open Preferences -> Team -> SVN and verify, that the SVN interface JavaHL (JNI) is checked (as opposed to JavaSVN (Pure Java), because that is what I have tested and is guaranteed to be absolutely compatible to the command line version of SVN). Leave all other settings alone for now, until you know what they mean.

Next you should apply the G2 Developer SVN settings as documented at Gallery:Using_Subversion#Developer_Info and modify your subclipse config file accordingly.

Also see the hint about the infamous Error: Secure connection truncated and make sure to use the correct / NEW URL

 https://gallery.svn.sourceforge.net/svnroot/gallery/......

Checking out Gallery 2 from the Sourceforge SVN repository

To prepare a checkout of Gallery 2 from the repository:

  1. open the SVN Repository perspective: Window -> Open Perspective -> Other -> SVN Repository Exploring
  2. in the SVN Repository view create a new repository location: via context menu New -> Repository Location or toolbar Add SVN Repository
  3. in the dialog enter the location URL: https://gallery.svn.sourceforge.net/svnroot/gallery/trunk/gallery2 (note the https) and press Finish
  4. a new entry in the SVN Repository view appears, open the Properties for it and make sure, that Repository root url is set to https://gallery.svn.sourceforge.net/svnroot/gallery

You are now all set to check out the current/last version of Gallery 2 (the trunk). If you rather want to be able to / must switch between branches easily, you could instead enter https://gallery.svn.sourceforge.net/svnroot/gallery as the location URL in step 3.

The next steps do the actual checkout into a new PHP project. Eclipse puts new projects and thus the SVN working copy into your workspace by default. That is perfectly ok, to test G2 with your Apache on localhost you can easily set up an Alias to the projects location in the workspace. But you might prefer to create an external Eclipse project right in your htdocs area.

To check out the Gallery 2 trunk:

  1. if you have used the long URL above in step 3: choose Checkout in the context menu of the repository location.
  2. if you have choosen the short URL above in step 3: open the tree for the repository location, open the trunk path and choose Checkout in the context menu of the gallery2 path.
  3. in the Check out as dialog choose Check out as a project configured using the New Project Wizard, since we want to make the project a PHP project and may be don't want it to reside in the workspace. Press Finish.
  4. in the New Project wizard select PHP -> PHP Project, press Next >.
  5. give the project a name and either use the default location in the workspace or enter the file system path to a new directory elsewhere (e.g. in your htdocs tree). Press Finish.

The directory will be created, Eclipse switches to the PHP perspective and shows the new project in the navigator view. The checkout progresses, which will take some time. After the checkout Eclipse will do a workspace build, which will take some more time ... so get yourself a cup of coffee.

You can also look at an animated tutorial for the checkout (note: any URLs there are outdated, prepend 'gallery.' before 'svn.sourceforge.net').

Working with Subclipse

When the workspace is built, open the new project in the navigator and have a look. It looks like every other project (except for the [gallery/trunk/gallery2] annotation on the project name may be).

Dig deeper into the project and notice the decoration on every file name: it'll show the revision number, datetime and last author of the file (you can have similar decorations for folders too, see Window -> Preferences -> Team -> SVN -> Label Decorations in the Text tab).

Now do a dummy change (to be undone/reverted soon) to some source file deep in the hierarchy, say themes/matrix/templates/error.tpl. Open that file, notice the Smarty syntax highlighting and add a Smarty comment {* Dummy change to be reverted *} after </head> (in the same line). As soon as you save the file you'll notice a decoration (a white star in a dark square) in the lower right corner of the files icon and all the way up to the projects icon in the Navigator view, which reminds you of changes you've done locally.

Feel free to have a first look at the Team Synchronizing perspective: with your dummy change still in place open (on the project folder) the context menu Team -> Synchronize with Repository. Eclipse switches to the Synchronizing perspective and compares the whole project with the repository version. This again will take some time, but typically much less than the initial checkout. Most work is done locally comparing the working copy against the BASE revision (which is magically stored by SVN, the PRISTINE copy). Sooner or later you'll see all the differences: just one outgoing change in error.tpl. With some chance you'll see incoming changes too, when some commit from others has taken place since your checkout. Note, that synchronizing does NO HARM AT ALL to either the repository or your working copy. It is only a compare.

In the Synchronize view just double click the error.tpl. Instead of opening the file for simple editing Eclipse now opens the Compare Editor and highlights the first changed line. Look at the header center column: the arrow to the right indicates an 'outgoing' change. Click the yellow down arrow: the compare editor now jumps to the first difference in the changed line. You'll begin to love this advanced compare features soon, at last when you ever have to resolve a conflicting change!

Enough exploring, let's quickly undo the dummy change. Close the compare editor. From the context menu of error.tpl choose Revert, press OK in the dialog and note, that the 'outgoing' synchronize view is now empty. Switch back to the PHP perspective and note, that all decoration icons are gone, indicating, that you have a clean working copy.

Most things you can do with the command line SVN you can also do with Subclipse and often more comfortably. But since Subclipse is tightly integrated into Eclipse, similar to the CVS integration, be sure to have read the Subclipse docs (Help -> Help Contents then Subclipse) and make yourself familiar with the integration. If you are working with SVN for the first time you might also want to read the [SVN Book] for SVN concepts.

Some daily tasks (very short description) are:

  • PHP Navigator, project context menu: Team -> Update
    Use that to quickly get up to date, when you have no local changes or don't care about details of repository changes. Do this also before every attempt to commit any changes. It updates your whole working copy to the right revision. Else commit attempts may fail.
  • PHP Navigator, project context menu: Team -> Synchronize with Repository
    to be used, when you have local changes and/or care about changes done to the repository since last update. Eclipse will open the Team Synchronizing perspective, compares your working copy with the repository and shows all differences in the Synchronize view (see image above). Don't forget to update the whole project before attempting to commit anything (see last point), even if you have updated everything from the synchronizing perspective step by step!
  • Synchronize view, double click on a file:
    Opens the very comfortable Eclipse compare editor (see image above) where your working copy is compared to the HEAD revision in the repository (and optionally to the BASE revision, if you switch to the 3-way compare).
  • Synchronize view, file context menu: Show in Resource History
    Opens the History view, where you can inspect the commit history including the commit comment and other files participating in the atomic commit operation.

You naturally can work with only part of the project by selecting one or more individual files or directories in the PHP Navigator and opening the Team context menu for one of the selected items.

  • PHP Navigator, individual item(s) context menu: Team -> Commit or
    Synchronize view, individual item(s) context menu: Commit
    This commits all selected items in an atomic operation. If selected files ain't added to SVN before you get the opportunity to do so in the same operation.
  • PHP Navigator, individual item(s) context menu: Team -> Revert or
    Synchronize view, individual item(s) context menu: Revert
    Undoes all local changes for the items and reverts them to the BASE revision.
  • PHP Navigator, individual file/dir context menu: Team -> Create Patch
    Creates a unified diff for the item, that can be stored to the clipboard or filesystem.

Just enjoy.

A final note: as is the case with CVS you always can have more then one working copy of the SVN repository. This might help developers having to do different tasks at the same time, e.g. enhancing module A and at the same time having to fix a bug in a totally unrelated module B or even the core. Instead of mangeling both modifications in the same working copy and having to sort them out at commit time it is often more advisable to e.g. do the bug fix on a freshly checked out working copy. That way a simple commit on the bug fix working copy commits the right things automatically. Just update the other project to get the bug fix into that also.

Using Quantum DB

With the Quantum DB extention for eclipse you can browse your databases from within eclipse, query your db, copy data, etc.

You should have installed Quantum DB with PHPeclipse.

In this guide we assume you're using MySQL on Windows XP, but you should get it working on Linux and for other DBMS too.

We need to setup the ODBC datasource first:

  1. You need to install the MySQL ODBC driver: Get the installer from http://dev.mysql.com/downloads/connector/odbc/3.51.html and execute it
  2. Go to Start > Control Panel > Administrative Tools > Datasources (ODBC)
  3. Click on System-DSN and add a new datasource, of course you need to choose your newly installed MySQL driver. Data Source Name: enter anything, Description: anything, Server: localhost, User / Password: your mysql user/password, Database: choose your gallery2 database. And hit OK to save.

Now you can use this new ODBC datasource in Quantum DB in Eclipse.

  1. Start Eclipse and switch to the Quantum DB perspective
  2. In the Database bookmarks view, right-click and choose New Bookmark...
  3. Select the JDBC-ODBC driver and click Next
  4. Enter your DB username/password and enter the data source name that you entered in the ODBC DSN setup as Data Source. Click Next.
  5. Give this bookmark a name and hit Finish.

Now you can use it by double-clicking on your new bookmark (or right-click -> Connect)