How to install phing

Some simple commands can make your life easier. First, you need to download the latest version of Phing. Feel free to download using the browser. If your script is there, or in any other temporary location, you need to move it to a definitive location. Feel free to store it in any other path. Moving the script to that location doesn't make it available everywhere or even executable. So, what make an script globally available?

SimpleSAMLphp is an open source application that implements SAML mechanisms and allows for the authentication system to be created as well as some administration tasks to be performed. The system is robust and battle tested, having been integral to the open source authentication systems for a number of years. The Luhn algorithm was created by Hans Peter Luhn and is a way of creating a simple checksum for a number.

This algorithm, also known as the mod 10 algorithm, is used in a wide variety of applications but is commonly associated with credit card numbers. If you look at the numbers on the front of your credit card the last digit on the right is the checksum.

An algorithm is done on the other numbers and if the checksum is the same then the number is considered valid. Outside of credit card numbers, the Luhn algorithm can be used to create a checksum on any number that you want to store. It is especially handy when you want to give users a number that they will be hand typing into a computer. The checksum helps spot any errors in typing in the number before that number is processed. The good thing about the Luhn algorithm is that it doesn't matter how long the number is so it will work with any kind of digit sequence.

I had an issue I was trying to debug today and needed a way to swap between different versions of composer. Composer is one of the few things that I install globally so it was locked at a particular version on the machine I was using.

There has been some significant changes between version 1 and version 2 and it isn't quite safe to use a composer 2 package on a platform that has composer 1 installed. As some projects I'm working on haven't been upgraded yet I needed a way to swap between versions whilst this work was being done. Therefore, if you have installed the appropriate driver you should also be able to reach many other DBMS.

For example, for a PostgreSQL database:. You should never hard-code sensitive data in your buildfile , you could use an unversioned property file instead. Also, be careful when using verbose or debug mode since you can expose sensitive data. The following suffixes case-insensitive are supported:. This condition is identical to the Available task, all attributes and nested elements of that task are supported, the property and value attributes are redundant and will be ignored.

Test two files for matching. Nonexistence of one file results in "false", although if neither exists they are considered equal in terms of content. This test does a byte for byte comparison, so test time scales with byte size. NB: if the files are different sizes, one of them is missing or the filenames match the answer is so obvious the detailed test is omitted. Phing was designed to be flexible and easily extensible.

Phing's existing core and optional tasks do provide a great deal of flexibility in processing files, performing database actions, and even getting user feedback during a build process. In some cases, however, the existing tasks just won't suffice and because of Phing's open, modular architecture adding exactly the functionality you need is often quite trivial.

In this chapter we'll look primarily at how to create your own tasks, since that is probably the most useful way to extend Phing. We'll also give some more information about Phing's design and inner workings.

There are three main areas where Phing can be extended: Tasks , Types , Mappers. The following sections discuss these options. Tasks are pieces of codes that perform an atomic action like installing a file. Therefore a special worker class hast to be created and stored in a specific location, that actually implements the job. The worker is just the interface to Phing that must fulfill some requirements discussed later in this chapter, however it can - but not necessarily must - use other classes, workers and libraries that aid performing the operations needed.

Extending types is a rare need; nevertheless, you can do it. A possible type you might implement is urlset , for example. In cases where the type is really only for a single task, you may want to just define the type class in the same file as the Task class, rather than creating an official stand-alone Type.

Creating new mappers is also a rare need, since most everything can be handled by the Appendix F, Core mappers. The Mapper framework does provide a simple way for defining your own mappers to use instead, however, and mappers implement a very simple interface. Before you are going to start to extend Phing let's have a look at the source layout. You should be comfortable with the organization of files witch in the source tree of Phing before start coding.

After you extracted the source distribution or checked it out from git you should see the following directory structure:. Table 6. The basic applications phing, configure as well as the wrapper scripts for different platforms currently Unix and Windows. Repository of all the classes used by Phing.

Documentation files. A set of testcases for different tasks, mappers and types. If you are developing in git you should add a testcase for each implementation you check in.

Currently there is no distinction between the source layout and the build layout of Phing. The directory layout shows the file tree that carries some additional files like the Phing website.

Later on there may be a buildfile to create a clean distribution tree of Phing itself. There are some file naming conventions used by Phing. Here's a quick rundown on the most basic conventions. Filenames consist of no more or less than two elements: name and extension. Files containing PHP code must end with the extension.

The name portion of the file must be named exactly like the class it contains. Buildfiles and configure rulesets must end with the extension.

