SIGNALS Docs
Reader View

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_price or @foreach ($costs as $cost), fails to render. When the render error names that field, the render is refused with document_prices_not_included on document_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:

  • payment for receipt
  • fleet_vehicle and vehicle for fleet_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.