PHPackages nlmdev/phingistrano-monkeypatch - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. nlmdev/phingistrano-monkeypatch ActiveLibrary nlmdev/phingistrano-monkeypatch =============================== phingistrano monkey patch v0.1.0(12y ago)03.1kPHP Since May 15Pushed 11y ago1 watchersCompare [ Source](https://github.com/nlmdev/phingistrano-monkeypatch)[ Packagist](https://packagist.org/packages/nlmdev/phingistrano-monkeypatch)[ RSS](/packages/nlmdev-phingistrano-monkeypatch/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)DependenciesVersions (2)Used By (0) Phingistrano [![project status](https://camo.githubusercontent.com/ba9b991a747c9d48b5c81f0dbb3029111a6288d605eb6a0b245b654e003adb8d/687474703a2f2f7374696c6c6d61696e7461696e65642e636f6d2f436f64654d656d652f5068696e6769737472616e6f2e706e67)](https://camo.githubusercontent.com/ba9b991a747c9d48b5c81f0dbb3029111a6288d605eb6a0b245b654e003adb8d/687474703a2f2f7374696c6c6d61696e7461696e65642e636f6d2f436f64654d656d652f5068696e6769737472616e6f2e706e67) ============================================================================================================================================================================================================================================================================================================================================================================================================================================================ [](#phingistrano-) A PHP utility for building and deploying projects based on Phing and other paralell technology. NEW! WINNT deployment is now possible ------------------------------------- [](#new-winnt-deployment-is-now-possible) Ive added a new deployment property called deploy.arch. By default it will have the value of UNIX, but if you change the value to WINNT then it will change the value of the directory separators in commands where windows architecture is relevant. Due to the difficulty in symlinking windows folders with MKLINK, the deployment procedure is slightly different in that the current deployment is a physical copy instead of a symlink. This was due to some problems with OpenSSH and Cygwin which was making symlinking too difficult. NEW! phpseclib library ---------------------- [](#new-phpseclib-library) Ive added the ability to use a "Pure PHP" implementation of ssh2 thanks to the PEAR seclib library. For those who have had trouble with using Phingistrano because of the SSH2 dependency, you may want to have a look. [README](#phpseclib) Table of Contents ----------------- [](#table-of-contents) - [Overview](#overview) - [Command line usage](#commandline) - [Installing Phing and dependencies](#dependencies) - [Adding Phingistrano to a project as a git submodule](#submodule) - [Creating a build file](#build) - [Symfony2 Helpers](#symfony2) - [The Modules](#modules) - [Deploy](#deploy) - [Rollback](#rollback) - [Test](#test) - [Version](#version) - [Sniff](#sniff) - [Docs](#docs) - [Gotchas](#gotchas) - [About](#about) Common build and deploy repository ---------------------------------- [](#common-build-and-deploy-repository) This is an attempt to keep all of our build utilities in a common centralized repository that can be loaded as a submodule. The hope is that we can add this submodule to any existing project and immediately use its build/deploy functionality, pending some property/configuration changes. Phingistrano tries to be flexible by loading it's individual components as modules by the Phing *importTask* task. This repository does not contain the main build.xml to use, but it does give an [example of what one might look like](https://github.com/CodeMeme/Phingistrano/blob/master/phingistrano/build.example.xml) . It's important to understand that by this paradigm, you must tailor your buid.xml to the project, and import these submodules as needed. If you need customized versions of individual components, you could simply override or use different tasks defined in your build.xml, or even better, [import a custom build.helpers.xml](https://github.com/CodeMeme/Phingistrano/blob/master/phingistrano/build.helpers.example.xml) . In the examples I've shown, the targets are just aggregated targets from within the modules, strung together with the *depends* attribute. If you look at how it's done, you will likely see how easy, clean and flexible this is. Command line usage ------------------ [](#command-line-usage) - phing help (lists the available targets in the project and modules) - phing \[ target \] executes a target in the main project - phing \[ module \].\[ target \] executes a target in a submodule Installing Phing and dependencies --------------------------------- [](#installing-phing-and-dependencies) This repository uses phing, git and several phing and php extensions which are required to use all of the features. I will try to outline how to get and install these dependencies. I'm using Ubuntu 10.10 as a dev machine but I've also done this on Fedora 13 and RHEL 6 with equal success. You may need to slightly tweak these directions to suit your environment but this should get you started. ### Git [](#git) Git is currently the only repository system supported by this package. ``` sudo apt-get install git ``` ### Phing is the interface [](#phing-is-the-interface) [Phing 2.4.5](http://phing.info/trac/wiki/Users/Download) ``` sudo pear channel-discover pear.phing.info sudo pear install phing/phing ``` ### PHP Codesniffer [](#php-codesniffer) ``` sudo pear install PHP_CodeSniffer-1.3.0a1 ``` I could not get phing 2.4.4 to work with this version (1.3.0.RC1) of phpcs. Phing seems to want to use the "-o" flag with phpcs and the error message suggest that 1.3.0.RC1 does not support that flag. Therefore I recommend using version PHP\_CodeSniffer-1.3.0a1 [PHP\_CodeSniffer-1.3.0a1](http://pear.php.net/PHP_CodeSniffer) ### PHPUnit [](#phpunit) [PHPUnit by Sebasian Bergmann](https://github.com/sebastianbergmann/phpunit/) The PEAR channel (`pear.phpunit.de`) that is used to distribute PHPUnit needs to be registered with the local PEAR environment. Furthermore, components that PHPUnit depends upon are hosted on additional PEAR channels. ``` pear channel-discover pear.phpunit.de pear channel-discover components.ez.no pear channel-discover pear.symfony-project.com ``` This has to be done only once. Now the PEAR Installer can be used to install packages from the PHPUnit channel: ``` pear install phpunit/PHPUnit ``` ### PHP Documentor [](#php-documentor) We use php documentor in our build routine to document our code. ``` sudo pear install --alldeps PhpDocumentor ``` ### VersionControl\_Git-alpha [](#versioncontrol_git-alpha) This tool needs an extended git library for phing ``` sudo pear install VersionControl_Git-alpha ``` Also included in the repo, these phing git extensions by Evan Kaufman: [Extended Git tasks](http://github.com/EvanK/phing-ext-gittasks) ### Pear mail extension [](#pear-mail-extension) ``` sudo pear install pear/Mail sudo pear install pear/Mail_Mime ``` SSH2 PHP Extension *OR* phpseclib Net\_SSH2 ------------------------------------------- [](#ssh2-php-extension-or-phpseclib-net_ssh2) Since the PHP ssh2 extension has been difficult to install, and for some people impossible to extend php due to system permissions, You can use this library, PHPs SSH2 extension or both. ### phpseclib Net\_SSH2 and NetSFTP [](#phpseclib-net_ssh2-and-netsftp) Ive tailored a custom ssh task for Phingistrano that will also use the Net\_SSH2 and Net\_SFTP classes from the [PEAR phpseclib library](http://phpseclib.sourceforge.net/documentation/net.html#net_ssh_dependencies). The one drawback that I've found about this library is that uploads can be *VERY* slow. If the upload speed becomes a problem for you, then I suggest looking into the direct strategy for deployment as it requires no uploading. You can install the [phpseclib](http://phpseclib.sourceforge.net/pear.htm) dependencies with the following commands: ``` sudo pear channel-discover phpseclib.sourceforge.net sudo pear install phpseclib/Net_SSH2 sudo pear install phpseclib/Net_SFTP sudo pear install phpseclib/Math_BigInteger sudo pear install phpseclib/Crypt_Random sudo pear install phpseclib/Crypt_Hash sudo pear install phpseclib/Crypt_TripleDES sudo pear install phpseclib/Crypt_RC4 sudo pear install phpseclib/Crypt_AES sudo pear install phpseclib/Crypt_RSA ``` ### SSH2 PHP Extension [](#ssh2-php-extension) This repo needs the php ssh2 extension. I have 2 sets of instructions for installing this depending on the operating system so only follow 1 set of instructions as it applies to the system you are on. ### Install ssh2 library on Fedora 13+ &RHEL 6+ [](#install-ssh2-library-on-fedora-13-rhel-6) ``` yum install libssh2-devel ``` ### Install ssh2 library on Ubuntu 10.10+ [](#install-ssh2-library-on-ubuntu-1010) ##### Install the PHP Bindings for libssh2 [](#install-the-php-bindings-for-libssh2) ``` sudo apt-get install libssh2-1-dev ``` ##### then download and install the ssh2 library with git [](#then-download-and-install-the-ssh2-library-with-git) ``` sudo apt-get install libssh2-php ``` ### SSH2 PHP Extension (all operating systems) [](#ssh2-php-extension-all-operating-systems) Once you've installed the SSH2 library, install the PHP extension with PECL ``` sudo pecl install channel://pecl.php.net/ssh2-0.11.2 ``` #### Configure extension [](#configure-extension) The ssh2 extension might not add itself to the php ini. I've found that I usually have to link it up manually. Adding Phingistrano to a project as a git submodule --------------------------------------------------- [](#adding-phingistrano-to-a-project-as-a-git-submodule) ``` git submodule add git@github.com:CodeMeme/Phingistrano.git vendor/Phingistrano git submodule init ``` This should automatically create a .gitmodules file for you. If not, you can create one manually with the following contents: ``` [submodule "vendor/Phingistrano"] path = vendor/Phingistrano url = git@github.com:CodeMeme/Phingistrano.git ``` ### To update the submodule [](#to-update-the-submodule) ``` git submodule update ``` (You should run this once upon sub-repository creation as well.) Creating a build file --------------------- [](#creating-a-build-file) The way this repository is used is that it's grafted into your project as a git submodule. In order to use the features of this project, you'll need to create a phing build.xml in your project root directory. This should be named build.xml. The content of your build.xml should be like this: ``` ``` The path to Phingistrano will vary depending on your installation. Possibly you could even add the Phingistrano library by pear, or however you want. ### required properties [](#required-properties) This Readme document outlines required properties for each module under heading "The Modules" For my example, I will show you how you should add the properties to your build file: ``` ``` ### Optional Properties [](#optional-properties) This is a list of properties available for the individual modules but not needed for successful execution. You can use these properties to configure your deployment, or leave them out if you accept the defaults. ``` ``` ### Importing the build submodule [](#importing-the-build-submodule) Now that you've got your build file, you need to import the modules. The build submodule comes with a main build xml that can be imported if you want to use all the modules. Imports should always be underneath the predefined properties to ensure that the properties in the modules can be overridden by your preferences. You can add it like this (vendor/Phingistrano is the path of how I set up my submodule): ``` ``` [I use the helpers file](https://github.com/CodeMeme/Phingistrano/blob/master/build.helpers.example.xml) to keep utility functions that aren't necessarily needed for building the project If you look at the build.helpers.example.xml file that I included in this repo, you can see that I'm storing targets that open a VPN tunnel, restart memcached, perform remote commands, etc... ### Cherrypicking modules [](#cherrypicking-modules) If you don't want to use all the modules in this repository, you could cherrypick them into your main build file by adjusting the path like this: ``` ``` **Warning** If you cherry pick the modules, you may have to put blank targets from each module in your main build file. For example if I used: ``` ``` deploy has targets which are namespaced like this: deploy.distributed, deploy.prepare, etc... In my main build file, I would need to create empty targets with those names so that the namespace will work. Like this: ``` ``` This is due to how phing handles namespaced targets. ### Main Targets [](#main-targets) In order to do things with Phing, your build.xml will need targets. These are the commands that you enter on the command line when you use phing. i.e : $phing \[ target \] ``` ``` ### Targets that assign properties [](#targets-that-assign-properties) At my work, we have multiple environments and repositories in which we use throught an application development cycle. In order to build different repositories on different environments we use targets that assign properties. For example: ``` ``` Then I add new targets under main targets that incorporate these property adding targets as a dependency: ``` ``` ### Example build.xml [](#example-buildxml) [my final build.xml](https://github.com/CodeMeme/Phingistrano/blob/master/build.example.xml) looks like this: ``` ``` The Modules ----------- [](#the-modules) For each module that you use, there are certain properties that may be required. In your main build file, you should control the modules with these properties. I will attempt to outline what the properties are and what they do. #### Global properties [](#global-properties) ``` ``` ##### phingistrano.dir [](#phingistranodir) This is the path to the location of your Phingistrano libraries. This is important due to how the modules work. With this value set, you can use one central phingistrano repository for all of your projects, possibly even install it via a Pear channel, or just keep the library in any place of your choosing. It is required, however, to set this value because modules no longer self resolve. ``` ``` ##### build.target [](#buildtarget) This is the folder that your build related media will appear. By default it creates and uses the folder: .build ``` ``` ### Deploy [](#deploy) - phing deploy.staging { deploys the users current branch to staging } - phing deploy.production { deploys master branch to production (always master) } - phing deploy.test { deploys the users current branch to test } #### Deploy Hooks [](#deploy-hooks) ##### postcache [](#postcache) Runs a target called "postcache" immediately as the cacheing is completed and before it wraps it into a tarball. This is useful in situations where you may need to run treatment scripts like the vendors script in Symfony2: ``` ``` ##### precache [](#precache) Runs a target called "precache" right before you enter in to the repository cacheing part of deploy. This is useful if there are certain treatments, specific to the project, that you need to run before the repository gets cached #### Deploy properties [](#deploy-properties) ``` ``` ##### deploy.history [](#deployhistory) By default, Phingistrano will keep every deployment if your project. If you do not want to limit the amount of back deployments simply do not set this value. If you would like to limit the number of back deployments, that Phingistrano will retain, you can do that with the deploy.history property. If you do not want to keep any back deployments, simply set the value to zero (not recommended). ``` ``` ##### deploy.arch [](#deployarch) deploy architecture of the deployment system. By default the value is "UNIX" but can be set to "WINNT" for deploying to windows architectures. This is only supported for Windows servers running OpenSSH with Cygwin. **ALERT**Setting the deploy.arch property to WINNT will change the deployment procedure in that the current deployment will be a physical copy instead of a symlink. there will still be a backlog of releases in the releases folder, the only thing that changes is that the symlink will be a physical copy of the specified release folder. ``` ``` ##### deploy.branch [](#deploybranch) deploy branch is the branch of your repository that will be used in the deployment the default value is "master" ``` ``` ##### deploy.user & deploy.password [](#deployuser--deploypassword) This is the user name and password of the ssh account that will be used during deployment. ``` ``` ##### deploy.path [](#deploypath) This is the path on the deployment server where your "releases" directory resides ``` ``` ##### deploy.repository [](#deployrepository) This property holds the address of your git repository. ``` ``` ##### deploy.log [](#deploylog) This is not the file name of your log. This is the logging directive that you can append to remote shell commands to manage the logging of your deployment. By default the deploy.log value is "2>&1 tee /your/deploy/path/deploy.log". This will make the output get sent to the terminal, but also get logged in the file: "/your/deploy/path/deploy.log" ``` ``` ##### deploy.servers [](#deployservers) This is a comma delimited list of the server IPs or host names in which you will deploy your build. Make sure that you can ssh to these servers and that the deploy.user is capable of logging in and writing to the deploy.path on all of these servers. If there is only 1 deployment server simply write the one IP or hostname. ``` ``` #### Defining a deployment strategy [](#defining-a-deployment-strategy) To define a deployment strategy, enter it's name for the value of the deploy.strategy property. A deployment strategy must be defined but distributed will be defined by default. ``` ``` #### Deploy strategies [](#deploy-strategies) There are two different deployment strategies: distributed and direct. ##### Distributed [](#distributed) This is the most basic strategy. This downloads or updates your git repository locally and creates a deployment tarball. The deployment tarball is uploaded to your designated deployment servers. ##### Direct [](#direct) This strategy uses very little bandwidth (good for large projects that take forever to upload). This downloads or updates your git respository directly on the deployment servers. A tarball is still created but is not uploaded. The cached copy is formatted and moved in place to your deployment directory. ##### Hybrid [](#hybrid) Hybrid strategy has been depreciated. It was too complicated to set up and had problems. If you are trying to run a hybrid strategy, the easiest way is to set up a distributed strategy on a remote server, and just trigger the phing target with a remote command in your local helpers file. ### Rollback [](#rollback) ``` ``` #### Command line usage [](#command-line-usage-1) - phing rollback.staging { rollsback to the most recent deployment before current} - phing rollback.production -Drollback.direction=forward { rolls production forward (reverse is default) } - phing rollback.getlist { displays a list of available deployments ranging from most recent to oldest identify the list as numbers 1-5 or whatever } - phing rollback.test -Drollback.selected=\[ #number 1-5 \] { selects a specific deployment from the list (if less than 2 it will be 1, if more than max it will be max) } ### Test [](#test) A result file of your unit testing will be found in the reports subdirectory of your build target directory. By default: /.build/reports/testsuites.xml ``` ``` #### test.bootstrap [](#testbootstrap) This property value will refer to a bootstrap file that your phpunit execution will rely on. If the file doesn't exist then the bootstrap will be created automatically, so don't worry about it if your project unit tests don't require bootstrapping. As long as this property is defind and phing can write to the directory, this bootstrap file will be created with an empty directive. ``` ``` #### test.dir [](#testdir) Will assign a directory for php unit to traverse looking for unit tests. At this time only one directory is supported. Set it to a higher directory if you can use multiple directories recursively. ``` ``` #### test.incpattern [](#testincpattern) The pattern of files to include when looking for unit tests. Defaults to the value in the example. At this time only one line of inclusion is supported. ``` ``` #### test.excpattern [](#testexcpattern) The pattern of files to exclude when looking for unit tests. At this time only one line of exclusion is supported. ``` ``` #### test.type [](#testtype) The format of the output from testing, can be xml, plain, clover, or brief. ``` ``` #### test.outfile [](#testoutfile) The format of the the name of the output file from the testing result. The default is testsuites.xml. ``` ``` ### Version [](#version) ``` ``` #### version.to and version.from [](#versionto-and-versionfrom) The version.to property is the email address which the notification will be sent to on a new version. version.from is the email address of who or what the mail will be sent from. ``` ``` ### Sniff [](#sniff) ``` ``` #### sniff.standard [](#sniffstandard) This will set the sniff standard for which PHP Codesniffer will use when it makes a pass over your code. This can be one of the commonly used standards like PEAR or Zend or it can be the path to a custom ruleset.xml file. ``` ``` Docs ---- [](#docs) ``` ``` #### docs.destdir [](#docsdestdir) This is the directory that your docs will be generated in. ``` ``` #### docs.target [](#docstarget) This should be a path to a folder that you may want the documentor to make a pass over ``` ``` #### docs.output [](#docsoutput) PHPDocumentor output format ``` ``` Symfony2 Helpers ---------------- [](#symfony2-helpers) Symfony2 is a great new php framework but during deployment, some complexity is added to make sure your application gets its needed dependencies and that the application is conditioned for perfect operation. Things like assetic, doctrine migrations, and caching may need some help. I've prepared this example file of how you can do the conditioning to your symfony 2 app during automated deployment. ### Add the Symfony2 helpers file to your main buld.xml by importing it just like a regular helpers file [](#add-the-symfony2-helpers-file-to-your-main-buldxml-by-importing-it-just-like-a-regular-helpers-file) ``` ``` ### add the post\_deploy routine to your deployment targets [](#add-the-post_deploy-routine-to-your-deployment-targets) ``` ``` ### inside the symfony2.helpers.xml [](#inside-the-symfony2helpersxml) #### Assigning symfony properties [](#assigning-symfony-properties) You will need to assign a property of the symfony environment. You may even need to assign other properties depending on what you're doing. This should help you along in the process. ``` ``` ##### Asserting properties for the right environment [](#asserting-properties-for-the-right-environment) Now when you need to augment the targets to perform the right environmental context, you just add the symfony.properties.stage, symfony.properties.test target to the depends attribute. This is exactly how Phingistrano does it in the main build paradigm. #### postcache [](#postcache-1) The symfony2 helpers file takes advantage of the new postcache hook in Phingistrano. "postcache" is used immediately after the deploy module creates it's "cached-copy". Running these targets in "postcache" ensures that you will have refreshed versions of your vendors folder once it creates the tarball for distribution. ``` ``` #### postdeploy [](#postdeploy) These are targets that will be run immediately after your deployment on all the servers defined for this environment. The best way to manage this "postdeploy" sequence is to aggregate all of your targets into the "depends" attribute. In this example I've created postdeploy targets for each additional environment context. This ensures that your properties get assigned based on what environment you're deploying to. ``` ``` #### migrate [](#migrate) This performs doctrine migrations on your application ``` ``` #### assetic\_dump [](#assetic_dump) This installs assets and performs an assetic dump. Bear in mind that symlinked assets in your tarball will have incorrect paths on your deployment server unless you install the assets on post deployment. This is because symfony uses only absolute paths in the asset install and has no option for relative paths. ``` ``` #### clear\_cache [](#clear_cache) This clears the cache, warms up the cache, and performs a cruicial directory permissions adjustment so that the webserver can read/write to your cache. This example assumes that the webserver user is in the same group as your directory owner/deployment user. Individual milage may vary depending on how your hosting environment is set up. ``` ``` \##Gotchas ## ### namespaced submodules won't work if a base target doesn't exist [](#namespaced-submodules-wont-work-if-a-base-target-doesnt-exist) With phing version 2.4, you have to have an empty target in your main build file that corresponds to your submodule target. This can be as simple as creating a target with the appropriate name: ``` ``` The ticket #620 has been completed by Matthias from Phing development and starting on Phing version 2.5 these empty targets will not be necessary. About ----- [](#about) This code was developed by Codememe. Codememe is: - *Eric Clemmons* - *Evan Kaufman* - *Jesse Greathouse* Special thanks to these technologies and those who product them: - Phing - Git - Github - PHPDocumentor - PHPUnit - PHP Codesniffer - SSH2 - PHP ### Health Score 28 — LowBetter than 54% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity16 Limited adoption so far Community12 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 81.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 4387d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/70876a0fe41b0ad0a298f6dd279a08b3c2e81e028905e088d715ba48bf0f160e?d=identicon)[nlmuser](/maintainers/nlmuser) --- Top Contributors [![jessegreathouse](https://avatars.githubusercontent.com/u/439733?v=4)](https://github.com/jessegreathouse "jessegreathouse (44 commits)")[![konstantin-burnaev-at-news](https://avatars.githubusercontent.com/u/6721810?v=4)](https://github.com/konstantin-burnaev-at-news "konstantin-burnaev-at-news (6 commits)")[![wizonesolutions](https://avatars.githubusercontent.com/u/344116?v=4)](https://github.com/wizonesolutions "wizonesolutions (2 commits)")[![nlmuser](https://avatars.githubusercontent.com/u/7588656?v=4)](https://github.com/nlmuser "nlmuser (1 commits)")[![sukhjit2](https://avatars.githubusercontent.com/u/7588676?v=4)](https://github.com/sukhjit2 "sukhjit2 (1 commits)") ### Embed Badge ![Health badge](/badges/nlmdev-phingistrano-monkeypatch/health.svg) ``` [![Health](https://phpackages.com/badges/nlmdev-phingistrano-monkeypatch/health.svg)](https://phpackages.com/packages/nlmdev-phingistrano-monkeypatch) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)