We are using PEAR coding standards. If you have suggestions about improvements to Phing codebase, don't hesitate to let us know. PHP installations are typically quite customized -- e. This is performed by the init layer of Phing that uses a three-level initialization procedure. It basically consists of three different files:. At the first look this may seem to be unnecessary overhead.

Why three levels of initialization? The main reason why there are several entry points is that Phing is build so that other frontends e. This scripts are technical not required but provided for the ease of use. Imagine you have to type every time you want to build your project:. Indeed that is not very elegant. Furthermore if you are lax in setting your environment variables these script can guess the proper variables for you.

However you should always set them. The scripts are platform dependent, so you will find shell scripts for Unix like platforms sh as well as the batch scripts for Windows platforms. If you set-up your path properly you can call Phing everywhere in your system with this command-line referring to the above example :. This is basically a wrapper for the Phing class that actually does all the logic for you.

If you look at the source code for phing. Given that all the prior initialization steps passed successfully the Phing is included and Phing::startup is invoked by the main application script. It sets-up the system components, system constants ini-settings, PEAR and some other stuff. The detailed start-up process is as follows:. Phing defines a number of Exception subclasses for more fine-grained handling of Exceptions.

This section exists to explain -- or try -- how Phing "works". Particularly, how Phing proceeds through a build file and invokes tasks and types based on the tags that it encounters. These handler classes "handle" the tags that are found in the buildfile. Core tasks and datatypes are mapped to XML tag names in the defaults. If a tag is presented that doesn't match any expected tags, then ProjectHandler assumes it is a datatype and invokes the DataTypeHandler.

TargetHandler expects all tags to be either tasks or datatypes and invokes the appropriate handler based on the mappings provided in the defaults. We will start creating a rather simple task which basically does nothing more than echo a message to the screen. See [below] for the source code and the following [below] for the XML definition that is used for this task. This code contains a rather simple, but complete Phing task. It is assumed that the file is named MyEchoTask.

We'll explain the source code in detail shortly. But first we'd like to discuss how we should register the task to Phing so that it can be executed during the build process. The task shown [above] must somehow get loaded and called by Phing. Therefore it must be made available to Phing so that the buildfile parser is aware a correlating XML element and it's parameters. Have a look at the minimalistic buildfile example given in [the buildfile below] that does exactly this.

To register the custom task with Phing, the taskdef element line 5 is used. See Section B. Optionally, before the taskdef element, the includepath element adds a path to PHP's include path. This is of course only required if the mentioned path isn't already on the include path. You see that we pass the message that our task should echo to the screen via an XML attribute called "message".

And for fun, if the "reverse" attribute is set to a "truth-like" value, the message will be reversed when displayed. So we get "dlroW olleH" displayed instead! Now that you've got the knowledge to execute the task in a buildfile it's time to discuss how everything works. All files containing the definition of a task class follow a common well formed structure:. Arbitrary private or protected class methods.

Then include all other required system or proprietary classes. If you look at line 5 in [the source code of the task] you will find the class declaration. Furthermore there are some fine-grained rules you must obey when creating the classes see also,[naming and coding standards] :.

Your classname must be exactly like the taskname you are going to implement plus the suffix "Task". In our example case the classname is MyEchoTask constructed by the taskname " myecho " plus the suffix " task ".

However, it is encouraged that you use it this way. The task class you are creating must at least extend " Task " to inherit all task specific methods. The next lines you are coding are class properties. Most of them are inherited from the Task superclass, so there's not need to redeclare them.

Nevertheless you should declare the following ones yourself:. Always hard code the taskname property that equals the name of the XML element that your task claims.

Currently this information is not used - but it will be in the future. In the MyEchoTask example the coded properties can be found in lines 7 to Give you properties meaningful descriptive names that clearly state their function within the context. A couple of properties are inherited from the superclass that must not be declared in the properties part of the code. The next block that follows is the class's constructor.

It must be present and call at least the constructor or the parent class. Of course, you can add some initialization data here.

It is recommended that you define your prior declared properties here. As you can see in the XML definition of our task [see buildfile above] , line 9 there is an attribute defined with the task itself, namely "message" with a value of the text string that our task should echo. The task must somehow become aware of the attribute name and the value. Therefore the setter methods exist. For each attribute you want to import to the task's namespace you have to define a method named exactly after the very attribute plus the string "set" prepended.

This method accepts exactly one parameter that holds the value of the attribute. Now you can set the a class internal property to the value that is passed via the setter method. If this is not the case, throw a BuildException. In some cases, such as when you have three attributes and at least one of them should be set, you may want to check the attribute values inside the init or main method.

