Framework Laravel Package

Getting Started

This package is a fluent table builder for Laravel — you compose tables from typed column definitions ($table->addText(...), and sibling add* methods), then chain modifier methods before rendering. The 1.9 release demonstrates two of those modifiers in action:

$table->addText('period', 'Période')->right()->setDescription('Un truc de ouf!!!!');

Read this as: define the column, align its header/body right, and attach a description (a tooltip/legend shown near the column). Start by:

1. Instantiating a table (usually via a facade, service, or container binding — check the package's service provider).
2. Adding a handful of columns with addText (or wherever your own column types live).
3. Chaining modifiers (->right(), ->setDescription(...)) to validate the fluent API before wiring it into a Blade view or PDF renderer.
4. Rendering once and eyeballing the output — descriptions and alignment are visual and easy to validate by inspection.

First practical use case: a report table (invoice line items, timesheets, period summaries) where numeric columns need right alignment and columns need short explanatory text under or beside the header.

Implementation Patterns

• Column factory + modifier chain. addText($key, $label) returns a column object; every modifier (->right(), ->setDescription()) returns the same object, so order within the chain is flexible. Keep the chain on one line per column for readability in large table definitions.
• Centralise column definitions. Define a buildReportTable() method (or a dedicated builder class) that returns the table with all columns pre-modded. Controllers and views stay thin, and column metadata (alignment, descriptions) lives in one place.
• Descriptions as a documentation layer. Since setDescription() attaches human-readable text to a column, use it to explain non-obvious fields to end readers (e.g. “Net of tax”, “Incl. overtime”). This is preferable to stuffing explanations into the column label, which breaks layout.
• Right-align numeric fields consistently. Apply ->right() on any monetary, count, or percentage column in one pass. Pair it with the same alignment on totals rows so they line up.
• Compose per-section tables. For multi-section reports, build several small tables and concatenate in the view; alignment/description modifiers stay scoped per column and don't leak.
• Integration tip: if you render to PDF, verify the description rendering survives the HTML→PDF pass — some PDF engines drop title-style attributes, so confirm the package injects a real inline element rather than a tooltip.

Gotchas and Tips

• Modifier order is a red herring — but don't assume. The fluent API should make ->setDescription(...)->right() equivalent to the reverse. Test one column with reversed order to confirm the package doesn't accumulate a shared state that makes order matter.
• Descriptions are presentation-only. setDescription() likely does not affect exports (CSV/Excel) or the underlying data key. Don't rely on it as machine-readable metadata; keep source-of-truth docs in your own column config.
• Method availability differs by column type. ->right() and ->setDescription() come from a base column class; verify a custom column type you register inherits them (or implements the same traits/interface) before chaining.
• Alignment gotcha on header vs body. ->right() may align the header, body, or both depending on the renderer. Check the rendered screenshot from the release (the linked image) against your own engine to confirm expectations.
• Debugging rendered output: dump the column object (dd($column)) to see how description/alignment are stored before they hit the template — this is faster than chasing the generated markup.
• Non-ASCII labels. 'Période' works, but confirm your renderer/view declares UTF-8; header encoding issues with accented labels are a common source of mojibake in PDF output.
• Upgrade note for 1.9: if you were previously passing alignment/description via config arrays or hacking labels, migrate to the fluent methods — mixing the two patterns is where surprising precedence bugs appear.
• Extension point: override the column class (or a renderer partial) to add your own modifiers (e.g. ->monospace(), ->tooltip()), reusing setDescription as the pattern to copy.