www.it-ebooks.info www.it-ebooks.info Integrating PHP Projects with Jenkins Sebastian Bergmann Beijing • Cambridge • Farnham • Köln • Sebastopol • Tokyo www.it-ebooks.info Integrating PHP Projects with Jenkins by Sebastian Bergmann Copyright © 2011 Sebastian Bergmann. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com. Editor: Julie Steele Production Editor: Jasmine Perez Cover Designer: Karen Montgomery Interior Designer: David Futato Illustrator: Robert Romano Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Integrating PHP Projects with Jenkins, the image of starlings, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information con- tained herein. ISBN: 978-1-449-30943-5 [LSI] 1315836072 www.it-ebooks.info Table of Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v 1. Build Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 The Example Project 2 Our First Build Script 2 2. Setting Up Jenkins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Installing the PHP Quality Assurance Toolchain 5 Installing Jenkins 6 3. Continuous Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Running Unit Tests During the Build 11 Creating a Jenkins Job 14 4. Continuous Inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 API Documentation 21 Software Metrics 22 Duplicate Code 24 Coding Standard Violations 26 Result Aggregation 29 Complete Build Script 30 5. Automating the Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 PHP Project Wizard 33 Template for Jenkins Jobs for PHP Projects 35 6. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Continuous Integration and Development Branches 37 Additional Testing 38 Continuous Deployment 40 iii www.it-ebooks.info Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 iv | Table of Contents www.it-ebooks.info Preface Why Continuous Integration? Most web applications are changed and adapted frequently and quickly. Their envi- ronment, for example the size and the behaviour of the user base, are constantly chang- ing. What was sufficient yesterday can be insufficient today. Especially in a web envi- ronment it is important to monitor and continuously improve the software quality not only when developing, but also when maintaining the software. The practice of Con- tinuous Integration is the solution of choice to achieve this goal. Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily—leading to multiple integrations per day. Each integration is verified by an automated build (in- cluding test) to detect integration errors as quickly as possible. —Martin Fowler Continuous Integration reduces the amount of repetitive processes the developers need to perform when building or deploying the software thus reducing the risks of late discovery of defects, producing low-quality software, lack of project visibility as well as lack of deployable software. Why Jenkins? At least as far as I know, Sebastian Nohn was the first to experiment with the continuous integration of PHP projects. Back in 2006 he described on his blog how to use Apache Ant and CruiseControl to set up a continuous build that invoked PHPUnit to run the unit tests of a PHP project. Soon thereafter, the developers of Mayflower GmbH started to build a quality assurance platform for PHP projects that was based on CruiseControl. It not only ran unit tests as part of the build loop but also static code analysis tools such as PHP_CodeSniffer to collect software metrics over time. This quality assurance platform gave Manuel Pichler the idea to start the phpUnder Control open source project. This was a set of patches for CruiseControl (which could v www.it-ebooks.info not be customized or extended through plugins) that added out-of-the-box support for PHP projects. phpUnderControl significantly lowered the barrier to entry for intro- ducing continuous integration into a PHP project but since it was based on Cruise- Control it was a nightmare from an operations point of view and not as customizable and flexible as one would like. The developers of Mayflower GmbH later refactored their quality assurance platform for PHP projects into a tool that can be used with arbitrary continuous integration servers. It was open-sourced under the name PHP_CodeBrowser. When the Java community started to migrate from CruiseControl to more modern continuous integration servers, I had a look at Hudson (as Jenkins was called back then) and tried it together with the PHP quality assurance toolchain. I was pleasantly sur- prised to find a product that was not only more convenient to use and more robust (from an operations perspective) than CruiseControl but to also meet a vibrant devel- opment community. Thanks to the plethora of plugins developed and maintained by this community, Jenkins supports building and testing virtually any project, including PHP projects. The PHP community has developed a wide range of quality assurance tools since 2006. Where Sebastian Nohn only ran PHPUnit tests with Apache Ant and CruiseControl, a typical continuous integration setup for a PHP project today also includes the detection of violations of a defined set of coding guidelines and the gathering of various software metrics as well as the generation of API documentation, for instance. Over the course of the last two years I have successfully set up continuous integration environments that are based on Jenkins for our customers. These development teams leverage Jenkins to monitor the various aspects of software quality throughout the lifecycle of their projects. This enables them to create, maintain and extend sustainable software of high quality with PHP. The result of this experience is a template for Jenkins jobs for PHP projects that I have released as an open source project. What's in This Book? This book covers everything you need to know in order to use Jenkins for the contin- uous integration of your PHP projects. Here is how the book is organized: Chapter 1 In this chapter you will learn how to use Apache Ant to automate your build. Chapter 2 This chapter explains how to set up Jenkins and install the PHP tools that are required to continuously integrate a PHP project. Chapter 3 This chapter shows how to create a job for a PHP project in Jenkins. vi | Preface www.it-ebooks.info Chapter 4 Building on the continuous integration environment that was set up in the previous chapter, you will learn in this chapter how to add static code analysis tools to the build for continuous inspection. Chapter 5 This chapter shows how the automated build and continuous integration of a PHP project can be simplified by using the PHP Project Wizard and the Template for Jenkins Jobs for PHP Projects. Chapter 6 This chapter concludes the book with a summary of the benefits of Continuous Integration and Continuous Inspection while providing an outlook of what you can implement in addition to the processes and techniques described in this book. This book makes the assumption that the reader is familiar with the concept of Con- tinuous Integration and the set of problems it aims to solve. [Duvall2007] and [Hum- ble2010] are recommended basic and further reading, respectively, on this topic. While this book explains how to install Jenkins and how to configure it for PHP jobs it does not cover topics such as authentication, for instance, that are impartial to the programming stack used. Furthermore, the assumption is made that Jenkins is installed in a UNIX environment. For Jenkins-related topics not covered in this book the reader is referred to [Smart2011]. The planning, execution, and automation of tests for the different layers and tiers of a PHP-based web application is also outside the scope of this book. [Bergmann2011] is an excellent resource on these matters. Finding Out More If you would like to find out more about Jenkins and PHP, and to get the latest updates, visit this book's companion website at http://jenkins-php.org/. This is also where the template for Jenkins jobs for PHP projects is maintained. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Preface | vii www.it-ebooks.info Constant width bold Shows commands or other text that should be typed literally by the user. Constant width italic Shows text that should be replaced with user-supplied values or by values deter- mined by context. This icon signifies a tip, suggestion, or general note. This icon indicates a warning or caution. Using Code Examples This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “ Integrating PHP Projects with Jenkins by Sebastian Bergmann. Copyright 2011 Sebastian Bergmann, 978-1-449-30943-5.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com. Safari® Books Online Safari Books Online is an on-demand digital library that lets you easily search over 7,500 technology and creative reference books and videos to find the answers you need quickly. With a subscription, you can read any page and watch any video from our library online. Read books on your cell phone and mobile devices. Access new titles before they are available for print, and get exclusive access to manuscripts in development and post feedback for the authors. Copy and paste code samples, organize your favorites, down- viii | Preface www.it-ebooks.info [...]... so: wget http://localhost:8080/jnlpJars /jenkins- cli.jar We can now install the plugins for Jenkins that are required to integrate PHP projects: java java java java java java java java java -jar -jar -jar -jar -jar -jar -jar -jar -jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar jenkins- cli.jar -s -s -s -s -s -s -s -s... http://github com/thePHPcc/bankaccount This is what the project structure looks like: ├── │ │ │ │ ├── ├── ├── │ │ └── build ├── phpcs.xml ├── phpmd.xml ├── src_autoload .php. in └── tests_autoload .php. in build.xml phpunit.xml.dist src ├── autoload .php └── tests ├── autoload .php └── • The build directory contains the XML configuration files for PHP_ CodeSniffer (phpcs.xml) and PHPMD (phpmd.xml) as well... as well as customized templates for phpab, the PHP Autoload Builder PHP_ CodeSniffer and PHPMD are static analysis tools for PHP code and are covered in Chapter 4 where we discuss Continuous Inspection • build.xml is the Apache Ant build script that is used to build the project • phpunit.xml.dist is the PHPUnit configuration file for the project If phpunit.xml or phpunit.xml.dist (in that order) exist... that orchestrates other targets The phpab target uses the task to invoke the aforementioned PHP Autoload Builder to generate the autoloader code The two tasks are equivalent to calling phpab on the command-line like so: phpab output src/autoload .php template build/src_autoload .php. in src phpab output tests/autoload .php template build/tests_autoload .php. in tests Invoking Ant in the directory... duplicated code in a PHP project • PHP_ Depend is a tool for static code analysis of PHP code that is inspired by JDepend 5 www.it-ebooks.info • phpmd (PHP Mess Detector) allows the definition of rules that operate on the raw data collected by PHP_ Depend • phploc measures the scope of a PHP project by, among other metrics, means of different forms of the Lines of Code (LOC) software metric • PHP_ CodeBrowser... manually install Jenkins into a directory of your choice The following steps detail how Jenkins can be installed on a UNIX system into the / usr/local /jenkins directory: mkdir /usr/local /jenkins cd /usr/local /jenkins wget http://mirrors .jenkins- ci.org/war-stable/latest /jenkins. war Using the web application archive (WAR) from the URL above we install an "older but stable" release of Jenkins The Jenkins developers... wonderful people without whom this book would not have been possible: simply because there would have been no tools to write about These people are Kohsuke Kawaguchi (creator of Jenkins) , Greg Sherwood (creator of PHP_ CodeSniffer), Manuel Pichler (creator of PHP_ Depend and PHPMD), Elger Thiele (creator of PHP_ CodeBrowser), and Volker Dusch who co-maintains the template for Jenkins jobs for PHP projects Thank... in JUnit format that PHPUnit produces The following two plugins are not required to integrate PHP projects with Jenkins The Git plugin is required to interact with Git repositories and the Green Balls plugin customizes Jenkins to use a green ball instead of a blue ball to signify a successful build java -jar jenkins- cli.jar -s http://localhost:8080 install-plugin git java -jar jenkins- cli.jar -s http://localhost:8080... suffix=" .php" >src src/autoload .php 11 www.it-ebooks.info Invoking phpunit without any parameters in the project directory (where the phpunit.xml.dist configuration file resides) will result in PHPUnit running the tests the way we set it up in the configuration We can now add a target to our build.xml script that invokes PHPUnit... build script Example 4-2 The phploc build target for PHPLOC In the above, we let PHPLOC write its data to a CSV file The data from that file can be plotted using Jenkins' Plot plugin As . www.it-ebooks.info www.it-ebooks.info Integrating PHP Projects with Jenkins Sebastian Bergmann Beijing • Cambridge • Farnham • Köln • Sebastopol • Tokyo www.it-ebooks.info Integrating PHP Projects. files for PHP_ CodeSniffer (phpcs.xml) and PHPMD (phpmd.xml) as well as customized templates for phpab, the PHP Autoload Builder. PHP_ CodeSniffer and PHPMD