In our example the setter is named setMessage , because the XML attribute the echo task accepts is "message". It is now available to the task for further disposal. There is also another setter named setReverse. This helps keep our own code nice and simple. For example, you might be developing a task that would contain a nested "color" XML tag. In this instance a creator method named createcolor would be required. If the XML for the task and the subtag look like the above, the PHP code for it could look something like the following:.

It must be implemented even if it does nothing like in the example above. You can do init steps here required to setup your task object properly. After calling the Init-Method the task object remains untouched by the parser. Init should not perform operations related somehow to the action the task performs. The init method should return true or an error object evaluated by the governing logic.

If you don't implement init method, phing will shout down with a fatal error. There is exactly one entry point to execute the task. It is called after the complete buildfile has been parsed and all targets and tasks have been scheduled for execution.

From this point forward the very implementation of the tasks action starts. In case of our example a message imported by the proper setter method is Logged to the screen through the system's "Logger" service the very action this task is written for. The Log method-call in this case accepts two parameters: a event constant and the message to log.

For the more or less simple cases as our example all the logic of the task is coded in the Main method. However for more complex tasks common sense dictates that particular action should be swapped to smaller, logically contained units of code.

The most common way to do this is separating logic into private class methods - and in even more complex tasks in separate libraries. You should only create a standalone Type if the Type needs to be shared by more than one Task.

If the Type is only needed for a specific Task -- for example to handle a special parameter or other tag needed for that Task -- then the Type class should just be defined within the same file as the Task. For cases where you do need a more generic Type defined, you can create your own Type class -- similar to the way a Task is created. Type classes need to extend the abstract DataType class. Besides providing a means of categorizing types, the DataType class provides the methods necessary to support the " refid " attribute.

All types can be given an id, and can be referred to later using that id. In this example we are creating a DSN type because we have written a number of DB-related Tasks, each of which need to know how to connect to the database; instead of having database parameters for each task, we've created a DSN type so that we can identify the connection parameters once and then use it in all our db Tasks.

The TypedefTask provides a way to "declare" your type so that you can use it in your build file. Here is how you would use this type in order to define a single DSN and use it for multiple tasks. Of course you could specify the DSN connection parameters each time, but the premise behind needing a DSN datatype was to avoid specifying the connection parameters for each task. You must provide a setter method for every attribute you want to set from the XML build file.

It is good practice to also provide a getter method, but in practice you can decide how your tasks will use your task. Also important to note is that the getter method needs to check to see whether the current DataType is a reference to a previously defined DataType -- the DataType::isReference exists for this purpose. For this reason, the getter methods need to be called with the current project, because References are stored relative to a project.

The getRef task needs to be implemented in your Type. This method is responsible for returning a referenced object; it needs to check to make sure the referenced object is of the correct type i.

You can probably just copy this method from an existing Type and make the few changes that customize it to your Type. In some cases you may want to extend existing mappers e. Writing filename mappers is simplified by interface support in PHP5. Here's an example of a filename mapper that creates DOS-style file names. For this example, the "to" and "from" attributes are not needed because all files will be transformed. It returns true or false depending on whether the given file should be selected or not.

An example of a custom selection that selects filenames ending in. For example a custom condition that returns true if a string is all upper case could be written as:. Table A. Phing is script-safe - means that you can execute Phing and Configure within a automated script context. To check back the success of a Phing call it returns an exit code that can be captured by your calling script. The following list gives you details on the used exit codes and their meaning. This appendix contains a reference of all core tasks, i.

This reference lists the tasks alphabetically by the name of the classes that implement the tasks. Table B. This is a real example from the build file used to generate this book! The text may be in-line or be in a file. When the os attribute is specified, then the command is only executed when run on one of the specified operating systems.

The files of a number of Resource Collections — including but not restricted to FileSets, FileLists or DirSets — are passed as arguments to the system command. Changes the attributes of a file or all files inside specified directories. Right now it has effect only under Windows. Each of the 4 possible permissions has its own attribute, matching the arguments for the attrib command. FileSets or FileLists can be specified using nested fileset and filelist elements.

By default this task won't do anything unless it detects it is running on a Windows system. If you know for sure that you have a "attrib" executable on your PATH that is command line compatible with the Windows command, you can use the task's os attribute and set its value to your current os. Modify an existing reference by adding nested elements or re- assigning properties mapped as XML attributes.

This is an unusual task that makes use of Phing's internal processing mechanisms to reload a previously declared reference by means of the id attribute, then treats the declared augment element as though it were the original element. The AutoloaderTask includes autoload file to bootstrap all necessary components in Phing execution context.

