Introduction to the packer
The packer extension is intended to be a major leap forward in the technology of generating PDFs. The eventual goal is that you'll just feed all your data to the packer, and it will figure out how to fit it on the page (or create new pages as needed).
The packer is a long way from achieving that goal, but it does have some useful things it can do:
Ok, ok, it's not much, but it's a start. Here's how to use the packer as it currently stands:
$pdf->enable('packer');
$page = $pdf->packer->new_page();
$pdf->draw_rectangle(50, 10, 10, 50, $page);
$space = new field(10, 50, 10, 50);
$pdf->packer->allocate($space);
$pdf->packer->fill_text($text);
At the time of writing, the packer seems to be working in the sense that I've yet to see it do anything insane, or crash. That doesn't mean it's going to produce useful results. As detailed below in the "rational", there are areas of potential failure that I still have not addressed.
The concept of the packer engine started with perl's Tk library, and the packer included. phppdflib's packer will run somewhat differently, since the main restraining factor is available page space and phppdflib can create new pages at will - two things the perl packer doesn't factor in to its reasoning.
The basic idea I have is that each page will store an array of rectangles that indicate the unused space on the page. Initially, a page will consist of a single rectangle (bounded by the page margins) All painting functions will remove the space they use from this pool, thus keeping track of how much space is still available to use on the page. Special functions will allow a client script to paint an object "in the next available space", and the packer should create new pages as needed to place objects.
Inside the machine, the painting of an object will take the rectangle that
it's placed in and break it into sub-rectangles that identify remaining space.
To illistrate, a page initially consists of a single "field" (that's the term
I'm going to coin, we'll see if it sticks):
+----------+ | | | | | | | | | | | | +----------+When we place (for example) an image on the page, it allocates some space (a) and the remaining space is broken into new rectangles (b & c)
+----+-----+ | | a | | | | | b +-----+ | | | | | c | | | | +----+-----+The allotment of remaining space is not arbitrary, it attempts to keep the largest vertical area possible (b) since that's how text normally flows. A special function will exist to "fill in" text in the remaining space - the idea being that a user can place all her/his images in the document, and then automagically have the packer flow the text around the images.
Since this section was originally written, I believe I've solved some of the problems that orinally worried me. I feel that the code I currently have in place can handle any possible allocation of space from a collection of fields of arbitrary complexity. However, this has introduced new concerns:
See example-packer.php
in the examples directory.
The first incarnation of the packer was added in 2.6
The packer is very much experimental at this time, it is also very incomplete.