diff --git a/src/content/docs/customizing-fossbilling/company.mdoc b/src/content/docs/customizing-fossbilling/company.mdoc index 9ce747d..3da7203 100644 --- a/src/content/docs/customizing-fossbilling/company.mdoc +++ b/src/content/docs/customizing-fossbilling/company.mdoc @@ -60,6 +60,8 @@ https://example.com This signature appears at the bottom of most automated emails. You can still override it in individual templates. +For more control over generated output, see [Email Templates](/customizing-fossbilling/email-templates/) and [Customizing Invoice PDFs](/customizing-fossbilling/invoice-pdf/). + ## Currency Settings Also in **Configuration → Settings → Currency**: diff --git a/src/content/docs/customizing-fossbilling/config.mdoc b/src/content/docs/customizing-fossbilling/config.mdoc index 1b99d88..395fdb4 100644 --- a/src/content/docs/customizing-fossbilling/config.mdoc +++ b/src/content/docs/customizing-fossbilling/config.mdoc @@ -101,21 +101,36 @@ Temporarily disable public access. Use `allowed_urls` for endpoints that must st ### API Settings -Control API access and rate limiting. Use `require_referrer_header` to lock browser-originated requests to your install URL, `allowed_ips` for explicit allowlists, and the `rate_*` values to tune throttling. +Control API access. + +- Use `require_referrer_header` to lock browser-originated requests to your install URL, and `allowed_ips` for explicit allowlists. +- Keep `CSRFPrevention` enabled. The bundled [JavaScript API wrapper](/developing-fossbilling/javascript/) handles CSRF tokens for session-authenticated browser calls. ```php 'api' => [ 'require_referrer_header' => true, 'allowed_ips' => [], - 'rate_span' => 60, - 'rate_limit' => 100, - 'throttle_delay' => 2, - 'rate_span_login' => 60, - 'rate_limit_login' => 20, 'CSRFPrevention' => true, ], ``` +### Rate Limiter +FOSSBilling includes a built-in rate limiter which depends on Symfony's [rate limiter](https://symfony.com/doc/current/rate_limiter.html) component. + +`policies` is an empty array by default and inherits sensible defaults from [`FOSSBilling\Security\RateLimiter::getDefaultConfig()`](https://github.com/FOSSBilling/FOSSBilling/blob/main/src/library/FOSSBilling/Security/RateLimiter.php#L37). + +Any policy you explicitly set in the `policies` array will override the default one. We have included an example below. You can refer to Symfony's documentation on creating rate limiter policies. + +```php +'rate_limiter' => [ + 'enabled' => true, + 'whitelist_ips' => [], // Array of whitelisted IP addresses and CIDRs + 'policies' => [ + 'client_signup' => ['policy' => 'fixed_window', 'limit' => 5, 'interval' => '1 hour'], + ], +], +``` + ## Environment Variables Some settings can be overridden via environment variables: diff --git a/src/content/docs/customizing-fossbilling/email-templates.mdoc b/src/content/docs/customizing-fossbilling/email-templates.mdoc index 8d4fee9..3654f0f 100644 --- a/src/content/docs/customizing-fossbilling/email-templates.mdoc +++ b/src/content/docs/customizing-fossbilling/email-templates.mdoc @@ -45,10 +45,10 @@ See [Twig Filters & Functions](/developing-fossbilling/twig-filters/) for all av ### Markdown Format -Default templates use Markdown for simple formatting. Wrap your content with the `apply markdown` filter: +Default templates use Markdown for simple formatting. Wrap your content with the `apply markdown_to_html` filter: ```twig -\{% apply markdown %\} +\{% apply markdown_to_html %\} Hi \{\{ staff.name \}\}, If you are reading this email, FOSSBilling is **configured properly** and is **able to send emails**. @@ -108,7 +108,7 @@ For full control, use HTML: Templates exist in two places: -1. **Module source** — `modules/{Module}/html_email/` +1. **Module source** — `modules/{Module}/templates/email/` 2. **Database** — `email_template` table (copied there when module is installed) After installation, edit templates through the admin panel or directly in the database. Changes made only to the module files will not apply until you regenerate the templates. @@ -121,4 +121,4 @@ After installation, edit templates through the admin panel or directly in the da ## Example Module -See the [example module](https://github.com/FOSSBilling/example-module/tree/main/html_email) for more template examples. +See the [core email templates](https://github.com/FOSSBilling/FOSSBilling/tree/main/src/modules/Email/templates/email) for more template examples. diff --git a/src/content/docs/customizing-fossbilling/invoice-pdf.mdoc b/src/content/docs/customizing-fossbilling/invoice-pdf.mdoc index a7c7adf..fa2a36a 100644 --- a/src/content/docs/customizing-fossbilling/invoice-pdf.mdoc +++ b/src/content/docs/customizing-fossbilling/invoice-pdf.mdoc @@ -7,13 +7,14 @@ FOSSBilling generates invoice PDFs with [Dompdf](https://github.com/dompdf/dompd ## CSS Limitations -Dompdf doesn't support everything. As of version 2.0.3: +Dompdf is not a complete PDF engine. FOSSBilling uses Dompdf 3.x, which supports many print-friendly CSS features but still has layout limitations: | Supported | Not Supported | |-----------|---------------| | CSS 2.1 and some CSS3 | Flexbox | | `@import`, `@media`, `@page` | CSS Grid | -| Basic positioning | Complex layouts | +| CSS custom properties and math functions such as `calc()` | Browser-style complex layouts | +| Basic positioning and table layouts | Splitting table rows or cells across pages | {% aside type="tip" %} Table cells can't span pages. Keep table rows compact enough to fit on one page. @@ -23,37 +24,41 @@ Table cells can't span pages. Keep table rows compact enough to fit on one page. ### Creating a Custom Stylesheet -1. Copy `/modules/Invoice/pdf_template/default-pdf.css` -2. Paste as `/modules/Invoice/pdf_template/custom-pdf.css` +1. Copy `/modules/Invoice/templates/pdf/default-invoice.css` +2. Paste as `/modules/Invoice/templates/pdf/custom-invoice.css` -FOSSBilling automatically uses `custom-pdf.css` if it exists. +FOSSBilling automatically uses `custom-invoice.css` if it exists. {% aside type="caution" %} -Editing `default-pdf.css` directly is overwritten on updates. Always use `custom-pdf.css`. +Editing `default-invoice.css` directly is overwritten on updates. Always use `custom-invoice.css`. {% /aside %} ### CSS Classes Reference ![PDF layout with CSS classes](../../../assets/invoice-layout.png) -Common classes include: +The default stylesheet uses these classes: -- `.invoice-header` — Company and client info -- `.invoice-details` — Invoice number, date, due date -- `.invoice-items` — Line items table -- `.invoice-totals` — Subtotal, tax, total -- `.invoice-footer` — Terms, notes +- `.CompanyLogo` — Company logo image +- `.TopSectionDivider` — Divider below the header area +- `.InvoiceInfo` — Invoice number, dates, and status +- `.CompanyInfo` — Seller/company heading and details +- `.ClientInfo` — Client heading and details +- `.Breakdown` — Line items, tax, discount, and total table +- `.InvoiceText` — Custom invoice text blocks +- `.InvoiceFooter` — Payment details, company footer, and signature +- `.muted-text` — Muted footer signature text ## Custom HTML Template -**FOSSBilling 0.6.0+**: Customize the HTML structure. +Customize the HTML structure by adding a custom Twig template. ### Creating a Custom Template -1. Copy `/modules/Invoice/pdf_template/default-pdf.twig` -2. Paste as `/modules/Invoice/pdf_template/custom-pdf.twig` +1. Copy `/modules/Invoice/templates/pdf/default-invoice.twig` +2. Paste as `/modules/Invoice/templates/pdf/custom-invoice.twig` -FOSSBilling uses `custom-pdf.twig` automatically. +FOSSBilling uses `custom-invoice.twig` automatically. ### Template Variables @@ -61,17 +66,24 @@ Available in PDF templates: | Variable | Description | |----------|-------------| -| `invoice` | Invoice data (id, total, items, etc.) | -| `client` | Client information | -| `company` | Your company details | -| `currency` | Currency code and symbol | +| `currency_code` | Invoice currency code for `format_currency`. | +| `css` | Contents of `custom-invoice.css` or `default-invoice.css`, inserted into the template's `