It could be useful if build tools e. Here, AvailableTask first checks for the existence of either file or directory named test. And last it checks if extension foo is loaded, so the property foo. NB: the Available task can also be used as a condition, see conditions. When this task executes, it will set the specified property to the value of the last path element of the specified file. If file is a directory, the basename will be the last directory element.

If file is a full-path, relative-path, or simple filename, the basename will be the simple file name, without any directory elements. Make some target the extension of some defined extension point. It will make the list of targets dependencies of the extension point.

This target is useful when you want to have a target to participate in another build workflow which explicitly exposes an extension point for that kind of insertion. Thus the target to bind and the extension point to bind to are both declared in some imported build files. But directly modifying the target dependency graph of these external build files may have a side effect on some other project which imports them. This task helps to modify the target dependencies but only in your context.

For more informations, see chmod in the PHP Manual. Sets a property if a certain condition holds true - this is a generalization of Section B. If the condition holds true, the property value is set to true by default; otherwise, the property is not set.

You can set the value to something other than the default by specifying the value attribute. Conditions are specified as nested elements, you must specify exactly one condition - see conditions for a complete list of nested elements.

Copies files or directories. Files are only copied if the source file is newer than the destination file, or when the destination file does not exist. It is possible to explicitly overwrite existing files. CopyTask does not allow self copying, i. The destination the file is to be written to.

If you only want to specify a directory to copy to, use todir. Additionally, CopyTask supports Filesets, i. For more information, see Appendix D, Core Types -- pay particular attention to the defaultexcludes attribute.

Appendix F, Core mappers and Appendix E, Core filters are also supported by CopyTask , so you can do almost everything that needs processing the content of the files or the filename. Alters the default excludes for all subsequent processing in the build, and prints out the current default excludes if desired. Silently allow several fileset based tasks to operate on emacs backup files and then restore normal behavior.

Deletes a file or directory, or set of files defined by a fileset. If the file does not exist, do not display a diagnostic message or modify the exit status to reflect an error. This means that if a file or directory cannot be deleted, then no error is reported. This setting emulates the -f option to the Unix rm command. Default is false meaning things are verbose. The dependset task compares a set of sources with a set of target files. If any of the sources has been modified more recently than any of the target files, all of the target files are removed.

If any of the sources in the above example does not exist, all target files will also be removed. To ignore missing sources instead, use filesets instead of filelists for the sources. Runs phing's -diagnostics code inside phing itself.

This is good for debugging phing's configuration under an IDE. When this task executes, it will set the specified property to the value of the specified file or directory up to, but not including, the last path element. If the specified file is a path that ends in a filename, the filename will be dropped. If the specified file is just a filename, the directory will be the current directory. Note: This is not the same as the UNIX dirname command, which is defined as "strip non-directory suffix from filename".

Displays all the current properties in the project. The output can be sent to a file if desired. Report the current properties to the file "my. Echoes a message to the current loggers and listeners which means standard out unless overridden.

A level can be specified, which controls at what logging level the message is filtered at. The task can also echo to a file, in which case the option to append rather than overwrite the file is available, and the level option is ignored.

Executes a shell command. You can use this to quickly add a new command to Phing. However, if you want to use this regularly, you should think about writing a Task for it.

Causes the current build script execution to fail and the script to exit with an optional error message. Calculates either MD5 or SHA1 hash value of a file and stores the value as a hex string in a property and generates a checksum file.

Other popular algorithms like "crc32" or "sha" may be used with help of the algorithm attribute. Stores the size of a specified file in a property. The file size can be returned in different units. File size unit. Examples: M , G , T. The foreach task iterates over a list, a list of filesets , or both. If both, list and filesets , are specified, the list will be evaluated first. Nested filesets are evaluated in the order they appear in the task. This task doesn't have any attributes, the condition to test is specified by a nested element - see the conditions for a complete list of nested elements.

All three subelements are optional. Both are containers for Phing tasks. You may specify as may of these as you like, and the order they are specified is the order they are evaluated in.

On execution it will read another Phing file into the same Project. Functionally it is nearly the same as copy and pasting the imported file onto the end of the importing file.

The import task may only be used as a top-level task. This means that it may not be used in a target. If a target in the main file is also present in at least one of the imported files, the one from the main file takes precedence. This makes it easy to keep the same target name, so that the overriding target is still called by any other targets--in either the main or imported buildfile s --for which it is a dependency, with a different implementation.

This enables the new implementation to call the old target, thus enhancing it with tasks called before or after it. Imported files are treated as they are present in the main buildfile. This makes it easy to understand, but it makes it impossible for them to reference files and resources relative to their path.

