AppendixC-OptionalTasks.html

Revision 273, 52.9 kB (checked in by hans, 1 year ago)
Merging recent 2.3 branch changes.
Property svn:executable set to ``* Property svn:keywords set to `author date id revision`

Line
1	<!--
2	-File $Id$
3	-License GNU FDL (http://www.gnu.org/copyleft/fdl.html)
4	-Copyright 2002, turing
5	-Author alex black, enigma@turingstudio.com
6	-->
7	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
8	<html xmlns="http://www.w3.org/1999/xhtml">
9	<head>
10	<title>Phing Guide - Optional Tasks</title>
11	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
12	<link rel="Stylesheet" rev="Stylesheet" href="../../css/Documentation.css" type="text/css" media="All" charset="iso-8859-1" />
13	</head>
14	<body>
15	<h1><a name="AppendixC-OptionalTasks"></a>Appendix C: Optional Tasks</h1>
16
17	<p>
18	This appendix contains a reference of all optional tasks, i.e. tasks that are not directly needed for
19	building projects, but can assist in various aspects of development and deployment.
20	</p>
21
22	<p> This reference lists the tasks alphabetically by the name of the classes that
23	implement the tasks. So if you are searching for the reference to the <code><phplint></code>
24	tag, for example, you will want to look at the reference of PhpLintTask. </p>
25
26	<h2><a name="DbDeployTask"></a>DbDeployTask</h2>
27	<p>The <em>DbDeployTask</em> creates .sql files for making revisions to a database, based on dbdeploy conventions centering around a changelog table in the database. See <a href="http://dbdeploy.com/documentation/getting-started/rules-for-using-dbdeploy/">rules for using dbdeploy</a> for more information. You will need a changelog table like so:</p>
28
29	<pre>CREATE TABLE changelog (
30	change_number BIGINT NOT NULL,
31	delta_set VARCHAR(10) NOT NULL,
32	start_dt TIMESTAMP NOT NULL,
33	complete_dt TIMESTAMP NULL,
34	applied_by VARCHAR(100) NOT NULL,
35	description VARCHAR(500) NOT NULL
36	)</pre>
37
38	<h3>Example</h3>
39	<pre>
40	<taskdef name="dbdeploy" classname="phing.tasks.ext.dbdeploy.DbDeployTask"/>
41
42	<dbdeploy
43	url="sqlite:${project.basedir}/data/db.sqlite">
44	userid="dbdeploy"
45	password="dbdeploy"
46	dir="${project.basedir}/data/dbdeploy/deltas"
47	/>
48	</pre>
49
50	<p>The above example uses a sqlite database and delta scripts located in dbdeploy/deltas in the project base dir.</p>
51
52	<h3>Attributes</h3>
53	<table>
54	<thead>
55	<tr>
56	<th>Name</th>
57	<th>Type</th>
58	<th>Description</th>
59	<th>Default</th>
60	<th>Required</th>
61	</tr>
62	</thead>
63	<tbody>
64	<tr>
65	<td>url</td>
66	<td>String</td>
67	<td>PDO connection url</td>
68	<td>n/a</td>
69	<td>Yes</td>
70	</tr>
71	<tr>
72	<td>userid</td>
73	<td>String</td>
74	<td>DB userid to use for accessing the changelog table</td>
75	<td>none</td>
76	<td>As required by db</td>
77	</tr>
78	<tr>
79	<td>password</td>
80	<td>String</td>
81	<td>DB password to use for accessing the changelog table</td>
82	<td>none</td>
83	<td>As required by db</td>
84	</tr>
85	<tr>
86	<td>dir</td>
87	<td>String</td>
88	<td>Directory containing dbdeploy delta scripts</td>
89	<td>none</td>
90	<td>Yes</td>
91	</tr>
92	<tr>
93	<td>outputfile</td>
94	<td>String</td>
95	<td>Filename in which deployment SQL will be generated</td>
96	<td>dbdeploy_deploy.sql</td>
97	<td>No</td>
98	</tr>
99	<tr>
100	<td>undooutputfile</td>
101	<td>String</td>
102	<td>Filename in which undo SQL will be generated</td>
103	<td>dbdeploy_undo.sql</td>
104	<td>No</td>
105	</tr>
106	<tr>
107	<td>deltaset</td>
108	<td>String</td>
109	<td>deltaset to check within db</td>
110	<td>Main</td>
111	<td>No</td>
112	</tr>
113	<tr>
114	<td>lastchangetoapply</td>
115	<td>Integer</td>
116	<td>Highest-numbered delta script to apply to db</td>
117	<td>999</td>
118	<td>No</td>
119	</tr>
120	</tbody>
121	</table>
122
123	<h2><a name="CoverageMergerTask"></a>CoverageMergerTask</h2>
124	<p>The CoverageMergerTask merges code coverage information from external sources with an existing code coverage database.</p>
125
126	<p>The format of the code coverage files is expected to be identical to:
127
128	<pre>
129	file_put_contents('/www/live/testcases/coverage.data', serialize(xdebug_get_code_coverage));
130	</pre>
131
132	<h3>Supported Nested Tags</h3>
133	<ul>
134	<li>fileset</li>
135	</ul>
136
137	<h3>Example</h3>
138	<pre>
139	<coverage-merger>
140	<fileset dir="/www/live/testcases">
141	<include name="*/.data"/>
142	</fileset>
143	</coverage-merger>
144	</pre>
145
146	<h2><a name="CoverageReportTask"></a>CoverageReportTask</h2>
147	<p>The CoverageReportTask formats a coverage database into a framed HTML report using XSLT.
148
149	<h3>Attributes</h3>
150	<table>
151	<thead>
152	<tr>
153	<th>Name</th>
154	<th>Type</th>
155	<th>Description</th>
156	<th>Default</th>
157	<th>Required</th>
158	</tr>
159	</thead>
160	<tbody>
161	<tr>
162	<td>outfile</td>
163	<td>String</td>
164	<td> The location for the intermediate XML file. </td>
165	<td>coverage.db</td>
166	<td>Yes</td>
167	</tr>
168	</tbody>
169	</table>
170
171	<h3>Supported Nested Tags</h3>
172	<ul>
173	<li>report
174	<h3>Attributes</h3>
175	<table>
176	<thead>
177	<tr>
178	<th>Name</th>
179	<th>Type</th>
180	<th>Description</th>
181	<th>Default</th>
182	<th>Required</th>
183	</tr>
184	</thead>
185	<tbody>
186	<tr>
187	<td>styledir</td>
188	<td>String</td>
189	<td> The directory where the stylesheets are located. </td>
190	<td>n/a</td>
191	<td>Yes</td>
192	</tr>
193	<tr>
194	<td>todir</td>
195	<td>String</td>
196	<td> The directory where the files resulting from the
197	transformation should be written to. </td>
198	<td></td>
199	<td>Yes</td>
200	</tr>
201	</tbody>
202	</table>
203	</li>
204	</ul>
205
206	<h3>Example</h3>
207	<pre>
208	<coverage-report outfile="reports/coverage.xml">
209	<report todir="reports/coverage" styledir="/home/phing/etc"/>
210	</coverage-report>
211	</pre>
212	<h2><a name="CoverageSetupTask"></a>CoverageSetupTask</h2>
213	<p>The CoverageSetupTask prepares a database which can be used to gather code coverage information for
214	unit tests. The code coverage tasks use the <a href="http://www.xdebug.org/" target="_blank">Xdebug</a> extension.</p>
215
216	<h3>Attributes</h3>
217	<table>
218	<thead>
219	<tr>
220	<th>Name</th>
221	<th>Type</th>
222	<th>Description</th>
223	<th>Default</th>
224	<th>Required</th>
225	</tr>
226	</thead>
227	<tbody>
228	<tr>
229	<td>database</td>
230	<td>String</td>
231	<td>The location for the coverage database. </td>
232	<td>coverage.db</td>
233	<td>Yes</td>
234	</tr>
235	</tbody>
236	</table>
237
238	<h3>Supported Nested Tags</h3>
239	<ul>
240	<li>classpath</li>
241	<li>fileset</li>
242	</ul>
243
244	<h3>Example</h3>
245	<pre>
246	<coverage-setup database="./reports/coverage.db">
247	<fileset dir="classes">
248	<include name="*/.php"/>
249	</fileset>
250	</coverage-setup>
251	<phpunit2 codecoverage="true">
252	<batchtest>
253	<fileset dir="src">
254	<include name="Test.php"/>*
255	</fileset>
256	</batchtest>
257	</phpunit2>
258	</pre>
259
260	<h2><a name="IoncubeEncoderTask"></a>IoncubeEncoderTask</h2>
261	<p>The <em>IoncubeEncoderTask</em> executes the <a href="http://www.ioncube.com" target="_blank">ionCube</a> encoder (for either PHP4 or PHP5 projects).</p>
262
263	<p>For more information on the meaning of the various options please consult the ionCube <a href="http://www.ioncube.com/USER-GUIDE.pdf" target="_blank">user guide</a>.</p>
264
265	<h3>Example</h3>
266	<pre><ioncubeencoder
267	binary="true"
268	copy=".ini config/"
269	encode="*.inc licenses/license.key"
270	encrypt=".tpl .xml"
271	encrypt="more"
272	fromdir="files"
273	ignore=".bak RCS/ ~ docs/"
274	ioncubepath="/usr/local/ioncube"
275	keep="docs/README"
276	licensepath="mylicense.txt"
277	optimize="max"
278	passphrase="mypassphrase"
279	phpversion="4"
280	targetoption="replace"
281	todir="encoded"
282	withoutruntimeloadersupport="true">
283	<comment>A project encoded with the ionCube encoder.</comment>
284	</ioncubeencoder>
285	</pre>
286
287	<h3>Attributes</h3>
288	<table>
289	<thead>
290	<tr>
291	<th>Name</th>
292	<th>Type</th>
293	<th>Description</th>
294	<th>Default</th>
295	<th>Required</th>
296	</tr>
297	</thead>
298	<tbody>
299	<tr>
300	<td>allowedserver</td>
301	<td>String</td>
302	<td>Restricts the encoded files to particular servers and/or domains. Consult the IonCude documentation for more information.</td>
303	<td>none</td>
304	<td>No</td>
305	</tr>
306	<tr>
307	<td>binary</td>
308	<td>Boolean</td>
309	<td>Whether to save encoded files in binary format (default is ASCII format)</td>
310	<td>false</td>
311	<td>No</td>
312	</tr>
313	<tr>
314	<td>copy</td>
315	<td>String</td>
316	<td>Specifies files or directories to exclude from being encoded or encrypted and copy them to the target directory (separated by space).</td>
317	<td>none</td>
318	<td>No</td>
319	</tr>
320	<tr>
321	<td>encode</td>
322	<td>String</td>
323	<td>Specifies additional file patterns, files or directories to encode, or to reverse the effect of <em>copy</em></td>
324	<td>none</td>
325	<td>No</td>
326	</tr>
327	<tr>
328	<td>encrypt</td>
329	<td>String</td>
330	<td>Specify files or directories (space separated list) that are to be encrypted.</td>
331	<td>none</td>
332	<td>No</td>
333	</tr>
334	<tr>
335	<td>expirein</td>
336	<td>String</td>
337	<td>Sets a period in seconds (s), minutes (m), hours (h) or days (d) after which the files expire. Accepts: <em>500s</em> or <em>55m</em> or <em>24h</em> or <em>7d</em></td>
338	<td>none</td>
339	<td>No</td>
340	</tr>
341	<tr>
342	<td>expireon</td>
343	<td>String</td>
344	<td>Sets a YYYY-MM-DD date to expire the files.</td>
345	<td>none</td>
346	<td>No</td>
347	</tr>
348	<tr>
349	<td>fromdir</td>
350	<td>String</td>
351	<td>Path containing source files</td>
352	<td>none</td>
353	<td>Yes</td>
354	</tr>
355	<tr>
356	<td>ignore</td>
357	<td>String</td>
358	<td>Set files and directories to ignore entirely and exclude from the target directory (separated by space).</td>
359	<td>none</td>
360	<td>Yes</td>
361	</tr>
362	<tr>
363	<td>ioncubepath</td>
364	<td>String</td>
365	<td>Path to the ionCube binaries</td>
366	<td>/usr/local/ioncube</td>
367	<td>No</td>
368	</tr>
369	<tr>
370	<td>keep</td>
371	<td>String</td>
372	<td>Set files and directories not to be ignored (separated by space)./td>
373	<td>none</td>
374	<td>No</td>
375	</tr>
376	<tr>
377	<td>licensepath</td>
378	<td>String</td>
379	<td>Path to the license file that will be used by the encoded files</td>
380	<td>none</td>
381	<td>No</td>
382	</tr>
383	<tr>
384	<td>nodoccomments</td>
385	<td>String</td>
386	<td>Omits documents comments ( /** ... */ ) from the encoded files.</td>
387	<td>none</td>
388	<td>No</td>
389	</tr>
390	<tr>
391	<td>obfuscation-key</td>
392	<td>String</td>
393	<td>The obfuscation key must be supplied when using the obfuscate option</td>
394	<td>none</td>
395	<td>No</td>
396	</tr>
397	<tr>
398	<td>obfuscate</td>
399	<td>String</td>
400	<td>The Encoder can obfuscate the names of global functions, the names of local variables in global functions, and line numbers. Use either <em>all</em> or any of <em>functions</em>, <em>locals</em> or <em>linenos</em> separated by a space.</td>
401	<td>none</td>
402	<td>No</td>
403	</tr>
404	<tr>
405	<td>optimize</td>
406	<td>String</td>
407	<td>Controls the optimization of the encoded files, accepts either <em>more</em> or <em>max</em></td>
408	<td>none</td>
409	<td>No</td>
410	</tr>
411	<tr>
412	<td>passphrase</td>
413	<td>String</td>
414	<td>The passphrase to use when encoding with a license file</td>
415	<td>none</td>
416	<td>No</td>
417	</tr>
418	<tr>
419	<td>phpversion</td>
420	<td>Integer</td>
421	<td>The PHP version to use</td>
422	<td>5</td>
423	<td>No</td>
424	</tr>
425	<tr>
426	<td>targetoption</td>
427	<td>String</td>
428	<td>Option to use when target directory exists, accepts <em>replace</em>, <em>merge</em>, <em>update</em> and <em>rename</em></td>
429	<td>none</td>
430	<td>No</td>
431	</tr>
432	<tr>
433	<td>todir</td>
434	<td>String</td>
435	<td>Path to save encoded files to</td>
436	<td>none</td>
437	<td>Yes</td>
438	</tr>
439	<tr>
440	<td>withoutruntimeloadersupport</td>
441	<td>Boolean</td>
442	<td>Wether to disable support for runtime initialization of the ionCube Loader</td>
443	<td>false</td>
444	<td>No</td>
445	</tr>
446	</tbody>
447	</table>
448
449	<h3>Supported Nested Tags</h3>
450	<ul>
451	<li>comment
452	<p>Custom text that is added to the start of each encoded file.</p>
453	</li>
454	</ul>
455
456	<h2><a name="IoncubeLicenseTask"></a>IoncubeLicenseTask</h2>
457	<p>The <em>IoncubeLicenseTask</em> executes the <a href="http://www.ioncube.com" target="_blank">ionCube</a> make_license program.</p>
458
459	<p>For more information on the meaning of the various options please consult the ionCube <a href="http://www.ioncube.com/USER-GUIDE.pdf" target="_blank">user guide</a>.</p>
460
461	<h3>Example</h3>
462	<pre><ioncubelicense ioncubepath="/usr/local/ioncube" licensepath="mylicense.txt" passphrase="mypassphrase">
463	<comment>A license file made with the ionCube encoder.</comment>
464	</ioncubelicense>
465	</pre>
466
467	<h3>Attributes</h3>
468	<table>
469	<thead>
470	<tr>
471	<th>Name</th>
472	<th>Type</th>
473	<th>Description</th>
474	<th>Default</th>
475	<th>Required</th>
476	</tr>
477	</thead>
478	<tbody>
479	<tr>
480	<td>ioncubepath</td>
481	<td>String</td>
482	<td>Path to the ionCube binaries</td>
483	<td>/usr/local/ioncube</td>
484	<td>No</td>
485	</tr>
486	<tr>
487	<td>licensepath</td>
488	<td>String</td>
489	<td>Path to the license file that will be generated</td>
490	<td>none</td>
491	<td>No</td>
492	</tr>
493	<tr>
494	<td>passphrase</td>
495	<td>String</td>
496	<td>The passphrase to use when generating the license file</td>
497	<td>none</td>
498	<td>No</td>
499	</tr>
500	</tbody>
501	</table>
502
503	<h3>Supported Nested Tags</h3>
504	<ul>
505	<li>comment
506	<p>Custom text that is added to the start of each encoded file.</p>
507	</li>
508	</ul>
509
510	<h2><a name="PDOSQLExecTask"></a>PDOSQLExecTask</h2>
511
512	<p>The <em>PDOSQLExecTask</em> executes SQL statements using PDO.</p>
513
514	<h3>Examples</h3>
515
516	<pre><pdo url="pgsql:host=localhost dbname=test">
517	<fileset dir="sqlfiles">
518	<include name=".sql"/>*
519	</fileset><br /></pdo>
520	</pre>
521
522	<pre><pdo url="mysql:host=localhost;dbname=test" userid="username" password="password">
523	<transaction src="path/to/sqlfile.sql"/>
524	<formatter type="plain" outfile="path/to/output.txt"/>
525	</pdo>
526	</pre>
527
528	<h3>Attributes</h3>
529	<table>
530	<thead>
531	<tr>
532	<th>Name</th>
533	<th>Type</th>
534	<th>Description</th>
535	<th>Default</th>
536	<th>Required</th>
537	</tr>
538	</thead>
539	<tbody>
540	<tr>
541	<td>url</td>
542	<td>String</td>
543	<td>PDO connection URL (DSN) </td>
544	<td>none</td>
545	<td>Yes</td>
546	</tr>
547	<tr>
548	<td>userid</td>
549	<td>String</td>
550	<td>Username for connection (if it cannot be specified in URL) </td>
551	<td>none</td>
552	<td>No</td>
553	</tr>
554	<tr>
555	<td>password</td>
556	<td>String</td>
557	<td>The password to use for the connection (if it cannot be specified in URL) </td>
558	<td>none</td>
559	<td>No</td>
560	</tr>
561	<tr>
562	<td>encoding</td>
563	<td>String</td>
564	<td>The database encoding.</td>
565	<td>none</td>
566	<td>No</td>
567	</tr>
568	<tr>
569	<td>src</td>
570	<td>File</td>
571	<td>A single source file of SQL statements to execute.</td>
572	<td>none</td>
573	<td>No</td>
574	</tr>
575	<tr>
576	<td>onerror</td>
577	<td>String</td>
578	<td>The action to perform on error (continue, stop, or abort)</td>
579	<td>abort</td>
580	<td>No</td>
581	</tr>
582	<tr>
583	<td>delimiter</td>
584	<td>String</td>
585	<td>The delimeter to separate SQL statements (e.g. "GO" in MSSQL)</td>
586	<td>;</td>
587	<td>No</td>
588	</tr>
589	<tr>
590	<td>delimitertype</td>
591	<td>String</td>
592	<td>The delimiter type ("normal" or "row"). Normal means that any occurence of the delimiter
593	terminate the SQL command whereas with row, only a line containing just
594	the delimiter is recognized as the end of the command.</td>
595	<td>normal</td>
596	<td>No</td>
597	</tr>
598	</tbody>
599	</table>
600
601	<h3>Supported Nested Tags</h3>
602	<ul>
603	<li>transaction
604	<p>Wrapper for a single transaction.</p>
605	</li>
606	<li>fileset
607	<p>Files containing SQL statements.</p>
608	</li>
609	<li>formatter
610	<p>The results of any queries that are executed can be printed in different formats.
611	Output will always be sent to a file, unless you set the <em>usefile</em> attribute to <em>false</em>.
612	The path to the output file file can be specified by the <em>outfile</em> attribute; there is a default filename that
613	will be returned by the formatter if no output file is specified.</p>
614	<p>There are three predefined formatters - one prints the query results in XML format,
615	the other emits plain text. Custom formatters that
616	extend phing.tasks.pdo.PDOResultFormatter can be specified.</p>
617	<h3>Attributes</h3>
618	<table>
619	<thead>
620	<tr>
621	<th>Name</th>
622	<th>Type</th>
623	<th>Description</th>
624	<th>Default</th>
625	<th>Required</th>
626	</tr>
627	</thead>
628	<tbody>
629	<tr>
630	<td>type</td>
631	<td>String</td>
632	<td> Use a predefined formatter (either <em>xml</em> or <em>plain</em>). </td>
633	<td>n/a</td>
634	<td rowspan="2">One of these attributes is required. </td>
635	</tr>
636	<tr>
637	<td>classname</td>
638	<td>String</td>
639	<td> Name of a custom formatter class (must extend phing.tasks.ext.pdo.PDOResultFormatter). </td>
640	<td>n/a</td>
641	</tr>
642	<tr>
643	<td>usefile</td>
644	<td>Boolean</td>
645	<td> Boolean that determines whether output should be sent to a file. </td>
646	<td>true</td>
647	<td>No</td>
648	</tr>
649	<tr>
650	<td>outfile</td>
651	<td>File</td>
652	<td>Path to file in which to store result. </td>
653	<td>Depends on formatter</td>
654	<td>No</td>
655	</tr>
656	<tr>
657	<td>showheaders</td>
658	<td>Boolean</td>
659	<td>(only applies to plain formatter) Whether to show column headers.</td>
660	<td>false</td>
661	<td>No</td>
662	</tr>
663	<tr>
664	<td>coldelim</td>
665	<td>String</td>
666	<td>(only applies to plain formatter) The column delimiter.</td>
667	<td>,</td>
668	<td>No</td>
669	</tr>
670	<tr>
671	<td>rowdelim</td>
672	<td>String</td>
673	<td>(only applies to plain formatter) The row delimiter.</td>
674	<td>\n</td>
675	<td>No</td>
676	</tr>
677	<tr>
678	<td>encoding</td>
679	<td>String</td>
680	<td>(only applies to XML formatter) The xml document encoding.</td>
681	<td>(PHP default)</td>
682	<td>No</td>
683	</tr>
684	<tr>
685	<td>formatoutput</td>
686	<td>Boolean</td>
687	<td>(only applies to XML formatter) Whether to format XML output.</td>
688	<td>true</td>
689	<td>No</td>
690	</tr>
691	</tbody>
692	</table>
693	<h3>Examples</h3>
694	<pre><pdo url="pgsql:host=localhost dbname=test">
695	<fileset dir="sqlfiles">
696	<include name="*.sql"/