-
Notifications
You must be signed in to change notification settings - Fork 51
Class ZugferdDocumentPdfBuilder
HorstOeko edited this page Dec 31, 2024
·
25 revisions
Class representing the facillity adding XML data from ZugferdDocumentBuilder
to an existing PDF with conversion to PDF/A
use horstoeko\zugferd\codelists\ZugferdCurrencyCodes;
use horstoeko\zugferd\codelists\ZugferdInvoiceType;
use horstoeko\zugferd\ZugferdDocumentBuilder;
use horstoeko\zugferd\ZugferdDocumentPdfBuilderAbstract;
use horstoeko\zugferd\ZugferdDocumentPdfBuilder;
use horstoeko\zugferd\ZugferdProfiles;
// Build the XML using ZugferdDocumentBuilder
$zugferdDocumentBuilder = ZugferdDocumentBuilder::CreateNew(ZugferdProfiles::PROFILE_EN16931);
$zugferdDocumentBuilder
->setDocumentInformation('R-2024/00001', ZugferdInvoiceType::INVOICE, DateTime::createFromFormat('Ymd', '20241231'), ZugferdCurrencyCodes::EURO)
->......
// Create a PDF using the XML content from ZugferdDocumentBuilder and an existing print-output file
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');
// Create a PDF using the XML content from ZugferdDocumentBuilder and a print-content stream (string)
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfString($documentBuilder, '%PDF-1.5...........');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');
// Alternatively, you can also return the merged output as a content stream (string)
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->generateDocument();
$pdfBinaryString = $zugferdDocumentPdfBuilder->generateDocument()->downloadString();
// If you would like to brand the merged PDF with the name of you own solution you can call
// the method setAdditionalCreatorTool. Before calling this method the creator of the PDF is identified as 'Factur-X library 1.x.x by HorstOeko'.
// After calling this method you get 'MyERPSolution 1.0 / Factur-X PHP library 1.x.x by HorstOeko' as the creator
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setAdditionalCreatorTool('MyERPSolution 1.0');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');
// It is also possible to add additional attachments to the merged PDF. These can be any files that can help the invoice
// recipient with processing. For example, a time sheet as an Excel file would be conceivable.
// The method attachAdditionalFileByRealFile has 3 parameters:
// - The file to attach which must exist and must be readable
// - (Optional) A name to display in the attachments of the PDF
// - (Optional) The type of the relationship of the attachment. Valid values are defined in the class
// ZugferdDocumentPdfBuilderAbstract. The constants are starting with AF_
//
// If you omit the last 2 parameters the following will happen:
// - The displayname is calculated from the filename you specified
// - The type of the relationship of the attachment will be AF_RELATIONSHIP_SUPPLEMENT (Supplement)
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->attachAdditionalFileByRealFile('/path/to/existing.file', "Some display Name", ZugferdDocumentPdfBuilderAbstract::AF_RELATIONSHIP_SUPPLEMENT);
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');
// You can also add an attachment to the PDF as an stream (string). The conditions are the same as above for the attachAdditionalFileByRealFile method
// The only difference to attachAdditionalFileByRealFile is that the attachAdditionalFileByContent method accepts 4 parameters, whereby here (as with attachAdditionalFileByRealFile)
// the last two can be omitted. You only need to specify a file name under which the file is to be embedded
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->attachAdditionalFileByContent('<xml>....</xml>', 'additionalDocument.csv', "Some other display Name", ZugferdDocumentPdfBuilderAbstract::AF_RELATIONSHIP_SUPPLEMENT);
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');
// We can change some meta information such as the title, the subject, the author and the keywords. This library essentially provides 4 methods for this:
// - setAuthorTemplate
// - setTitleTemplate
// - setSubjectTemplate
// - setKeywordTemplate
// The 4 methods just mentioned accept a free text that can accept the following placeholders:
// - %1$s .... contains the invoice number (is extracted from the XML data)
// - %2$s .... contains the type of XML document, such as ‘Invoice’ (is extracted from the XML data)
// - %3$s .... contains the name of the seller (extracted from the XML data)
// - %4$s .... contains the invoice date (extracted from the XML data)
// The following example would generate...
// - the author: .... Issued by seller with name Lieferant GmbH
// - the title .... Lieferant GmbH : Invoice R-2024/00001
// - the subject .... Invoice-Document, Issued by Lieferant GmbH
// - the keywords .... R-2024/00001, Invoice, Lieferant GmbH, 2024-12-31
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setAuthorTemplate('Issued by seller with name %3$s');
$zugferdDocumentPdfBuilder->setTitleTemplate('%3$s : %2$s %1$s');
$zugferdDocumentPdfBuilder->setSubjectTemplate('%2$s-Document, Issued by %3$s');
$zugferdDocumentPdfBuilder->setKeywordTemplate('%1$s, %2$s, %3$s, %4$s');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');
// If the previously mentioned options for manipulating the meta information are not sufficient,
// you can also use a callback function. The following 4 parameters are passed to the callback
// function in the specified order:
// - $which .... one of "author", "title", "subject" and "keywords"
// - $xmlContent .... the content of the xml as a string
// - $invoiceInformation .... an array with some information about the invoice
// - $default .... The default value for the specified field (see $which
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setMetaInformationCallback(
function ($which) {
if ($which === 'title') {
return "DummyTitle";
}
if ($which === 'author') {
return "DummyAuthor";
}
if ($which === 'subject') {
return "DummySubject";
}
if ($which === 'keywords') {
return "DummyKeywords";
}
}
);
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');No summary available.
public static function fromPdfFile(
horstoeko\zugferd\ZugferdDocumentBuilder $documentBuilder,
string $pdfFileName,
): void
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| documentBuilder | horstoeko\zugferd\ZugferdDocumentBuilder | ❌ | |
| pdfFileName | string | ❌ |
No summary available.
public static function fromPdfString(
horstoeko\zugferd\ZugferdDocumentBuilder $documentBuilder,
string $pdfContent,
): void
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| documentBuilder | horstoeko\zugferd\ZugferdDocumentBuilder | ❌ | |
| pdfContent | string | ❌ |
Constructor
public function __construct(horstoeko\zugferd\ZugferdDocumentBuilder $documentBuilder, string $pdfData): void
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| documentBuilder | horstoeko\zugferd\ZugferdDocumentBuilder | ❌ | The instance of the document builder. Needed to get the XML data |
| pdfData | string | ❌ | The full filename or a string containing the binary pdf data. This is the original PDF (e.g. created by a ERP system) |
Generates the final document
public function generateDocument(): static
{
}Returns a value of type static
Saves the generated PDF document to a file
public function saveDocument(string $toFilename): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| toFilename | string | ❌ | The full qualified filename to which the generated PDF (with attachment)is stored |
Returns a value of type static
Starts a HTTP download of the generated PDF document
public function saveDocumentInline(string $toFilename): string
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| toFilename | string | ❌ |
Returns a value of type string
Returns the content of the generared PDF as a string
public function downloadString(): string
{
}Returns a value of type string
Sets an additional creator tool (e.g. the ERP software that called the PHP library)
public function setAdditionalCreatorTool(string $additionalCreatorTool): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| additionalCreatorTool | string | ❌ | The name of the creator |
Returns a value of type static
// Before calling this method the creator of the PDF is identified as 'Factur-X library 1.x.x by HorstOeko'.
// After calling this method you get 'MyERPSolution 1.0 / Factur-X PHP library 1.x.x by HorstOeko' as the creator
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setAdditionalCreatorTool('MyERPSolution 1.0');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Set the type of relationship for the XML attachment. Allowed
types are 'Data', 'Alternative' and 'Source'
public function setAttachmentRelationshipType(string $relationshipType): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| relationshipType | string | ❌ | Type of relationship |
Returns a value of type static
Set the type of relationship for the XML attachment to "Data"
public function setAttachmentRelationshipTypeToData(): static
{
}Returns a value of type static
Set the type of relationship for the XML attachment to "Alternative"
public function setAttachmentRelationshipTypeToAlternative(): static
{
}Returns a value of type static
Set the type of relationship for the XML attachment to "Source"
public function setAttachmentRelationshipTypeToSource(): static
{
}Returns a value of type static
Attach an additional file to PDF. The file that is specified in $fullFilename
must exists
public function attachAdditionalFileByRealFile(
string $fullFilename,
string $displayName = '',
string $relationshipType = '',
): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| fullFilename | string | ❌ | |
| displayName | string | ❌ | |
| relationshipType | string | ❌ |
Returns a value of type static
// The method attachAdditionalFileByRealFile has 3 parameters:
// - The file to attach which must exist and must be readable
// - (Optional) A name to display in the attachments of the PDF
// - (Optional) The type of the relationship of the attachment. Valid values are defined in the class
// ZugferdDocumentPdfBuilderAbstract. The constants are starting with AF_
//
// If you omit the last 2 parameters the following will happen:
// - The displayname is calculated from the filename you specified
// - The type of the relationship of the attachment will be AF_RELATIONSHIP_SUPPLEMENT (Supplement)
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->attachAdditionalFileByRealFile('/path/to/existing.file', "Some display Name", ZugferdDocumentPdfBuilderAbstract::AF_RELATIONSHIP_SUPPLEMENT);
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Attach an additional file to PDF by a content string
public function attachAdditionalFileByContent(
string $content,
string $filename,
string $displayName = '',
string $relationshipType = '',
): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| content | string | ❌ | |
| filename | string | ❌ | |
| displayName | string | ❌ | |
| relationshipType | string | ❌ |
Returns a value of type static
// You can also add an attachment to the PDF as an stream (string). The conditions are the same as above for the attachAdditionalFileByRealFile method
// The only difference to attachAdditionalFileByRealFile is that the attachAdditionalFileByContent method accepts 4 parameters, whereby here (as with attachAdditionalFileByRealFile)
// the last two can be omitted. You only need to specify a file name under which the file is to be embedded
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->attachAdditionalFileByContent('<xml>....</xml>', 'additionalDocument.csv', "Some other display Name", ZugferdDocumentPdfBuilderAbstract::AF_RELATIONSHIP_SUPPLEMENT);
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Set the the deterministic mode. This mode should only be used
for testing purposes
public function setDeterministicModeEnabled(bool $deterministicModeEnabled): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| deterministicModeEnabled | bool | ❌ |
Returns a value of type static
Set the template for the author meta information
public function setAuthorTemplate(string $authorTemplate): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| authorTemplate | string | ❌ |
Returns a value of type static
// Change the author of the generated (merged) PDF
// This method accepts a free text that can accept the following placeholders:
// - %1$s .... contains the invoice number (is extracted from the XML data)
// - %2$s .... contains the type of XML document, such as ‘Invoice’ (is extracted from the XML data)
// - %3$s .... contains the name of the seller (extracted from the XML data)
// - %4$s .... contains the invoice date (extracted from the XML data)
// The follwing example will generate: Issued by seller with name Lieferant GmbH
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setAuthorTemplate('Issued by seller with name %3$s');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Set the template for the keyword meta information
public function setKeywordTemplate(string $keywordTemplate): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| keywordTemplate | string | ❌ |
Returns a value of type static
// Change the keywords of the generated (merged) PDF
// This method accepts a free text that can accept the following placeholders:
// - %1$s .... contains the invoice number (is extracted from the XML data)
// - %2$s .... contains the type of XML document, such as ‘Invoice’ (is extracted from the XML data)
// - %3$s .... contains the name of the seller (extracted from the XML data)
// - %4$s .... contains the invoice date (extracted from the XML data)
// The follwing example will generate: R-2024/00001, Invoice, Lieferant GmbH, 2024-12-31
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setKeywordTemplate('%1$s, %2$s, %3$s, %4$s');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Set the template for the title meta information
public function setTitleTemplate(string $titleTemplate): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| titleTemplate | string | ❌ |
Returns a value of type static
// Change the title of the generated (merged) PDF
// This method accepts a free text that can accept the following placeholders:
// - %1$s .... contains the invoice number (is extracted from the XML data)
// - %2$s .... contains the type of XML document, such as ‘Invoice’ (is extracted from the XML data)
// - %3$s .... contains the name of the seller (extracted from the XML data)
// - %4$s .... contains the invoice date (extracted from the XML data)
// The follwing example will generate: Lieferant GmbH : Invoice R-2024/00001
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setTitleTemplate('%3$s : %2$s %1$s');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Set the template for the subject meta information
public function setSubjectTemplate(string $subjectTemplate): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| subjectTemplate | string | ❌ |
Returns a value of type static
// Change the subject of the generated (merged) PDF
// This method accepts a free text that can accept the following placeholders:
// - %1$s .... contains the invoice number (is extracted from the XML data)
// - %2$s .... contains the type of XML document, such as ‘Invoice’ (is extracted from the XML data)
// - %3$s .... contains the name of the seller (extracted from the XML data)
// - %4$s .... contains the invoice date (extracted from the XML data)
// The follwing example will generate: Invoice-Document, Issued by Lieferant GmbH
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setSubjectTemplate('%2$s-Document, Issued by %3$s');
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');Set the user defined callback for generating custom meta information
public function setMetaInformationCallback(?callable $callback = null): static
{
}| Name | Type | Allows Null | Description |
|---|---|---|---|
| callback | callable | ✔️ |
Returns a value of type static
// Use a callback function to manipulate the meta information.
// The following 4 parameters are passed to the callback
// function in the specified order:
// - $which .... one of "author", "title", "subject" and "keywords"
// - $xmlContent .... the content of the xml as a string
// - $invoiceInformation .... an array with some information about the invoice
// - $default .... The default value for the specified field (see $which
$zugferdDocumentPdfBuilder = ZugferdDocumentPdfBuilder::fromPdfFile($zugferdDocumentBuilder, '/tmp/existingprintlayout.pdf');
$zugferdDocumentPdfBuilder->setMetaInformationCallback(
function ($which) {
if ($which === 'title') {
return "DummyTitle";
}
if ($which === 'author') {
return "DummyAuthor";
}
if ($which === 'subject') {
return "DummySubject";
}
if ($which === 'keywords') {
return "DummyKeywords";
}
}
);
$zugferdDocumentPdfBuilder->generateDocument();
$zugferdDocumentPdfBuilder->saveDocument('/tmp/merged.pdf');