# this is the text which will end up within readme.pdf, when processed
# by readme.php.
#
# the syntax being used is fairly obvious:
#
# a line starting with '#' is a comment or a directive
# 1<title>  is a first level heading (text is 'title')
# 2<heading> is a second level heading (text is 'heading')
# "#NP" starts a new page
# "#C" starts a code section (put this on a line by itself
# "#c" end the code section
# "#X" and "#x" surround a block which will be executed as php code.
#
# <b></b> <i></i> can be used within the text with gleeful abandon

1<Introduction>

This class is designed to provide a <b>non-module</b>, non-commercial alternative to dynamically creating pdf documents from within PHP.
Obviously this will not be quite as quick as the module alternatives, but it is surprisingly fast, this demonstration page is almost a worst case due to the large number of fonts which are displayed.
There are a number of features which can be within a Pdf document that it is not at the moment possible to use with this class, but I feel that it is useful enough to be released.

The bulk of this document will describe the major calls to the class, the readme.php file (which will create this pdf) should be sufficient as an introduction.

Note that this document was generated using the demo script 'readme.php' which came with this package.

1<Changes>

2<version 007>

This is it - the james bond version - though all similarity ends with the name, but there are some funky new features and a few bug fixes.

The ezTable features have been extended, it is now possible to define the justification of the individual columns, and to specify colum widths as well as the width of the entire table.

You can now have <b>extra fonts!</b>. It is possible to add type 1 postscript fonts, or TrueType fonts. Though note that for the postscript font you have to have both a .pfb file and a .afm file - but there are free products out there which can convert a .pfa to a .pfb. Also to use a TrueType file you have to have a corersponding .afm file as this is required to specify the character widths - luckily there is a program which will generate one from a ttf file.

Bugfixes:
- fix the open font command so that the font file can be in the same directory.
- fix a bug with full justification, a space was being left at the end of each line - the justification now lines up much better.
- added some binary characters near the start of the pdf file, this is so that transfer programs will recognise it as binary.
- adjusted addTextWrap so that a text angle can now be supplied.
- have found that the reasona that jpeg file loading was not working for a lot of people is that if magic_quotes_runtime is set on in the php.ini file, then the file read is not binary safe. Adjusted the code to turn that option off before the read, then on again afterwards - there is at least one report of it working much better now.
- added the missing code to specify the xPos of a table - this was documented in the last version, but someone forgot to code it.


2<version 006>

Still more bug fixes of course, but also some improved functionality.

It is now possible to use &lt;b>&lt;/b>&lt;i>&lt;/i> markers within the text stream to do the obvious functionality. This depends on 'font families' being set up, which are described later.

The table functionality within ezPdf has been enhanced so that the width of a table can be specified and the cell contents will be wrapped to fit.

There is some trial functionality to allow the specification of adjusted character maps, this does mean that this version will have to re-create your 'php_<font>.afm' files, but it will do it automatically on first use, <b>but make sure you have the adobe .afm files in the directory and that the web-server has write access</b>, alternatively download the new ones.

Also there has been a slight attempt to tidy the code a little, and improve the documentation. This is partly in preparation for this project to be put into SourceForge, as it will be immediatly following this release.

2<version 005>

Contains a few bug fixes from 004, and the addition of the capability to draw arbitrary Bezier curves, and ellipses at arbitrary angles.

2<version 004>

This release includes a certain amount of functionality which should have been in 003. The enhancements are:
- page numbering easily done within ezpdf, they can be started and stopped on any page, uses an arbitrary template for the format, and can be set to start numbering pages from a given number.
- can now pass content-disposition through to the headers, for what it is worth
- having the 'Accept-Ranges' header set is optional, and off by default - seemed to cause problems.
- lines can now have their width, dash patterns, join types and endings set.
- there is now a reopenObject function which will allow adding content to previous objects, as long as the id has been stored. This function will also now work on pages, and the newpage() function now returns an id so that these can be accessed. 
- the first page of course does not return an id, so there is a getFirstPageId() function to find that one.

2<notes from version 003>

This is the document accompanying version 003 of this pdf class, the significant changes in this class version are:
- Creation of the ezpdf class, an extension to the base class to make life simpler.
Inclusion of compression within the content streams, code from Andrea Gagliardi (thanks).
- A new image function which will include a jpeg file straight from the file, so image inclusion without using GD.
- An extra content header, might improve life on some browsers (thanks John Arthur).