Because of this, for every imported file, Phing adds a property that contains the path to the imported buildfile. With this path, the imported buildfile can keep resources and be able to reference them relative to its position. Additionally, the directory will be stored in phing.

Note that "builddocs" is not the filename, but the name attribute present in the imported project tag. If import file does not have a name attribute, the phing. Suppose your main build file called importing. This snippet however will resolve imported. The right way to use imported. This technique also allows imported. Additionally, ImportTask supports Filesets, i.

For more information, see Appendix D, Core Types. The given path can be prepended default or appended to the current include path, or it can replace the include path. The InputTask can be used to interactively set property values based on input from the console or other Reader. The LoadFileTask loads the contents of a text file into a single property.

Creates a directory, including any necessary but non-existent parent directories. Does nothing if the directory already exists. Moves a file or directory to a new file or directory. By default, the destination file is overwritten if it already exists. When overwrite is turned off, then files are only moved if the source file is newer than the destination file, or when the destination file does not exist. Source files and directories are only deleted if the file or directory has been copied to the destination successfully.

For further documentation, see Section B. Converts a path form for a particular platform, optionally storing the result into a given property. It can also be used when you need to convert FileList, FileSet, DirSet into a list, separated by a given character, such as a comma or space, or, conversely, e. Nested map elements can be specified to map Windows drive letters to Unix paths, and vice-versa. A single nested mapper element can be specified to perform any of various filename transformations.

Coverts a path to a fileset. This is useful if you have a path but need to use a fileset as input in a phing task. These properties are only set if properties of the same name have not been set outside the "phingcall" tag. When a target is invoked by phingcall , all of its dependent targets will also be called within the context of any new parameters. Note: the top level tasks of a project will always be executed!

In the example above, the properties property1 and foo are defined and only accessible inside the called target. This task calls another build file.

You may specify the target that is to be called within the build file. The base directory of the new project is set dependent on the dir and the inheritAll attribute. This is important to keep in mind or else you might run into bugs in your build. The following table shows when which value is used:. Stores the Phing version when used as task or checks for a specific Phing version when used as condition.

Stores the Phing version in the property phingversion if the current Phing version is 2. Otherwise the property remains unset. Sets the property phing-is-exact if Phing 2. Neither 2. Copies the value of a named property to another property. This is useful when you need to plug in the value of another property in order to get a property name and then want to get the value of that property name.

PropertyPromptTask is a simple task to read in user input into a property. If you need something more advanced, see the Section B. Performs regular expression operations on an subject string, and sets the results to a property. There are two different operations that can be performed:. It is important to note that when doing a "replace" operation, if the subject string does not match the regular expression, then the property is not set.

You can change this behavior by supplying the "defaultValue" attribute. This attribute should contain the value to set the property to in this case. Selects property names that match a given regular expression and returns them in a delimited list. With PropertyTask , you can define user properties in your build file. Several recorders can exist at the same time. Each recorder is associated with a file.

The filename is used as a unique identifier for the recorders. The first call to the recorder task with an unused filename will create a recorder using the parameters provided and add it to the listeners of the build.

All subsequent calls to the recorder task using this filename will modify that recorders state recording or not or other properties like logging level. Some technical issues: the file's output stream is flushed for "finished" events buildFinished, targetFinished and taskFinished , and is closed on a buildFinished event. The following build. The ReflexiveTask performs operations on files.

It is essentially a convenient way to transform using filter chains files without copying them. It is up to the user to ensure that relentless execution of the nested tasks is safe. At least one task must be specified. Replaces the occurrences of a given regular expression with a substitution pattern in a selected file or set of files. The ResolvePathTask turns a relative path into an absolute path, with respect to specified directory or the project basedir if no dir attribute specified.

This task is useful for turning a user-defined relative path into an absolute path in cases where buildfiles will be called in different directories. Without this task, buildfiles lower in the directory tree would mis-interpret the user-defined relative paths. Retry is a container which executes a single nested task until either: there is no failure; or: its retrycount has been exceeded. If this happens a BuildException is thrown.. A task for sleeping a short period of time, useful when a build or deployment process requires an interval between tasks.

Sort a delimited list of items in their natural string order. Note that the value and refid attributes are mutually exclusive, and the value attribute takes precedence if both are specified. Calls a given target for all defined sub-builds. This is an extension of Phing for bulk project execution. This task must not be used outside of a target if it invokes the same build file it is part of. An individual case to consider, if the value that is being switched on matches to value attribute of the case, then the nested tasks will be executed.