Document Type Registry
Contract for mapping printable document types onto resolver types, source models, permissions, categories, and aliases.
Overview
App\Services\Documents\DocumentTypeRegistry maps a printable document type such as quote or receipt onto:
- the resolver type that renders it
- the Eloquent source model class it accepts
- its label and description
- the permission checked by UI and generation flows
- an optional category and alias list
- whether a document of the type can print money
- whether a document of the type answers for the quote version
Core binds the registry as a singleton in AppServiceProvider, and the constructor registers the built-in type map. As a factual note about the current integration, PluginRegistrar::documentType() forwards registrations into this registry; this is not SDK usage guidance.
Public surface
| Method | Purpose |
|---|---|
register() |
Save or replace one document-type definition |
has() / get() |
Check for a type or fetch its full definition |
exposesMoney() |
Return whether a document of the type can print money; true for an unknown type |
pricedVariantOf() |
Return the registered priced variant of a money-free type, or null |
answersForQuote() |
Return whether a document of the type is pinned to the quote pricing revision and accepts or declines the quote version on customer approval; follows exposesMoney() when the registration sets no value, so true for an unknown type |
resolverType() |
Return the resolver type used for rendering |
modelType() |
Return the accepted source model class |
permission() |
Return the permission gate name associated with the type |
label() / filenameSlug() |
Return the display label or its slugified filename form |
all() |
Return all registered summaries |
forSourceModel() |
Return types whose source model matches a class or instance |
forSourceModelPermitted() |
Return only the types the current user may use |
typesInCategory() |
Return the types assigned to one category |
isRegisteredSourceModel() / registeredSourceModels() |
Inspect whether a model class participates in the registry |
allowedDocumentableTypeValues() |
Return the validation whitelist for documentable_type inputs |
resolveSourceModelClass() |
Resolve an input alias back to a concrete model class |
This metadata registry does not publish a separate registered-value interface. Its current framework contract is the typed public surface on this page plus the documented registration shape and runtime behavior below.
Definition shape
Each registration records this definition:
[
'resolver_type' => string,
'model_type' => class-string<Model>,
'label' => string,
'description' => string,
'permission' => string,
'category' => ?string,
'aliases' => list<string>,
'exposes_money' => bool,
'answers_for_quote' => ?bool,
]
The registry does not infer the resolver type from the document type. Shared resolvers are normal and already used by core.
description defaults to an empty string, permission defaults to documents.create, category defaults to null, aliases defaults to an empty list, exposesMoney defaults to true, and answersForQuote defaults to null, which means the type follows exposesMoney(). Exact duplicate aliases are removed while preserving first appearance. These defaults are applied when the definition is stored.
The class-string<Model> annotation and the relationship between document type, resolver type, model, and permission are static contracts. register() does not preflight the model class, require the resolver type to be registered, or verify that the permission exists. An invalid relationship can therefore be stored and fail only when a later consumer tries to use it.
get() returns the complete stored definition, including aliases. all() returns summary rows and intentionally omits aliases.
Current core mappings
Rental-backed types
| Document type | Resolver type | Notes |
|---|---|---|
quote |
rental |
standard quote; prints money |
delivery_note |
rental_dispatch |
warehouse dispatch output; money-free |
delivery_note_priced |
rental |
delivery note that prints prices; prints money |
pick_list |
rental_dispatch |
warehouse pick output; money-free |
return_list |
return_list |
dedicated resolver type; money-free |
damage_report |
rental_dispatch |
staged type with no seeded system template; money-free |
Money-free rental types
Of the rental types, only quote and delivery_note_priced are registered with exposesMoney set to true. The four money-free types render through resolvers that never build prices, totals, costs, tax, or the currency, so they still generate, finalise, share, and are approved for a rental whose money precision or currency is not recorded. A quote, a priced delivery note, and any other rental document type, including a plugin type (plugin registrations keep the true default), is refused for such a rental with rental_document_precision_missing or rental_currency_missing.
delivery_note_priced ("Delivery Note (with prices)") is the priced variant of delivery_note. It renders through the money-bearing rental resolver and has its own seeded system template and its own DNP- number sequence. A tenant whose delivery note template prints prices copies that template onto this type. pricedVariantOf('delivery_note') returns delivery_note_priced; every other type returns null.
Only a type that answers for the quote is pinned to the quote pricing revision when it is generated, and only such a document accepts or declines the quote version when a customer approves or declines it. A registration can set answersForQuote explicitly; a registration that sets no value follows exposesMoney(). Core sets quote to true and delivery_note_priced to false: the priced delivery note prints money but is never pinned, and approving or declining it records the answer on the document only. A plugin type sets no value (PluginRegistrar::documentType() forwards neither flag), so a plugin rental type prints money and is pinned. An unknown type also answers true. A money-free type is never pinned to a quote pricing revision. Approving or declining a shared money-free document never accepts or declines the quote, even when the stored document has a pin.
Money is named by one rule in App\Services\Documents\DocumentMoneyKeys. A key is split into words on every non-alphanumeric character and on camel-case and letter-digit boundaries, then lower-cased, so grand_total, GRAND_TOTAL, UnitPRICE, grand-total and line.total are read the same way. The key names money when one word, singular or plural, is on the word list (for example price, total, subtotal, cost, tax, vat, currency, value, rate, deposit, net, paid, due, credit, payment, minor), or when it holds decimal places. The safe compounds vat_number, tax_number, tax_id, field_value, frame_rate and replacement_serial are removed first. Data is normalised through JSON before the scan, so collections, models and JsonSerializable values are read as stored.
The same check runs after every render of a money-free type: document generation, workflow communication attachments, the template editor preview and the preview action. For a money-free type:
- A template that reads a money key in a
{{ }}echo or a directive expression, such as$rental->grand_total,$item->unit_priceor@foreach ($costs as $cost), fails to render. When the render error names that field, the render is refused withdocument_prices_not_includedondocument_template_id, and the message lists the fields. When the type has a priced variant, the message also names that variant's label. Raw text such as "Total" is not read. A failure that names no money field keeps its own error. - A template that reads a money key with a fallback, such as
{{ $rental->grand_total ?? '' }}, renders a blank and is not refused, because the render does not fail and the data holds no money. - Resolved data that holds a money key can only come from a plugin resolve extender. It is reported with the key paths and refused with the same code and a plugin message, before a document number is used.
- A stored document whose data holds a money key is checked against the live rental money like a quote before it is shared, finalised or approved. The missing-precision label check runs for every stored rental document.
Invoice and billing family
| Document type | Resolver type | Source model |
|---|---|---|
invoice |
invoice |
Invoice::class |
pro_forma |
invoice |
Invoice::class |
deposit |
invoice |
Invoice::class |
credit_note |
credit_note |
CreditNote::class |
receipt |
receipt |
InvoicePayment::class |
statement |
statement |
Account::class |
purchase_order |
purchase_order |
PurchaseOrder::class |
Specialist document types
Core also ships label, equipment_test_certificate, catalogue_item_spec, asset_label, virtual_stock_summary, repair_report, stock_check_report, warehouse_transfer_manifest, activity_summary, fleet_vehicle_summary, equipment_test_summary, scan_session_report, and flightcase_manifest.
Every built-in type currently uses the default permission documents.create.
Source-model resolution, permissions, and categories
forSourceModel() matches a type when its registered model_type is the same class as the supplied model or a parent class of it.
forSourceModelPermitted() applies one more filter:
return Gate::forUser($user)->allows($definition['permission']);
If there is no user, it returns an empty list. This is the path used by PrintMenu when it decides which document types are available for a record.
typesInCategory() is an exact category filter. Today the only core non-null category is certificate, so typesInCategory('certificate') returns equipment_test_certificate.
Type mapping and aliases
allowedDocumentableTypeValues() builds the finite request-validation allow-list used by GenerateDocumentData::rules(). For each currently registered source-model class it includes the exact fully qualified class name, basename, lowercase basename, snake-case basename, and every alias exactly as registered. It removes duplicates while preserving first appearance. The Rule::in(...) check does not admit other spellings.
Direct resolveSourceModelClass() calls are more permissive than that finite request-validation allow-list. They accept an exact fully qualified class name, compare basenames and registered aliases case-insensitively, and finally accept a string that ends with the model's exact basename. Consequently a direct call can resolve a differently cased alias or an otherwise unlisted namespace suffix that request validation rejects. Callers that bypass GenerateDocumentData own that distinction.
Current core aliases include:
paymentforreceiptfleet_vehicleandvehicleforfleet_vehicle_summary
So resolveSourceModelClass('payment') resolves to InvoicePayment::class, and resolveSourceModelClass('vehicle') resolves to Account::class.
filenameSlug() is separate from the registry key. It slugifies the current label, which is why receipt produces the filename stem from Payment Receipt rather than from the raw type name.
Collisions and failure modes
register() records definitions in an associative array keyed by document type. Registering the same type again replaces the prior definition. Duplicate keys are not rejected.
Cross-model alias collisions are not rejected either. Resolution walks the unique source-model classes in their current first-appearance order, gathers all aliases belonging to each model, and returns on the first match. If two different source models claim the same alias, the first matching model in current registry insertion order wins.
That insertion order is also externally visible. all(), forSourceModel(), forSourceModelPermitted(), and typesInCategory() do not sort their results; filtering retains the current registry order. PrintMenu consumes that order without sorting when it builds the permitted print choices for a record. Replacing an existing document-type key updates its definition without moving that key to the end of the map.
get(), resolverType(), modelType(), permission(), label(), and filenameSlug() all fail through get(), which throws InvalidArgumentException with Unknown document type [{$documentType}]. exposesMoney() does not throw: it returns true for an unknown or blank type, so a money guard fails closed.
resolveSourceModelClass() throws InvalidArgumentException with Unsupported documentable type [{$documentableType}] when the supplied input does not match any registered model or alias.
Worked example
These are all valid current lookups:
$registry = app(DocumentTypeRegistry::class);
$registry->resolverType('deposit'); // invoice
$registry->modelType('receipt'); // InvoicePayment::class
$registry->resolveSourceModelClass('payment'); // InvoicePayment::class
$registry->resolveSourceModelClass('vehicle'); // Account::class
The important contract distinction is that deposit is a document type, while invoice is the resolver type that actually renders it.