1<Use>

It is free for use for any purpose (public domain), though we would prefer it if you retain the notes at the top of the class containing the authorship, and feedback details.

Note that there is no guarantee or warranty, implied or otherwise with this class, or the extension.

1<Extensions>

In order to create simple documents with ease a class extension called 'ezPdf' has been developed, at the moment this includes auto page numbering, tabular data presentation, text wrapping to new pages, etc. This document has been created using mostly ezPdf functions.

The functions of ezpdf are described in the next section, though as it is a class extension, all of the basic functions from the original class are still available.

Please excuse this blatant 'plug', but if your company wishes some customization of these routines for your purposes, R&OS can do this at very reasonable rates, just drop us a line at info@ros.co.nz.

#NP
1<EZPDF Class Extension>


(note that the creation of this document in readme.php was converted to ezpdf with the saving of many lines of code).

It is anticipated that in practise only the simplest of documents will be able to be created using just ezpdf functions, they should be used in conjunction with the base class functions to achieve the desired result.


2<Cezpdf([paper='a4'],[orientation='portrait'])>

This is the constructor function, and allows the user to set up a basic page without having to know exactly how many units across and up the page is going to be.
Valid values for paper are 'a4','letter'.
Valid values for orientation are 'portrait','landscape'.
Starting ezpdf with the code below will create an a4 portrait document.

#C
$pdf =& new Cezpdf();
#c

If you want to get started in an easy manner, then here is the 'hello world' program:

#C
<?php
include ('class.ezpdf.php');
$pdf =& new Cezpdf();
$pdf->selectFont('./fonts/Helvetica.afm');
$pdf->ezText('Hello World!',50);
$pdf->ezStream();
?>
#c

2<ezSetMargins(top,bottom,left,right)>

Sets the margins for the document, this command is optional and they will all be set to 30 by default. Setting these margins does not stop you writing outside them using the base class functions, but the ezpdf functions will wrap onto a new page when they hit the bottom margin, and will not write over the side margins when using the <b>ezText</b> command below.

2<ezNewPage()>

Starts a new page. This is subtly different to the newPage command in the base class as it also places the ezpdf writing pointer back to the top of the page. So if you are using the ezpdf text functions, then this is the one to use when manually requesting a new page.

2<ezSetY(y)>

Positions the ezpdf writing pointer to a particular height on the page, don't forget that pdf documents have <b>y-coordinates which are zero at the bottom of the page and increase as they go up</b> the page.

2<ezSetDy(dy [,mod])>

Changes the vertical position of the writing point by a set amount, so to move the pointer 10 units down the page (making a gap in the writing), use:

#C
ezSetDy(-10)
#c

If this movement makes the writing location below the bottom margin, then a new page will automatically be made, and the pointer moved to the top of it.

The optional parameter 'mod' can be set to the value 'makeSpace', which means that if a new page is forced, then the pointer will be moved the distance 'dy' on the new page as well. The intention of this is if you needed 100 units of space to draw a picture, then doing:

#C
ezSetDy(-100,'makeSpace')
#c

guarantees that there will be 100 units of space above the final writing point.

