Eloquent Word Laravel Package

Getting Started

1. Install the Laravel 10-compatible major:

   composer require ambengers/eloquent-word:^5.0
   

   Use ^5.0 on Laravel 10. If you are on an older Laravel version, pin the matching package major and verify its composer.json constraints before upgrading.

2. Publish and inspect the package config/assets using the provider or tag documented in the README. Look first at:

   • the README quickstart for the exact facade/trait/class names,
   • config/eloquent-word.php for template paths, storage disk, temp paths, and placeholder settings,
   • the package tests for realistic template/render examples.

3. Start with the most common day-to-day use case: generating a contract, invoice, letter, or report from an Eloquent model and a .docx template. Create a template with simple placeholders, eager-load any relationships used by the template, map model attributes/accessors to placeholders, then either stream a download or store the generated file.

A typical integration shape is:

$invoice = Invoice::with('customer', 'lines')->findOrFail($id);

$document = Word::template(resource_path('templates/invoice.docx'))
    ->with([
        'invoice_number' => $invoice->number,
        'customer_name' => $invoice->customer->name,
        'total' => $invoice->formatted_total,
    ]);

return $document->download("invoice-{$invoice->number}.docx");

The exact facade/trait name should follow the package README; keep that call behind an application service so controllers and jobs do not depend directly on package internals.

Implementation Patterns

• Template per document type. Keep .docx templates under resources/templates or a dedicated disk, version them with the code, and map document types to templates in config or a small registry. This makes invoice/contract/report variants easy to manage without scattering paths through controllers.

• Use a presenter/DTO instead of raw models. Build an explicit array of placeholder values from the model, accessors, casts, and relationships. This avoids leaking sensitive attributes into templates and keeps placeholder names stable when the schema changes.

• Eager-load relationship data. If templates use customer, order-line, or address data, use with(...) before rendering. In queued generation, this also avoids lazy-loading failures when Model::preventLazyLoading() is enabled.

• Wrap generation in a service or action. A class like GenerateInvoiceDocument can resolve the template, prepare data, render, store, and return a download response. This is the main extension point if you later swap PHPWord configuration or add template variants.

• Store first, stream second. For user-facing downloads, generate to a temporary or private disk path, then return a streamed/download response. For auditability, keep generated documents on a private disk with a predictable naming convention.

• Queue bulk generation. Batch exports should run as jobs, one document per job or small chunk, with unique temp filenames and cleanup after upload. This keeps request memory bounded and avoids timeouts on large templates.

• Test with fixture templates. Keep a small .docx fixture in tests, generate output, and assert extracted text/XML or stored-file existence. Mock or fake the storage disk so tests do not depend on local filesystem state.

• Keep controllers thin. Controllers should authorize the model, dispatch generation, and return the response. Template mapping and document rendering belong in a service or job.

Gotchas and Tips

• 5.0 is a compatibility major. The release notes only call out Laravel 10 support. Treat it as a compatibility release rather than a feature drop, and check composer.json for PHP/Laravel constraints before upgrading. If you are not on Laravel 10, stay on the appropriate older major.

• Word can split placeholders across runs. Placeholders in .docx templates are sensitive to formatting changes. Keep placeholder text simple, in one run, and avoid applying formatting inside the placeholder itself.

• .docx is a zip/XML format. Do not read or edit templates as plain text. Validate that template files exist and use absolute filesystem paths when handing them to PHPWord or the package.

• Images, loops, and relationship blocks often have package-specific syntax. Check the README/tests for the exact placeholder conventions before building complex templates.

• Escape and sanitize user content. Treat template values as untrusted where appropriate. Avoid injecting raw HTML/XML-like content unless the package explicitly supports it.

• Watch storage paths. A public URL is not a filesystem path. Use Storage::path() or the package’s documented disk/path options when rendering from a Laravel disk.

• Clean up temp files and avoid filename collisions. Concurrent requests or queued jobs should use unique temporary names and delete intermediates after storing or streaming.

• Large documents can be memory-heavy. If generation slows down or times out, move it to a queue, simplify the template, or split the document into sections.

• Guard null relationships. Templates that reference optional relationships should receive fallback values from the presenter rather than failing on null.

• Keep package calls isolated. Because the package is a thin bridge between Eloquent data and Word templates, wrapping it in your own service makes future upgrades, template changes, and testing much easier.