Add custom document

Search…
Add custom document
Overview
Using the Shopware administration, you can easily create new documents. This guide will teach you how to achieve the same result, which is creating a new document, using your plugin.
Prerequisites
This guide is built upon the plugin base guide, but of course you can use those examples with any other plugin.
Furthermore adding a document via your plugin is done by using plugin database migrations. Since this isn't explained in this guide, you'll have to know and understand the plugin database migrations first.
Adding a custom document
Documents in Shopware are stored in the database table document_base_config. Do not confuse it with the document table, which contains the actually generated documents for an order and not the config for them.
Adding a new document is done by adding two entries to the database:
One entry in the document_base_config table, which contains the whole configuration and the documents name
One or more entries in the document_base_config_sales_channel table for each sales channel you want this document to be available
for
We're doing this via a migration. In the following example migration, a new document named "custom" will be created, which is assigned to the Storefront sales channel.
<plugin root>/src/Migration/Migration1616668698AddDocument.php
1
<?php declare(strict_types=1);
2
​
3
namespace Swag\BasicExample\Migration;
4
​
5
use Doctrine\DBAL\Connection;
6
use Shopware\Core\Defaults;
7
use Shopware\Core\Framework\Migration\MigrationStep;
8
use Shopware\Core\Framework\Uuid\Uuid;
9
​
10
class Migration1616668698AddDocument extends MigrationStep
11
{
12
    public function getCreationTimestamp(): int
13
    {
14
        return 1616668698;
15
    }
16
​
17
    public function update(Connection $connection): void
18
    {
19
        $documentConfigId = Uuid::randomBytes();
20
        $documentTypeId = $this->getDocumentTypeId($connection);
21
​
22
        $connection->insert('document_base_config', [
23
            'id' => $documentConfigId,
24
            'name' => 'custom',
25
            'filename_prefix' => 'custom_',
26
            'global' => 0,
27
            'document_type_id' => $documentTypeId,
28
            'config' => $this->getConfig(),
29
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
30
        ]);
31
​
32
        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
33
        if (!$storefrontSalesChannelId) {
34
            return;
35
        }
36
​
37
        $connection->insert('document_base_config_sales_channel', [
38
            'id' => Uuid::randomBytes(),
39
            'document_base_config_id' => $documentConfigId,
40
            'sales_channel_id' => $storefrontSalesChannelId,
41
            'document_type_id' => $documentTypeId,
42
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
43
        ]);
44
    }
45
​
46
    public function updateDestructive(Connection $connection): void
47
    {
48
    }
49
​
50
    private function getDocumentTypeId(Connection $connection): string
51
    {
52
        $sql = <<<SQL
53
            SELECT id
54
            FROM document_type
55
            WHERE technical_name = "delivery_note"
56
SQL;
57
        return $connection->fetchOne($sql);
58
    }
59
​
60
    private function getConfig(): string
61
    {
62
        $config = [
63
            'displayPrices' => false,
64
            'displayFooter' => true,
65
            'displayHeader' => true,
66
            'displayLineItems' => true,
67
            'displayLineItemPosition' => true,
68
            'displayPageCount' => true,
69
            'displayCompanyAddress' => true,
70
            'pageOrientation' => 'portrait',
71
            'pageSize' => 'a4',
72
            'itemsPerPage' => 10,
73
            'companyName' => 'Example company',
74
            'companyAddress' => 'Example company address',
75
            'companyEmail' => '[email protected]'
76
        ];
77
​
78
        return json_encode($config);
79
    }
80
​
81
    private function getStorefrontSalesChannelId(Connection $connection): ?string
82
    {
83
        $sql = <<<SQL
84
            SELECT id
85
            FROM sales_channel
86
            WHERE type_id = :typeId
87
SQL;
88
        $salesChannelId = $connection->fetchOne($sql, [
89
            ':typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
90
        ]);
91
​
92
        if (!$salesChannelId) {
93
            return null;
94
        }
95
​
96
        return $salesChannelId;
97
    }
98
}
Copied!
So it's basically fetching the "Storefront" sales channel ID, and the document type ID of the "Delivery note" document type and then inserts the necessary entries with some example data.
You'll have to provide a name and a filename_prefix for your custom document. If you create a new document for e.g. a completely new document type, you might want to set global to 1, so it acts like a fallback. Also make sure to have a look at the getConfig method here, since it contains important configurations you can set for your custom document.
Basically, that's it already! You can now browse your administration and use your newly configured document.
Next steps
You might wonder "But where do I define my custom template for my custom document?". This is done by adding a new document type, which is covered in this guide.
Document
Add custom document type
Last modified 18d ago
Copy link
Edit on GitHub
Contents
Overview
Prerequisites
Adding a custom document
Next steps