2<ezTable(array data,[array cols],[title],[array options]>

The easy way to throw a table of information onto the page, can be used with just the data variable, which must contain a two dimensional array of data. This function was made with data extracted from database queries in mind, so is expecting it in that format, a two dimensional array with the first array having one entry for each row (and each of those is another array).

The table will start writing from the current writing point, and will proceed until the all the data has been presented, by default, borders will be drawn, alternate limes will be shaded gray, and the table will wrap over pages, re-printing the headers at the top of each page.

The other options are described here:

$cols (optional) is an associative array, the keys are the names of the columns from $data to be presented (and in that order), the values are the titles to be given to the columns, if this is not wanted, but you do want later options then '' (the empty string) is a suitable placeholder.

$title (optional) is the title to be put on the top of the table

$options is an associative array which can contain:
 'showLines'=> 0 or 1, default is 1 (1->show the borders, 0->no borders)
 'showHeadings' => 0 or 1
 'shaded'=> 0 or 1, default is 1 (1->alternate lines are shaded, 0->no shading)
 'shadeCol' => (r,g,b) array, defining the colour of the shading, default is (0.8,0.8,0.8)
 'fontSize' => 10
 'textCol' => (r,g,b) array, text colour
 'titleFontSize' => 12
 'titleGap' => 5 , the space between the title and the top of the table
 'lineCol' => (r,g,b) array, defining the colour of the lines, default, black.
 'xPos' => 'left','right','center','centre',or coordinate, reference coordinate in the x-direction
 'xOrientation' => 'left','right','center','centre', position of the table w.r.t 'xPos'. This entry is to be used in conjunction with 'xPos' to give control over the lateral position of the table.
 'width' => <number>, the exact width of the table, the cell widths will be adjusted to give the table this width.
 'maxWidth' => <number>, the maximum width of the table, the cell widths will only be adjusted if the table width is going to be greater than this.
 'cols' => array(<colname>=>array('justification'=>'left','width'=>100),<colname>=>....) ,allow the setting of other paramaters for the individual columns, each column can have its width and/or its justification set.
 
Note that the user will have had to have made a font selection already or this will not produce a valid pdf file.

A simple table example:

#C
<?php
include ('class.ezpdf.php');
$pdf =& new Cezpdf();
$pdf->selectFont('./fonts/Helvetica.afm');

$data = array(
 array('num'=>1,'name'=>'gandalf','type'=>'wizard')
,array('num'=>2,'name'=>'bilbo','type'=>'hobbit')
,array('num'=>3,'name'=>'frodo','type'=>'hobbit')
,array('num'=>4,'name'=>'saruman','type'=>'bad dude')
,array('num'=>5,'name'=>'sauron','type'=>'really bad dude')
);

$pdf->ezTable($data);

$pdf->ezStream();
?>
#c

#X
$pdf->selectFont('./fonts/Helvetica.afm');

$data = array(
 array('num'=>1,'name'=>'gandalf','type'=>'wizard')
,array('num'=>2,'name'=>'bilbo','type'=>'hobbit')
,array('num'=>3,'name'=>'frodo','type'=>'hobbit')
,array('num'=>4,'name'=>'saruman','type'=>'bad dude')
,array('num'=>5,'name'=>'sauron','type'=>'really bad dude')
);

$pdf->ezTable($data);
#x

For a slightly more complex example, print that table again, but only the second and third columns, and in the other order, also have column headings and a table heading.

#C
$pdf->ezTable($data,array('type'=>'Type','name'=>'&lt;i>Alias&lt;/i>')
          ,'Some LOTR Characters');
#c

#X
$pdf->selectFont('./fonts/Helvetica.afm');
$pdf->ezTable($data,array('type'=>'Type','name'=>'<i>Alias</i>')
              ,'Some LOTR Characters');
#x

and the same, but with no headings or shading, or lines:

#C
$pdf->ezTable($data,array('type'=>'Type','name'=>'&lt;i>Alias&lt;/i>')
              ,'Some LOTR Characters'
              ,array('showHeadings'=>0,'shaded'=>0,'showLines'=>0));
#c

#X
$pdf->selectFont('./fonts/Helvetica.afm');
$pdf->ezTable($data,array('type'=>'Type','name'=>'<i>Alias</i>')
              ,''
              ,array('showHeadings'=>0,'shaded'=>0,'showLines'=>0));
#x

Now a version with the width specified to be too small, so that the content has to wrap, and the table oriented over the the right.

#C
$pdf->ezTable($data,array('type'=>'','name'=>''),''
          ,array('showHeadings'=>0,'shaded'=>0,'xPos'=>'right'
                ,'xOrientation'=>'left','width'=>100));
#c

#X
$pdf->selectFont('./fonts/Helvetica.afm');
$pdf->ezTable($data,array('type'=>'','name'=>'')
              ,''
              ,array('showHeadings'=>0,'shaded'=>0,'xPos'=>'right','xOrientation'=>'left','width'=>100));
#x

And for a final example, the column headings have been changed, one to a long name which wraps, and also have a return code in it. The 'num' column has been right justified, and the 'name' column fixed to a width of 100. The entire table is fixed to a width of 300. The x position of the table is also fixed to 90, and the table is set to be on the right of this point.

#C
$cols = array('num'=>"number a a a a a a a a a a a a a a a\nmore"
             ,'name'=>'Name','type'=>'Type');

$pdf->ezTable($data,$cols,'',
        array('xPos'=>90,'xOrientation'=>'right','width'=>300
             ,'cols'=>array(
                 'num'=>array('justification'=>'right')
                ,'name'=>array('width'=>100))
             ));
#c

#X
$pdf->selectFont('./fonts/Helvetica.afm');
$cols = array('num'=>"number a a a a a a a a a a a a a a a\nmore",'name'=>'Name','type'=>'Type');

$pdf->ezTable($data,$cols,'',array('xPos'=>90,'xOrientation'=>'right','width'=>300
         ,'cols'=>array('num'=>array('justification'=>'right'),'name'=>array('width'=>100))
         ));
#x

2<ezText(text,[size],[array options])>

This is designed for putting blocks of text onto the page. It will add a string of text to the document (note that the string can be very large, spanning multiple pages), starting at the current drawing position. It will wrap to keep within the margins, including optional offsets from the left and the right, if $size is not specified, then it will be the last one used, or the default value (12 I think). The text will go to the start of the next line when a return code "\n" is found.

possible options are:
 'left'=> number, gap to leave from the left margin
 'right'=> number, gap to leave from the right margin
 'aleft'=> number, absolute left position (overrides 'left')
 'aright'=> number, absolute right position (overrides 'right')
 'justification' => 'left','right','center','centre','full'

 only set one of the next two items (leading overrides spacing)
 'leading' => number, defines the total height taken by the line, independent of the font height.
 'spacing' => a real number, though usually set to one of 1, 1.5, 2 (line spacing as used in word processing)

2<ezStartPageNumbers(x,y,size,[pos],[pattern],[num])>

 Add page numbers on the pages from here, place then on the 'pos' side of the coordinates (x,y) (pos can be 'left' or 'right').
 Use the given 'pattern' for display, where {PAGENUM} and {TOTALPAGENUM} are replaced as required, by default the pattern is set to '{PAGENUM} of {TOTALPAGENUM}'
 If $num is set, then make the first page this number, the number of total pages will be adjusted to account for this.

 the following code produces a seven page document, numbered from the second page (which will be labelled '1 of 6'), and numbered until the 6th page (labelled '5 of 6')

#C
$pdf = new Cezpdf();
$pdf->selectFont('./fonts/Helvetica.afm');
$pdf->ezNewPage();
$pdf->ezStartPageNumbers(300,500,20,'','',1);
$pdf->ezNewPage();
$pdf->ezNewPage();
$pdf->line(300,400,300,600); // line drawn to check 'pos' is working
$pdf->ezNewPage();
$pdf->ezNewPage();
$pdf->ezNewPage();
$pdf->ezStopPageNumbers(); 
$pdf->ezStream();
#c
 
2<ezStopPageNumbers()>

Stop adding page numbers from this page (the current page will not be numbered).
 
2<ezOutput([debug])>

Very similar to the output function from the base class, but performs any closing tasks that ezpdf requires, such as adding the page numbers.

If you are using ezpdf, then you should use this function, rather than the one from the base class.

2<ezStream([options])>

Very similar to the stream function from the base class (all the same options, see later in this document), but performs any closing tasks that ezpdf requires, such as adding the page numbers.

If you are using ezpdf, then you should use this function, rather than the one from the base class.

 
#NP
1<Major Base Class Functions>


2<addText(x,y,size,text,[angle=0],[adjust=0])>

Add the text at a particular location on the page, noting that the origin on the axes in a pdf document is in the lower left corner by default.
An angle can be supplied as this will do the obvious (in degrees).

'adjust', gives the value of units to be added to the width of each space within the text. This is used mainly to support the justification options within the ezpdf ezText function.

The text stream can now (version 006) contain directives to make the text bold and/or italic. The directives are similar the basic html: 

&lt;b&gt;<b>bold text</b>&lt;/b&gt; 
&lt;i&gt;<i>italic text</i>&lt;/i&gt; 
&lt;b&gt;&lt;i&gt;<b><i>bold italic text</i></b>&lt;i&gt;&lt;/b&gt; 

<b>Note</b> that there can be no spaces within the directives, and that they must be in lower case.

By default, these will work only with the supplied fonts (though there is no way to add more at the moment, so that is ok), and when the font was selected it must have been specified with the '.afm' suffix. For more information about why this is and how you can customise this behaviour see the <b>setFontFamily</b> command.

If you do wish to print an actual '<', most of the time it would cause no problem, except in the instance where it would form a directive, in those cases the html replacement for the '<' can be used, "&amp;lt;". In fact if any of the html entities which are supported by the PHP htmlspecialchars command are used, then they will be translated before presentation.

2<setColor(r,g,b,[force=0])>

Set the fill colour to the r,g,b triplet, each in the range 0->1.
If force is set, then the entry will be forced into the pdf file, otherwise it will only be put in if it is different from the current state.

2<setStrokeColor(r,g,b,[force=0])>

Set the stroke color, see the notes for the fill color.

2<setLineStyle([width],[cap],[join],[dash],[phase])>
This sets the line drawing style.
 width, is the thickness of the line in user units
 cap is the type of cap to put on the line, values can be 'butt','round','square' where the difference between 'square' and 'butt' is that 'square' projects a flat end past the end of the line.
 join can be 'miter', 'round', 'bevel'
 dash is an array which sets the dash pattern, is a series of length values, which are the lengths of the on and off dashes.
   for example: (2) represents 2 on, 2 off, 2 on , 2 off ...
      (2,1) is 2 on, 1 off, 2 on, 1 off.. etc
 phase is a modifier on the dash pattern which is used to shift the point at which the pattern starts. 

#C
$pdf->setLineStyle(1);
#c
#X
$pdf->setLineStyle(1);
$pdf->ezSetDy(-8,'makeSpace');
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x
#C
$pdf->setLineStyle(5);
#c
#X
$pdf->setLineStyle(5);
$pdf->ezSetDy(-8,'makeSpace');
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x
#C
$pdf->setLineStyle(5,'round');
#c
#X
$pdf->setLineStyle(5,'round');
$pdf->ezSetDy(-8,'makeSpace');
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x
#C
$pdf->setLineStyle(5,'','',array(5));
#c
#X
$pdf->setLineStyle(5,'','',array(5));
$pdf->ezSetDy(-8,'makeSpace');
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x
#C
$pdf->setLineStyle(5,'','',array(10,5));
#c
#X
$pdf->setLineStyle(5,'','',array(10,5));
$pdf->ezSetDy(-8,'makeSpace');
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x
#C
$pdf->setLineStyle(5,'','',array(20,5,10,5));
#c
#X
$pdf->setLineStyle(5,'','',array(20,5,10,5));
$pdf->ezSetDy(-8,'makeSpace',4);
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x
#C
$pdf->setLineStyle(5,'round','',array(0,15));
#c
#X
$pdf->setLineStyle(5,'round','',array(0,15));
$pdf->ezSetDy(-8,'makeSpace');
$pdf->line(100,$pdf->y,400,$pdf->y);
$pdf->ezSetDy(-5);
#x

Note that the code shown with each of these lines is just the line style command, the drawing of each line also requires a <b>line</b> command, which is not shown.

2<line(x1,y1,x2,y2)>

Draw a line from (x1,y1) to (x2,y2), set the line width using setLineStyle.

2<curve(x0,y0,x1,y1,x2,y2,x3,y3)>

Draw a Bezier curve. The end points are (x0,y0)->(x3,y3), and the control points are the other two.

Bezier curves are neat, but probably not for the novice. The <b>ellipse</b> command uses a series of Bezier curves to make the ellipse.

The distinctive feature of these curves is that the curve is guaranteed to lie within the 4 sided polygon formed from the 4 control points (they are also computationally easy to draw). An example is shown below with the control points marked.

#C
$pdf->curve(200,$y+40,250,$y+5,350,$y,400,$y+45);
#c
#X
$pdf->ezSetDy(-50,'makeSpace');
$y = $pdf->y;
$pdf->setLineStyle(2);
$pdf->curve(200,$y+40,250,$y+5,350,$y,400,$y+45);
$pdf->setLineStyle(0.5);
$pdf->ellipse(200,$y+40,5);
$pdf->ellipse(250,$y+5,5);
$pdf->ellipse(350,$y,5);
$pdf->ellipse(400,$y+45,5);
$pdf->setLineStyle(0.5,'','',array(10,5));
$pdf->line(200,$y+40,250,$y+5);
$pdf->line(250,$y+5,350,$y);
$pdf->line(350,$y,400,$y+45);
#x

Note that the Bezier curve is a tangent to the line between the control points at either end of the curve.

2<ellipse(x0,y0,r1,[r2=0],[angle=0],[nSeg=8])>

Draw an ellipse, centred ay (x0,y0), with radii (r1,r2), oriented at 'angle' (anti-clockwise), and formed from nSeg bezier curves (the default 8 gives a reasonable approximation to the required shape).

If r2 is left out, or set to zero, then it is assumed that a circle is being drawn.

#C
$pdf->ellipse(300,$y+25,20);
#c
#X
$pdf->ezSetDy(-50,'makeSpace');
$pdf->setLineStyle(2);
$pdf->ellipse(300,$pdf->y+25,20);
#x

#C
$pdf->ellipse(300,$y+25,40,20);
#c
#X
$pdf->ezSetDy(-50,'makeSpace');
$pdf->setLineStyle(2);
$pdf->ellipse(300,$pdf->y+25,40,20);
#x

#C
$pdf->ellipse(300,$y+25,40,20,45);
#c
#X
$pdf->ezSetDy(-50,'makeSpace');
$pdf->setLineStyle(2);
$pdf->ellipse(300,$pdf->y+25,40,20,45);
#x

Of course the previous line style features also apply to these lines

#C
$pdf->setLineStyle(4,'round','',array(0,6,4,6));
$pdf->ellipse(300,$y+25,40,20,45);
#c
#X
$pdf->ezSetDy(-50,'makeSpace');
$pdf->setLineStyle(4,'round','',array(0,6,4,6));
$pdf->ellipse(300,$pdf->y+25,40,20,45);
#x


2<polygon(p,np,[f=0])>

Draw a polygon, where there are np points, and p is an array containing (x0,y0,x1,y1,x2,y2,...,x(np-1),y(np-1)).
If f=1 then fill the area.

#C
$pdata = array(200,10,400,20,300,50,150,40);
$pdf->polygon($pdata,4);
#c
#X
$pdata = array(200,10,400,20,300,50,150,40);
$pdf->ezSetDy(-60,'makeSpace');
for ($i=1;$i<count($pdata);$i+=2){
  $pdata[$i]+=$pdf->y;
}
$pdf->polygon($pdata,4);
#x

#C
$pdf->polygon($pdata,4,1);
#c
#X
$pdf->ezSetDy(-60,'makeSpace');
$pdata = array(200,10,400,20,300,50,150,40);
$pdf->ezSetDy(-60,'makeSpace');
for ($i=1;$i<count($pdata);$i+=2){
  $pdata[$i]+=$pdf->y;
}
$pdf->polygon($pdata,4,1);
#x

#C
$pdf->setColor(0.9,0.9,0.9);
$pdf->polygon($pdata,4,1);
#c
#X
$pdf->ezSetDy(-60,'makeSpace');
$pdata = array(200,10,400,20,300,50,150,40);
$pdf->ezSetDy(-60,'makeSpace');
for ($i=1;$i<count($pdata);$i+=2){
  $pdata[$i]+=$pdf->y;
}
$pdf->setColor(0.9,0.9,0.9);
$pdf->polygon($pdata,4,1);
#x


2<filledRectangle(x1,y1,width,height)>

Obvious.

2<rectangle(x1,y1,width,height)>

Obvious.

2<id=newPage()>

Starts a new page and returns the id of the page, this can be safely ignored, but storing it will allow the insertion of more information back into the page later, through the use of the 'reopenObject' function.

2<id=getFirstPageId()>

A related command is this which returns the id of the first page, this page is created during the class instantiation and so does not have its id returned to the user, this is the only way to fetch it, but it can be done at any point.

2<stream([array options])>

Used for output, this will set the required headers and output the pdf code.

The options array can be used to set a number of things about the output:

 'Content-Disposition'=>'filename' sets the filename, though not too sure how well this will work as in my trial the browser seems to use the filename of the php file with .pdf on the end.
 'Accept-Ranges'=>1 or 0 - if this is not set to 1, then this header is not included, off by default this header seems to have caused some problems despite the fact that it is supposed to solve them, so I am leaving it off by default.
 'compress'=> 1 or 0 - apply content stream compression, this is on (1) by default.

2<x=getFontHeight(size)>

Returns the height of the current font, in the given size. This is the distance from the bottom of the descender to the top of the Capitals.

2<x=getFontDecender(size)>

Returns a number which is the distance that the descender goes beneath the Baseline, for a normal character set this is a negative number. 

2<x=getTextWidth(size,text)>

Returns the width of the given text string at the given size.

2<a=addTextWrap(x,y,width,size,text,[justification='left'][,angle=0])>

Will print the text string to the page at the position (x,y), if the string is longer than width, then it will print only the part which will fit within that width (attempting to truncate at a space if possible) and will return the remainder of the string. 

'justification' is optional and can be set to 'left','right','center','centre','full'. It provides for the justification of the text and though quite usable here, was implemented for the ezpdf class.

2<saveState()>

Save the graphic state.

2<restoreState()>

Restore a saved graphics state.

2<id=openObject()>

Start an independent object. This will return an object handle, and all further writes to a page will actually go into this object, until a closeObject call is made.

2<reopenObject(id)>

Makes the point of current content insertion the numbered object, this 'id' must have been returned from a call to 'openObject' or 'newPage' for it to be a valid object to insert content into. Do not forget to call 'closeObject' to close off input to this object and return it to where it was beforehand (most likely the current page).
This will allow the user to add information to previous pages, as long as they have stored the id of the pages.

2<closeObject()>

Close the currently open object. Further writes will now go to the current page.

2<addObject(id,[options='add'])>

Add the object specified by id to the current page (default). If a string is supplied in options, then the following may be specified:
'add' - add to the current page only.
'all' - add to every page from the current one on.
'odd' - add to all odd numbered pages from now on.
'even' - add to all even numbered pages from now on.

2<stopObject(id)>

If the object (id) has been appearing on pages up to now, then stop it, this page will be the last one that could contain it.

2<addInfo(label,value)>

Add document information, the valid values for label are:
Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate, Trapped

modified in version 003 so that 'label' can also be an array of key->value pairs, in which case 'value' should not be set.

2<setPreferences(label,value)>

Set some document preferences, the valid values for label are:
HideToolbar, HideMenuBar, HideWindoUI, FitWindow, CenterWindow, NonFullScreenPageMode, Direction

modified in version 003 so that 'label' can also be an array of key->value pairs, in which case 'value' should not be set.

2<addImage(img,x,y,[w=0],[h=0],[quality=75])>

Add an image to the document, this feature needs some development. But as it stands, img must be a handle to a GD graphics object, and one or both of w or h must be specified, if only one of them is specified, then the other is calculated by keeping the ratio of the height and width of the image constant.
The image will be placed with its lower left corner at (x,y), and w and h refer to page units, not pixels.

2<addJpegFromFile(imgFileName,x,y,[w=0],[h=0])>

Add a JPEG image to the document, this function does not require the GD functionality, so should be usable to more people, interestingly it also seems to 
be more reliable and better quality. The syntax of the command is similar to the above 'addImage' function, though 'img' is a string containing the file name of the jpeg image.

2<a=output([debug=0])>

As an alternative to streaming the output directly to the browser, this function simply returns the pdf code. No headers are set, so if you wish to stream at a later time, then you will have to manually set them. This is ideal for saving the code to make a pdf file, or showing the code on the screen for debug purposes.

If the 'debug' parameter is set to 1, then the only effect at the moment is that the compression option is not used for the content streams, so that they can be viewed clearly.

2<openHere(style[,a][,b][,c])>

Make the document open at a specific page when it starts. The page will be the one which is the current page when the function is called.

The style option will define how it will look when open, valid values are:
(where the extra parameters will be used to supply any values specified for the style chosen)

'XYZ'  left, top, zoom <i>open at a particular coordinate on the page, with a given zoom factor</i>
'Fit'  <i>fit the page to the view</i>
'FitH' top <i>fit horizontally, and at the vertical position given</i>
'FitV' left <i>fit vertically, and at the horizontal position given</i>
'FitB' <i>fit the bounding box of the page into the viewer</i>
'FitBH' top <i>fit the width of the bounding box to the viewer and set at the vertical position given</i>
'FitBV' left <i>fit bounding box vertically and set given horizontal position</i>

2<selectFont(fontName [,encoding])>

This selects a font to be used from this point in the document. Errors can occur if some of the other functions are used if a font has not been selected, so it is wise to do this early on.

Postscript type 1 fonts and TrueType fonts can now be used! Though you do need a supporting .afm file for each of them. Things to note are:
- type 1 fonts are only acceptable as binary (.pfb) files, though there is a free utility (t1utils) to convert .pfa files to this format. You have to have the .afm file which goes with this file.
- TrueType fonts also have to have a .afm file, there is a free utility (ttf2pt1) to generate one from a .ttf file, and it seems to work for most cases.
- to use the font, simply place both of the files in the font directory, and select the font <b>using the name of the .afm file, including the .afm</b>.
- using lots of fonts will make your pdf files much larger, as the full font program (the .ttf or the .pfb file) is embedded within the pdf file (though this means that anyone receiving the file will see it just as intended).

The encoding directive is a little experimental, it allows the user to re-map character numbers from the 0->255 range to any named character in the set (as most of the sets have more than 256 characters). It should be an array of <number> => <name> pairs in an associative array. This is important to ensure that the right width for the character is used within the presentation characters, it has been noticed that sometimes, although the right character appears on the page, the incorrect width has been caluclated, using this function to explicitly set that number to the named character should fix the problem.

Note that the encoding directive will be effective <b>only the first time</b> that a font is selected, and it should not be used on symbolic fonts (such as Symbol or ZapfDingbats).

The command can be used in two forms - either with encoding=string, which sets this as the encoding type, or as an array which allows the setting of the encoding type, and the differences array. Examples of both are shown below, the example that sets the differences array includes the differences to make the common german characters work correctly.

#C
// use a Times-Roman font with MacExpertEncoding
$pdf->selectFont('./fonts/Times-Roman.afm','MacExpertEncoding');
// this next line should be equivalent
$pdf->selectFont('./fonts/Times-Roman.afm',array('encoding'=>'MacExpertEncoding'));

// setup the helvetica font for use with german characters
$diff=array(196=>'Adieresis',228=>'adieresis',
             214=>'Odieresis',246=>'odieresis',
             220=>'Udieresis',252=>'udieresis',
             223=>'germandbls');
$pdf->selectFont('./fonts/Helvetica.afm'
       ,array('encoding'=>'WinAnsiEncoding'
             ,'differences'=>$diff));
#c


2<setFontFamily(family,options)>

This function defines the relationship between the various fonts that are in the system, so that when a base font is selected the program then knows which to use when it is asked for the <b>bold</b> version or the <i>italic</i> version (not forgetting of course <b><i>bold-italic</i></b>).

It maintains a set of arrays which give the alternatives for the base fonts. The defaults that are in the system to start with are:

'Helvetica.afm'
        'b'=>'Helvetica-Bold.afm'
        'i'=>'Helvetica-Oblique.afm'
        'bi'=>'Helvetica-BoldOblique.afm'
        'ib'=>'Helvetica-BoldOblique.afm'

'Courier.afm'
        'b'=>'Courier-Bold.afm'
        'i'=>'Courier-Oblique.afm'
        'bi'=>'Courier-BoldOblique.afm'
        'ib'=>'Courier-BoldOblique.afm'

'Times-Roman.afm'
        'b'=>'Times-Bold.afm'
        'i'=>'Times-Italic.afm'
        'bi'=>'Times-BoldItalic.afm'
        'ib'=>'Times-BoldItalic.afm'

(where 'b' indicate bold, and 'i' indicates italic)
        
Which means that (for example) if you have selected the 'Courier.afm' font, and then you use the italic markers then the system will change to the 'Courier-Oblique.afm' font.

Note that at the moment it is not possible to have any more fonts, so there is little use in calling this function (except to change these settings, discussed below), but this is paving the way for when soon we will be able to add other fonts (both .afm, and .ttf), which is also why the suffix must be specified in the font name.

Note also that it is possible to have a different font when some text is bolded, then italicized, as compared to when it is italicized, then bolded ('bi' vs 'ib'), though they have all been set to be the same by default.

If you bold a font twice, then under the current system it would look for a 'bb' entry in the font family, and since there are none in the default families the font will revert to the base font. As an example here is the code that you would use to define a new font family for the Courier font which (for some reason) changed to Times-Roman when a double bold is used:

#C
$tmp = array(
         'b'=>'Courier-Bold.afm'
        ,'i'=>'Courier-Oblique.afm'
        ,'bi'=>'Courier-BoldOblique.afm'
        ,'ib'=>'Courier-BoldOblique.afm'
        ,'bb'=>'Times-Roman.afm'
      );
$pdf->setFontFamily('Courier.afm',$tmp);
#c


2<notes>

The units used for positioning within this class are the default pdf user units, in which each unit is equivalent to 1/72 of an inch.