Download the PHP package jiannius/atom without Composer

On this page you can find all versions of the php package jiannius/atom. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package atom

Atom

A Laravel UI component library built on Tailwind + Alpine + Livewire 4. Atom ships ~50 anonymous Blade components, a Livewire trait, an atom() runtime singleton for dispatching modals/toasts/alerts/confirms from PHP, a set of Laravel macros, and a pre-built JS/CSS bundle that the package serves itself — there is nothing to npm install in your host app.


Requirements

Dependency Version
PHP ^8.3
Laravel (illuminate/support) ^13.0
Livewire ^4.0
Intervention Image ^3.0

Installation

The service provider (Jiannius\Atom\AtomServiceProvider) auto-registers via Laravel's package discovery. It will:

No publishing step is required to get started.

Page boilerplate

Use <atom:html> once at the top of any full-page Blade view. It writes the <html>, <head>, meta tags, Tailwind base, atom's bundled CSS/JS, and your host app's Vite entry.

Useful <atom:html> props (all optional):

Prop Purpose
title <title> and OG tag (falls back to config('page.title')).
description Meta description / OG description.
image OG image (defaults to storage/img/logo.png).
canonical Canonical URL.
hreflang Array of locale alternates.
jsonld Raw JSON-LD payload.
gtm / ga / fbp Tracking IDs for GTM, GA, Facebook Pixel.
fonts Google Font family to preload (default inter).
dark Opts the page into dark mode (off by default, on every layout too). Adds class="dark" to <html> and emits the window.darkmode() bootstrap, which then follows the stored preference or, with none, the visitor's prefers-color-scheme. Required for <atom:darkmode-toggle> to work.
styles Additional stylesheet URLs.
scripts Additional script URLs.
editor Loads the editor CSS chunk (for pages using <atom:editor>).
vite Vite entries from your host app.
noindex Sets robots to noindex,nofollow.

The package's own JS/CSS bundle is served from /atom/{file} (immutable, hashed via dist/manifest.json); you do not need to add it to your Vite config.

Component directory

With the package installed and APP_ENV=local, visit /atom/docs in your app for a browsable directory of every component: live previews, copyable code snippets, auto-generated prop tables, and searchable icon/logo galleries. The routes are not registered outside the local environment.

Service provider entry points (reference)

If something feels magic, the answer is almost always in src/AtomServiceProvider.php (boot order: routes → migrations → translations → views → components → tag compiler → date facade swap → macros → asset routes → /atom/action/{name} POST endpoint).


The <atom:...> tag syntax

src/Services/TagCompiler.php rewrites tags before Blade compiles:

You write Resolves to File
<atom:button>...</atom:button> <x-atom::button>...</x-atom::button> components/button/index.blade.php
<atom:icon.check/> <x-atom::icon.check/> components/icon/check.blade.php
<atom:button.group>... <x-atom::button.group>... components/button/group.blade.php
<atom:input.text/> <x-atom::input.text/> components/input/text.blade.php

Dot paths map to subdirectories. The classic <x-atom::...> form still works — <atom:...> is preferred for terseness.


Quickstart example

A typical Livewire 4 form using Atom:


Helpers

The atom() singleton

app('atom') (aliased) is a single entry point for runtime UI dispatch. Inside a Livewire component, prefer the trait methods ($this->toast(...)) — they delegate here but are shorter. Use app('atom')->... from controllers, jobs, or anywhere outside the component class.

All heading, subheading, and message strings are auto-passed through t() for translation.

Global functions (src/Helpers.php)

Function Purpose
t($key, $count = 1, $params = []) Translation shim. Number → trans_choice, array → __($key, $array), scalar → __($key, $params). Used internally by every component.
num($value) Wraps Laravel's Number helper. Adds ->currency($iso, $rounding, $bracket, $abbreviate, $maxPrecision, $roundingMode) (2dp, rounded half-up; $roundingMode is half-up, half-even or half-down) and ->filesize($precision). All other Number::* methods proxy through.
carbon(...$args) Returns a Jiannius\Atom\Services\Carbon instance.
js($value) Alias for Js::from().
is_enum($value) True for UnitEnum / BackedEnum.
is_using_trait($class, $trait) True if $class (recursively) uses $trait.
safe_url($url) The URL unchanged if it is http, https, mailto, tel, sms or scheme-less, otherwise null. Reads the URL the way a browser does (entities decoded, tabs and newlines dropped, leading control characters stripped, scheme lowercased). Makes a URL scheme-safe and nothing more: //evil.com is allowed, so a redirect built from user input must also check the host. Every atom component that takes an href uses it.

Examples:

currency() rounds half-up (away from zero) by default, so 10.185 is 10.19; before this change it rounded half-even (10.18). Pass roundingMode: 'half-even' (or 'half-down') for another mode, in any case. roundingMode does not affect the $rounding 0.05 step or $abbreviate. The input is a float: 175 * 9.825 is 1719.3749999999998 and prints 1,719.37, so pass an exact value when a sum lands on a tie. In JavaScript, (0.065).currency(symbol, round, maxPrecision) takes the same maxPrecision (a number or numeric string, clamped 2 to 100; null, NaN or blank mean unset); without it the JS default allows up to 3 decimals, so it is not the same as the PHP default.

The AtomComponent Livewire trait

use Jiannius\Atom\Traits\AtomComponent; on any Livewire component to get:

Names the trait occupies

A trait method loses to a method of the same name on the class itself — with no error. So a component that defines one of these shadows atom's version. Whether that matters depends entirely on who calls the name, and the two halves are not equally risky.

Safe to shadow — nothing in atom ever calls these on your component. They're sugar that delegates to app('atom'), there for you to call and no one else. Define your own toast() and you get yours; you'll know, because you wrote it.

modal, command, toast, alert, confirm, action, wirekey, verifyRecaptcha

action is protected (see Upgrading to 3.25) — shadow it if you like, but define yours protected too. A public function action() on your component is callable from the browser as $wire.action(...), which is the exposure 3.25 removed.

Silent if shadowed — atom or Livewire invokes these by name, so redefining one kills the feature behind it with nothing to show for it. All of them are prefixed for exactly this reason; the prefix is the protection.

Invoked by Breaks
$_breadcrumbs, $_table, $_editor, $_recaptcha the toTable() macro and the blades sort, pagination, checkboxes
mountAtomComponent, updatedAtomComponent, updatingAtomComponent Livewire, by convention breadcrumbs, editor uploads, trashed-toggle clear, the raw: table-sort signature gate
resetTableCheckboxes, selectAllTableMatching, toggleTableShowSelected, clearTableSelectAll atom's markup, by name the checked-bar buttons no-op
tableSelection, tableSelectionQuery, tableRowsQuery, getTableCheckboxes, isTableSelectAll, isTableShowSelected, isTableShowTrashed each other, and your own items() bulk actions target the wrong rows
$paginators, getPage, gotoPage, nextPage, previousPage, resetPage, setPage, queryStringHandlesPagination Livewire's WithPagination pagination
_startUpload, _finishUpload, _removeUpload, _uploadErrored Livewire's WithFileUploads file uploads

Yours to define: breadcrumbs (optional), tableQuery (required for tableSelection()), tableSelectionQuery (override for sticky selection).

Nothing else is reserved. The computed property feeding <atom:table :paginate="..."> is yours to name: atom neither defines nor looks for items, rows, records, data, or anything like them. tests/Feature/AtomComponentSurfaceTest.php pins this list, so it can't drift from the trait without a failing test.

The Enum trait

use Jiannius\Atom\Traits\Enum; on backed enums to get the convention used by Atom's status badges and selects:


Macros

Eloquent / Query Builder (src/Macros/Builder.php)

filter() knows about: named scopes (search, byFoo), enum casts, JSON columns, date columns, and the key:operator syntax ('price:>=' => 100).

filter() reads keys and values as untrusted input, but it is not an allow-list. What it refuses: a key that is not a plain column name (optionally :operator, or column.path on a JSON column), a column listed in the model's $hidden or, when the model sets $visible, any column not listed there ($visible is a serialisation list, so one that omits created_at, status or a foreign key silently drops filters on them), an operator other than =, !=, <>, <, <=, >, >=, like and not like, and a value shape that makes no sense for the column (it is skipped, never an error). Date columns are filtered through quoted whereDate(). On a plain column a list value means "one of" (= or no operator) or "none of" (!=, <>); a list with <, <=, >, >=, like is skipped, and so is a date object with like. On a JSON column a list means "contains all of" (= or no operator) or "does not contain all of" (!=, <>). It reads the model's $hidden and $visible properties only: not makeHidden() / makeVisible() on an instance, and not sensitive columns you did not list. What it does not refuse: any other column of the table, and any named scope, which receives the value as sent (strings, arrays, dates). A client that can replace a public $filters (Livewire allows it) can therefore filter on every column the model does not hide, and call every scope. When that matters, either use WithUrlFilters, whose declared keys are such an allow-list enforced on every update, or pass filter() only the keys you allow, e.g. filter(Arr::only($this->filters, ['search', 'status', 'dates'])), and keep scopes safe to call with arbitrary input. Don't mark a $filters that atom's table controls bind to (wire:model="filters.search") as #[Locked]: Livewire then refuses every update from them, so search, filter selects and chips stop working. #[Locked] only fits a $filters the server sets and no wire:model touches.

Request (src/Macros/Request.php)

Str / Stringable (src/Macros/Str.php)

Arr (src/Macros/Arr.php)

ComponentAttributeBag (src/Macros/ComponentAttributeBag.php)

Used inside component templates:


Component catalog

All components live in components/. Open components/<name>/index.blade.php (or components/<name>.blade.php) to see the canonical @props([...]) list. The tables below list the most-used props per component.

Form inputs

Tag Notable props / subcomponents
<atom:input> name, type (text, email, password, number, tel, color), label, caption, prefix, suffix, required, error. Subs: <atom:input.text>, <atom:input.email>, <atom:input.tel>, <atom:input.color>, <atom:input.field>, <atom:input.prefix>.
<atom:textarea> name, label, caption, rows (default 3), autoresize, variant="transparent".
<atom:select> options — an array for a static list, or a string naming a GetOptions set to fetch remotely. Plus name (field name, not the option set), label, caption, variant (native (default), listbox, filter), required, error, prefix, suffix, inline; filters, multiple, searchable, clearable on listbox; table-filter on native/listbox registers the field as a chip in <atom:table.filters> (key = wire:model, chip name = label). Children: <atom:select.option>, <atom:select.group>.
<atom:checkbox> name, label, caption, align (start, center, end). Group with <atom:checkbox.group>.
<atom:radio> Same as checkbox. Group with <atom:radio.group>.
<atom:toggle> name, label, caption. Group with <atom:toggle.group>.
<atom:slider> Range slider on a native <input type=range>. name, label, caption, min (0), max (100), step (1), value, bubble (value shown on interaction), labels (min/max at track ends), required, disabled. wire:model binds via x-modelable.
<atom:rating> Star rating input + display. name, label, caption, count (5), value, half (half-step selection), readonly (display a fixed/average value), clearable (re-click resets to 0), icon (swap the star for any atom icon). wire:model binds via x-modelable.
<atom:date-picker> name, variant (date, range, calendar), label, caption, inline, prefix, suffix. Subs: <atom:date-picker.date>, <atom:date-picker.range>, <atom:date-picker.calendar>. The input also takes a typed date, committed on blur or Enter: the display format (01 Oct 2024), day-first numerics (01/10/2024) or ISO; a range as from - to or from to to. An entry that does not parse is put back, never sent.
<atom:time-picker> name, label, caption, invalid, inline.
<atom:uploader> label (default Upload), variant, size. Drop variant: <atom:uploader.dropzone>.
<atom:editor> Tiptap rich text. name, label, caption, readonly, autofocus, variant="transparent", placeholder, toolbar, mention. Many sub-buttons under <atom:editor.button.*> and contextual menus under <atom:editor.menu.*>. Requires <atom:html editor> on the page.

Buttons & links

Tag Notable props
<atom:button> type (submit, delete), variant (primary, danger, accent, ghost, link, facebook, google, linkedin, whatsapp, telegram), size (xs, sm, md, lg), block, href, icon, iconSuffix, inverted, newtab. Wraps wire:click, dispatches confirmed for type="delete" (auto-confirmed → $wire.delete()).
<atom:button.group> Layout helper for adjacent buttons.
<atom:link> href, icon, iconSuffix, variant="accent", newtab, rel.

An href is only followed if it is http, https, mailto, tel, sms or scheme-less; see Upgrading to 3.29.13.

Display & typography

Tag Notable props
<atom:heading> size (xs, sm, default, lg, xl, or <n>px) — each size sets both a font size and a weight. level (1..6) renders a real <hN> instead of the default <div>; see Heading levels below.
<atom:subheading> Same as heading, smaller / muted.
<atom:caption> Small muted text.
<atom:label> icon, align.
<atom:kbd> Keyboard-key caps. keys (space/+-separated, maps cmd→⌘, shift→⇧, alt→⌥, ctrl→⌃, enter, esc, arrows, …); or a single cap from the slot: <atom:kbd>Esc</atom:kbd>.
<atom:avatar> src, name, initial, square (default true), size (xs..xl). Stack: <atom:avatar.group>.
<atom:badge> status (enum-aware), size (xs, default, lg), icon, color, label. Group: <atom:badge.group>.
<atom:card> inset, subtle, divided, variant (stats, chart), heading, data, indicator, trend, color.
<atom:chart> Standalone ApexCharts chart. type (bar, area, trend), data (bar/area: label/value/tooltip rows; trend: plain number array), color (red/green/orange/gray or #hex), max (['value'=>, 'label'=>] goal line), min. Default height h-64 (h-16 for trend), override with a h-* class.
<atom:callout> icon, heading, content, variant (info, success, warning, danger, error), closeable.
<atom:skeleton> Animated loading block.
<atom:placeholder-bar> size="100%x20px".
<atom:empty> icon (default inbox), size, subtle, heading, subheading.
<atom:profile> name, avatar, email, size.
<atom:icon.*> 200+ icons. Examples: <atom:icon.check/>, <atom:icon.arrow-left/>, <atom:icon.delete/>. Browse components/icon/.
<atom:logo.*> Payment / brand marks: apple-pay, fpx, google-pay, ipay88, master, senangpay, stripe, tng, visa.

Heading levels

<atom:heading> renders a <div> unless you pass level, because most headings in an app UI are card titles, stat labels and table captions — visual, not structural. size and level are deliberately independent: size is how big it looks, level is where it sits in the document outline.

<atom:layouts.sidebar> supplies the page's <h1> itself, from its title prop — visually hidden, since the visible title comes from <atom:breadcrumbs>, which is a nav landmark and emits no heading element. So you do not need an <h1> in the page body; start at level="2".

Pass level where a section genuinely nests, and leave it off elsewhere:

A suggested mapping when a heading is structural: xl → level="1" (only outside the sidebar layout), lg → 2, default → 3, sm/xs → 4.

Feedback & overlays

Tag Notable props
<atom:modal> name (required for atom()->modal($name) to find it), inset, dismissible, closeable. Trigger via <atom:modal.trigger name="..."> or $this->modal('name')->show() from PHP.
<atom:alert> Window-bound. Triggered by atom()->alert(...). Config keys: heading, subheading, message, variant, button, onDismissed.
<atom:toast> Window-bound. Triggered by atom()->toast(...). Config keys: message, variant (success, warning, danger), delay (default 3000), position (top, bottom, center), align.
<atom:confirm> Window-bound. Triggered by atom()->confirm(...). Supports password, passphrase, optional reason field. Wires onAccepted / onRejected to Livewire methods.
<atom:tooltip> interactive, position (top, bottom, left, right), align (start, center, end), content, kbd, toggleable.
<atom:dropdown> position (bottom, top), align (start, end), locked.
<atom:context-menu> Right-click menu opened at the cursor. locked. Default slot = the right-clickable target; <x-slot:menu> holds <atom:menu.item>s. Reuses <atom:menu>.
<atom:lightbox> Image lightbox; click any <img> inside to zoom.

The four window-level overlays (alert, toast, confirm) are usually dropped once in your root layout — drop them in <atom:layouts.sidebar> or near <atom:html> and dispatch from anywhere.

Layout & navigation

Tag Notable props
<atom:form> inset. Wraps form, handles auto loading state on submit.
<atom:form.modal> name, cols (auto, 1, 2, 3), submit (Save label), dismissible, escapable, closeable. Modal + form + sticky bar: Save on the left, and on the right the optional named slots actions (anything that should stay visible while the form scrolls, e.g. a running total) and delete, in that order. With only delete, or neither, the markup is unchanged.
<atom:table> empty, paginate, maxRows (array of row options), skeleton, trashed, selectAll, stickySelection. Slots: columns, rows, header, checked (bulk-action bar), footer. Children: <atom:table.column>, <atom:table.row>, <atom:table.cell>, <atom:table.checkbox>, <atom:table.search>, <atom:table.filters>, <atom:table.trashed>, <atom:table.actions>, <atom:table.pagination>. Driven by $_table state on the Livewire component. See Table selection.
<atom:tabs> tabs (array), size (sm), variant (button, border). Child: <atom:tabs.item>.
<atom:list> heading, scrollable (default true). Child: <atom:list.item>.
<atom:menu> popover. Child: <atom:menu.item>.
<atom:navlist> Sidebar nav container. Children: <atom:navlist.item>, <atom:navlist.group>, <atom:navlist.badge>.
<atom:navlist.group> heading, expandable, expanded (default true), hiddenIfEmpty (default true), persistKey. See Remembering collapsed groups.
<atom:breadcrumbs> heading (default true). Reads $_breadcrumbs populated by your breadcrumbs() method. Wrap it in @persist('breadcrumbs') so the trail survives wire:navigate: without it each page starts a fresh trail from its own declared crumbs, so pushed crumbs don't accumulate and a crumb (or Back) returns to the bare URL, without the query string (filters, page) you left it with.
<atom:calendar> Month, week and day calendar with a toolbar. wire:model binds the anchor date (Y-m-d); with none it is static. Props: items (an array, or fn ($from, $to) => ... for the visible window), views, view, week-start, weekend, max, time-format, date-format, selectable, draggable, resizable, slot-duration, scroll-time, now-indicator, month, name. Events: calendar-select, calendar-item-move, calendar-item-resize, calendar-item-click. See Calendar.
<atom:separator> align (left, center, right). Slot becomes the label.
<atom:layouts.auth> Centered auth layout (login, register, forgot password). Props: title, noindex, dark, vite.
<atom:layouts.sidebar> App layout with sidebar + top bar. Props: title, noindex, dark, editor, styles, scripts, vite. Pass dark to get the darkmode bootstrap and the header's switcher.

Remembering collapsed groups

An expandable group's open state lives in Alpine, so it resets on every page load. Give it a persist-key and it's remembered in localStorage instead:

prop default behaviour
persistKey null When null, behaves exactly as before — no storage read, no write.

expanded is only the starting state. A stored value always wins, so a group rendered :expanded="false" that the user has expanded stays open across reloads. That precedence is the point of the feature, and the answer to "why is my :expanded="false" ignored?"

Three things worth knowing:

Storage access is wrapped both ways: hardened browsers and Safari private mode throw on localStorage, and an uncaught throw would take the Alpine component down and stop the group toggling at all. It degrades to today's behaviour instead. Persistence is per-browser only — there's no server-side or cross-device state.

Miscellaneous

Tag Notable props
<atom:copy> value — copy-to-clipboard button.
<atom:darkmode-toggle> Dark-mode switcher. Needs the page to pass dark to <atom:html> or its layout — without it window.darkmode() is never defined. The sidebar layout renders its own toggle when dark is set.
<atom:dd> Definition list. Child: <atom:dd.group>.
<atom:embed> src, icon, file — embeds image / video / YouTube / file preview.
<atom:error> Plain error message slot.
<atom:html> Page boilerplate (see Page boilerplate).
<atom:sharer> sites (array), url, title — social share buttons. atom does not bundle sharer.js: load it on the page (<script src="https://cdn.jsdelivr.net/npm/[email protected]/sharer.js"></script>) or the share buttons do nothing (the copy-link button works without it). The default sites (facebook, twitter-x, linkedin, whatsapp, telegram, email) were checked against sharer.js 0.5.4; a site needs an atom icon of the same name.
<atom:whatsapp> number, text — floating WhatsApp button.

Table selection

Add checkbox to a header column and :checkbox="$item->id" to the matching cell:

Ticked ids collect in $_table.checkboxes and survive pagination and sorting, so a selection can span pages. The header checkbox selects or deselects the current page only. Bulk-action buttons go in the checked slot — that bar replaces the table header while anything is selected and shows the running count.

Cross-page "Select all N" — :select-all

Once a subset is ticked, a Select all N button appears. It sets a $_table.select_all flag rather than materialising an id list, so it costs the same for 20 rows or 200,000. Ticking an individual row or the header exits the mode.

Requires a tableQuery() on the component — the full scoped and filtered query ($this->filters is client-controlled; see what filter() does and does not refuse):

Bulk actions then run off tableSelection(), which covers both modes:

Selection that survives a filter — :sticky-selection

By default a filter change, a search, or the trashed toggle clears the selection — the ticked rows may no longer be on screen, and a bulk action over invisible rows is a nasty surprise. Pass :sticky-selection for the opposite trade: keep the ids so a user can build one batch across several searches (tick 2, search, tick 1 more, act on all 3).

select_all still drops on a filter change — it means "everything matching this query", which stops being true the moment the query changes. The trashed toggle still clears everything, since live and soft-deleted rows aren't one result set. A persistent Clear selection appears in the checked bar, because part of the selection is off-screen and the user can't untick what they can't see.

The header slot also stays on screen instead of being swapped out for the checked bar — the two stack. Searching while holding a selection is the whole flow, and a table that hides its own search box the moment you tick a row can't support it.

Reviewing the batch — "Show selected"

A search hides part of the selection, so the checked bar carries a Show selected toggle that lists the selection instead of the filtered rows, search ignored. Flipping back restores the search results. Render the rows from tableRowsQuery() to wire it up:

The computed property is yours to name; <atom:table :paginate="$this->items"> is the only thing that has to agree with it. What atom owns is listed under Names the trait occupies.

Ticked rows stay unticked-able while the toggle is on, which is how a user prunes a batch they can no longer find by searching. The flag clears with the selection, and falls back to the filtered rows if the last row is unticked while it's on — otherwise the table would empty out and take its own toggle with it.

Note this is a filter to the selection, not a union with it: the search keeps returning what actually matches, so a 500-row batch never floods a result set and the paginator total stays honest.

This prop requires tableSelectionQuery() — the scoped but unfiltered base the checked ids resolve against:

Without it, ids ticked under an earlier filter get silently intersected away by the current one: the bar reads 3 selected and the delete hits 1. It defaults to tableQuery(), so a table that doesn't opt in is unaffected. It deliberately does not default to a bare newQuery() on the model — that would make the prop work with no override, but stays tenant-safe only where scoping is a global scope, and the consuming app is the only party that can say what "unfiltered but still scoped" means.

Clearing from a custom filter control

<atom:table.search>, <atom:select.filter> and <atom:date-picker.range> already dispatch the event. A hand-rolled control opts in the same way:


Filters in the URL — WithUrlFilters

A user filters a listing, opens a record, comes back through the breadcrumb and finds every filter gone: the filters only ever lived in Livewire state. ?page= and ?tab= already survive the trip because they are in the URL, and the breadcrumb already saves the listing's full URL. WithUrlFilters puts the filters there too (?search=ap&status[0]=fresh&region=SG).

It is opt-in: a component that does not use it declares no query string and is unchanged. It is not automatic because nested components (pickers, footprints, report panels) often carry a $filters of their own and would fight over ?status=.

Each declared key becomes one flat query key through Livewire's dotted queryString entries (filters.status as status), with history: false (replace, so typing does not stack history entries) and the default as except (a filter that returns to its default leaves the URL). Two optional methods: urlFiltersProperty() (default 'filters') and urlFiltersPrefix() (default '', for a page with two listings: 'claims_' gives ?claims_status=). A key must be a plain identifier (letters, digits, underscore: it becomes a query key, so no ., no col:operator) or the component throws at mount. Filter on an operator through a named scope instead. A key (with its prefix) that another query-string entry already uses also throws at mount: page on a component that uses WithPagination (every AtomComponent does), your own queryString, a #[Url] property (a host tab is one of these; a filter named tab or page is fine on a component with neither). A custom paginator page name (->paginate(10, pageName: 'p')) cannot be seen at mount, because Livewire registers it only when the paginator is built; the trait checks at the end of the initial render and throws the same LogicException if a filter key (with its prefix) equals a page name. Without it the two fight over one query key: ?search=ap is read as page "ap" while it also filters, and nextPage() is a TypeError. Give the filter another key or a urlFiltersPrefix(), or the paginator another pageName. The check does not run on a Livewire update request ($paginators is a public property, so a client can write any name into it and it would be a 500), so a page name your component registers only on a later request is not caught. WithoutUrlPagination does not change either rule: it only stops Livewire writing the page to the URL, it still reads it from the query (?search=ap makes the page "ap"), so such a component reserves page and is checked too.

The declaration is an allow-list

The browser controls the URL and, with Livewire, a public $filters; atom's own filter() macro refuses unsafe shapes but still filters any visible column and calls any named scope (see filter()). A link planted in front of another user would otherwise reach all of it. So the declaration is enforced where a value arrives, and the two paths fail differently on purpose:

This is why the property must not be #[Locked] (the table controls bind wire:model="filters.*", and Livewire refuses every client update to a locked property): the trait is the gate instead. It covers named-scope keys and plain column keys alike, because neither can reach filter() unless declared. It does not replace filter(Arr::only($this->filters, [...])) for a component that does not use the trait, nor the values you declare: a declared status scope still receives whatever shape-valid value arrives, so keep scopes safe for arbitrary input.

Defaults and "All"

Breadcrumbs, and what comes back

The crumb and Back return to the URL the breadcrumb saved when the user left, which carries the filters (and ?page=). That only works when the trail outlives wire:navigate: wrap <atom:breadcrumbs /> in @persist('breadcrumbs'), or each page starts a fresh trail from its own declared crumbs and the saved URL is lost (without it a crumb returns to the bare URL). The browser's Back button needs nothing: Livewire's history: false replaces the entry, so the filtered URL is the one in history.

Livewire's JS writes a list as status[0]=a&status[1]=b; a hand-written status[]=a link is read correctly by PHP but rewritten by the browser on load. Generate links with the indexed form.

Sort is not persisted. If it ever is, the URL value must be re-checked on mount with TableSort::isUnsafeFromClient(): updatingAtomComponent() only guards a browser update, and a URL value is not one. The seam is documented on mountWithUrlFilters().

tests/Feature/UrlFiltersTest.php and tests/e2e/url-filters.spec.js (fixture tests/Fixtures/UrlFiltersFixture.php) pin all of the above.


Calendar

<atom:calendar> is a month, week and day calendar with a toolbar (today, previous and next, a date jump, a view switcher). It lays out the items you give it, lets people click, drag-select to create, and move or resize an item with the pointer, and tells your code what they did through events. It saves nothing itself. Live previews: /atom/docs/calendar (local environment).

Quick start (Livewire)

Bind the anchor date with wire:model and pass the items as a closure of the visible window. The method behind the closure must be protected: the view is bound to the component, and a public method would be callable from the browser.

create(), reschedule() and edit() are Livewire actions, so the browser can call them with any arguments: authorise and scope them as you would any action. create() and reschedule() return true once they have saved, and the tag turns anything else into a refusal, see Saving a change. The query asks for ends_at >= $from, a harmless over-fetch of anything that ends exactly at the window's start, so that an item with no length that sits on the window's first instant is not dropped.

How the window and the data flow work

Props

Prop Default
items [] An iterable of items, or a closure fn (Carbon $from, Carbon $to) => iterable.
views ['month'] Any of month, week, day. More than one shows a switcher.
view first of views The view it opens in.
week-start monday Any weekday name.
weekend ['saturday', 'sunday'] The days that get the weekend tint; pass your own where the weekend is not Saturday and Sunday.
max 3 How many rows a day shows in the month (and in the all-day row of the week and day views) before "+N more". false, 0 or none shows every row.
time-format g:i A Times on items, in the grid and in labels. H:i for 24-hour.
date-format j M Y Dates in labels, such as the name of a day.
selectable off Click or drag over empty space to create (fires calendar-select).
draggable on Items can be moved. An item's own draggable wins.
resizable on Items can be pulled by their end. An item's own resizable wins.
slot-duration 30 Minutes a slot of the time grid is, and what a drag snaps to: 5, 10, 15, 20, 30 or 60.
scroll-time 06:00 The time the week and day views open at.
now-indicator on The red "now" line in the week and day views.
month none The anchor of a calendar with no wire:model.
name none A handle of your own: the ids inside the calendar are built from it.

time-format and date-format take a set of date() tokens: g G h H i a A for a time, d j D l m n M F y Y for a date, plus spaces, digits, punctuation and non-ASCII text (Y年n月j日). There is no escape character, any other ASCII letter is refused, and a format that is refused, or has none of its kind's tokens, falls back to the default. Month, week and day titles are written the way the locale writes them (October 2026, 2026年10月) and are not affected by date-format.

Anything else you put on the tag (class, data-*, x-on:*) goes to the root element. It is a width: 100% container; give it a width with a utility class. The week and day views scroll sideways where a week does not fit (a column is never narrower than --atom-calendar-min-column, 6rem), and --atom-calendar-hour (3.5rem) and --atom-calendar-grid-height (min(70vh, 48rem)) set an hour's height and the grid's height.

Items

An item is an array (or Arrayable):

Key Required
id yes An integer or a non-empty string, unique in the calendar. The browser keys items by string, so 1 and '1' are one item. A repeated id keeps the first item and reports the rest.
title yes Plain text. It is never printed as HTML.
start yes A date or an instant, see below.
end no See below. null is no end.
all_day no Defaults to true for a bare Y-m-d start, false for an instant.
color no A preset name, a name you added, a hex colour, or a backed enum with a color() method.
icon no The name of an Atom icon (check, calendar). Anything that is not one is ignored.
danger no The overdue look: red title, a warning icon, and "Overdue" for screen readers.
href no Makes the item a link. It goes through safe_url(), so a javascript: URL is dropped and the item becomes a button.
draggable, resizable no Override the calendar's props for this item.

Dates. A DateTimeInterface and an ISO string with an offset are exact instants. A string with no offset (2026-10-09 09:30) is read in config('app.timezone'). A bare Y-m-d is a calendar date and is never converted. An all-day item given an instant takes the viewer's date of that instant.

Ends. An all-day item's end is the last day, included (start 2026-10-05, end 2026-10-09 covers five days); given an instant, it covers up to one second before it, so a stored end of local midnight after the last day works. A timed item's end is exclusive. An end that is missing, unreadable or not after start is no end: the item is a short block (a dot, in the month).

A missing id, title or start throws an InvalidArgumentException, because that is a bug in the code that builds the items. A start that cannot be read skips the item and reports it once.

Colours. red, orange, yellow, green, blue, purple, black, zinc and gray are presets, each a tint, an accent edge and a dot that read in light and dark, with the text left neutral. An item with no colour, or a name the calendar does not know, is zinc. A hex colour (#rgb, #rgba, #rrggbb, #rrggbbaa) is used as it is, and its edge is adjusted where it would not show. Add or replace a preset in config/atom.php:

Names are lowercase letters, digits and dashes; a key you leave out keeps the preset's. Tailwind has to see those class strings, so make sure your build scans the file that holds them.

Dates and timezones

Everything the calendar shows and says is in the viewer's timezone, Jiannius\Atom\Services\Carbon::getLocalTimezone() (the signed-in user's timezone, else the TIMEZONE environment variable, else Asia/Kuala_Lumpur): the same one local() and pretty() use, and not config('app.timezone'). The browser's own zone never matters.

Set the zone where it is read from. TIMEZONE is read with env(), and env() is null once php artisan config:cache has run unless the value is a real environment variable of the server (the web server's or the container's, not only a line in .env). So give each user a timezone, or set TIMEZONE in the server's environment when config is cached: with neither, everyone gets Asia/Kuala_Lumpur. A user whose timezone is empty or is not a zone name PHP knows is shown config('app.timezone') instead, and it is reported once, rather than the calendar throwing.

Convert every date the calendar gives you with Calendar::fromLocal() (Jiannius\Atom\Services\Calendar). Events carry wall-clock strings (2026-10-09T09:30, or 2026-10-09 for days), and fromLocal() turns one into an instant in the application timezone, daylight saving included. It throws InvalidArgumentException for anything that is not Y-m-d or Y-m-dTH:i[:s] with no offset. Do not hand the string to Eloquent as it is, and do not give it a Carbon in another zone: Eloquent writes a Carbon's wall clock without converting it. A bare date (allDay: true) is a date, not an instant: store it as one, or add the day after its end as in the example above.

Building dates for the viewer. Calendar::now() is the current moment as a Carbon in the viewer's timezone, so Calendar::now()->startOfWeek() is the start of the viewer's week and not the server's (the docs demos use it). Calendar::timezone() is the viewer's zone name and Calendar::appTimezone() is config('app.timezone'), the zone fromLocal() returns and the items closure's $from and $to are in. Plain now() is in the application timezone.

Events

The calendar dispatches bubbling events from its root. Listen with x-on: on the tag, on an element around it, or on document. Times are the viewer's wall clock.

Event Detail
calendar-select { start, end, allDay, waitUntil } Click or drag over empty space, on a selectable calendar. Not cancelable. For days (the month, the all-day row) start and end are Y-m-d and end is the last day, included: one clicked day has start === end. For a time (the time grid) they are Y-m-dTH:i and end is exclusive, the first minute after the last slot.
calendar-item-move { id, start, end, allDay, waitUntil } An item was dropped somewhere else, with its length and, in the month, its time of day kept. end follows the same rules, and is null for a timed item that has none. Cancelable.
calendar-item-resize { id, start, end, waitUntil } An item's end was pulled. start stays. Cancelable.
calendar-item-click { id } An item without an href was clicked, or Enter or Space was pressed on it. This is also how a keyboard reaches an item: open your edit form from it.

preventDefault() on a move or a resize says no, and the item goes back at once. A drop that lands where the item already was fires nothing.

Saving a change: use waitUntil

Pass the promise of your save to waitUntil() while you handle the event, as the example above does with $wire.reschedule(...):

where reschedule() ends with return true; once it has saved.

Keyboard, touch and screen readers

Without Livewire

With no wire:model the calendar is static. It shows month (or the current month), lays out the items it is given, and switches views, but has no previous, next, today or date jump. Events still fire, so you can drive it from Alpine. Nothing sends a payload, so a moved item stays where it was dropped.

Upgrading from the event-calendar wrapper

The old <atom:calendar> wrapped @event-calendar/core. It is gone, together with that package and its calendar JS chunk and CSS file, and the new component is built into atom.js and atom.css. The tag is the same, nothing else is. A render throws, naming the attribute and what replaces it, when the tag itself carries any of these: the props modes and periods; an x-model (with or without modifiers; wire:model is fine); or an x-on: or @ listener, with any modifier (.window, .prevent...), for calendar-date-clicked, calendar-date-selected, calendar-event-clicked, calendar-event-dropped, calendar-event-resized, calendar-changed or calendar-mounted. Anything that is not on the tag cannot be seen, and does not throw: it stops working without a message. That is a $dispatch('add-calendar-events', ...) (or update- or remove-) from anywhere on the page, a listener you put on window or document in a script, and CSS aimed at the old markup. Search your code for -calendar-events, calendar- and ec-.

Props

Old Now
periods="['month', 'week', 'day']" views. Passing periods throws.
modes="['calendar', 'timeline']" Removed. There is no timeline, resource or list view. Passing modes throws.
name Still a prop, but it only keys the ids inside the calendar. It no longer picks which calendar an event is for.
First day of the week was Sunday week-start defaults to monday: pass week-start="sunday" to keep Sunday.
A day grew to fit its items A day shows max rows (3) and "+N more". :max="false" for the old behaviour.
Every click and drag selected selectable is off by default. Add it to keep creating. Drag and resize stay on.
x-model="date" (an ISO instant) wire:model="date" (Y-m-d), or none. Passing x-model throws. A property that still holds an ISO instant (2026-10-09T10:00:00.000Z) is not a date the calendar reads: it shows today, with no error. The anchor takes Y-m-d or Y-m, or a DateTimeInterface, which a Carbon-typed property is (read as the viewer's date).
Offset-less strings were read, and everything drawn, in the browser's timezone An offset-less string is read in config('app.timezone'), and everything is drawn in the viewer's timezone, Carbon::getLocalTimezone() (the signed-in user's timezone, else TIMEZONE in the environment, else Asia/Kuala_Lumpur), whatever the browser says. A host with neither a timezone on its users nor TIMEZONE set shows everyone Kuala Lumpur time: set one. With config cached, TIMEZONE has to be a real environment variable of the server, since a value that is only in .env is null then. See Dates and timezones.
CSS aimed at .ec-* classes, --ec-* variables or [&_.ec-event] utilities on the tag No longer applies: none of that markup exists. The look comes from the color presets, config('atom.calendar.colors') and the --atom-calendar-* variables above; delete the old rules.

Getting items in. The add-calendar-events, update-calendar-events and remove-calendar-events window events are gone, and so is the calendar-changed event that told you to fetch. The calendar asks your items closure for the window on every render, and a normal re-render after you save is the update, so a #[Renderless] fetch method and the events around it can be deleted. A host that fetched in calendar-changed replaces that with the closure and the overlap query in the Quick start.

Item fields

Old Now
start_at, end_at start, end (an end that is a date is the last day, included)
all_day all_day
bg_color, background_color color: a preset name or a hex colour. An item with none is zinc: the old default was a dark zinc-600 fill in a Tailwind v4 host (red-800 only where a Tailwind v3 build applied the wrapper's [&_.ec-event]:bg-red-800), the new one is the lighter zinc preset chip, a pale tint with a zinc edge and neutral text.
draggable, resizable draggable, resizable
text_color, class, style, meta, editable, resources Removed. Text is always neutral; look the record up by id from the event.
New: icon, danger, href

Events. The old events carried { info, mode, period, calendar }, with JavaScript dates and startUtc strings in info. The new ones carry the details above, as wall-clock strings, and the calendar object is not exposed.

Old Now
calendar-date-clicked, calendar-date-selected calendar-select (a click is a one-day select; needs selectable)
calendar-event-clicked calendar-item-click
calendar-event-dropped calendar-item-move
calendar-event-resized calendar-item-resize
calendar-changed, calendar-mounted Removed

An x-on: or @ listener for any of the old events, on the tag, throws and names its replacement; one on window, document or a wrapping element is not on the tag, so it is silent: search for it.

Every date in an event goes through Calendar::fromLocal() where an info.startUtc was used before; see Dates and timezones. The is-loading class a host could bind is not needed: the toolbar shows its own spinner while it waits for a window.


The AsEditorContent cast

Use this when you want a column to behave as Tiptap rich-text content with automatic image persistence:

What it does on save:

  1. Scans the HTML for Livewire temporary preview URLs (/livewire-{hash}/preview-file/...).
  2. Resizes each via Intervention Image (max width 1000, quality 80).
  3. Persists to Storage::disk(env('FILESYSTEM_DISK')) under <configured folder>/editor/.
  4. Rewrites the URLs back into the HTML, serializes the result.

get() lazily unserialize()s, falling back to the raw value if it isn't serialized.

Pair with the scheduled command to clean up images no longer referenced:

A file counts as referenced when its file name (or its percent-encoded form) appears anywhere in a stored editor value, whatever the format around it. The scan splits each form of a value (raw, decoded, percent-decoded) into tokens once, so its cost still follows the size of your data, not the number of files, and it prints a progress line every 1000 rows. A file whose name holds a space, quote, bracket or non-ASCII character (a macOS Screenshot ... .png stored through tiptapStoreImage(), say) is searched for as a plain substring instead, which is slower when there are many such files.

A file that any migration backup (see below) names, restored or not, is kept until the backups are pruned: --restore would otherwise bring back a row whose image the purge had deleted, and the live rows are read before the backups, so a restore that lands in between must not lose its image. The backup tables of every connection a discovered model uses (and the default one) are read, whether or not that model has an editor column today; one that cannot be reached stops the run, except a model with no editor column on a connection this config does not define: that cannot hold backups this config wrote, so it is warned about and skipped.

Moving a column to Tiptap JSON: atom:tiptap-migrate

Rows written by the AsEditorContent cast are serialize()d HTML (or serialize()d JSON, when the field was <atom:editor>). v4 removes that cast, so move the rows to JSON on 3.x first. Switch the cast from AsEditorContent to AsTiptapContent first (nothing is converted by that: AsTiptapContent reads the same rows), change the column to longText (the JSON is about 3.5 times the HTML, and a MySQL TEXT holds 65,535 bytes: the command refuses a row whose JSON would not fit, and says so), and fix anything that prints the column raw before you run --force: once a row is JSON, {!! $model->body !!}, x-html, strip_tags($model->body) and a mail or PDF template that echoes it print JSON. Print it through <atom:tiptap.content> or Content::render(). Then move the rows when you are ready. Run it with the app's own database connection settings: a connection charset that differs from the column's can mangle what is read, and the command backs up what it read.

You can run the command before switching the cast, but do not plan on it: on 3.x a column still cast as AsEditorContent is migrated like any other (the command writes through the query builder, never through a cast, and --force warns about the raw-printing risk above when one is in scope), and AsEditorContent hands the stored JSON back as the string it is, which the editor and Content::render() read. What it cannot do is stay migrated: AsEditorContent::set() serialize()s whatever it is given, so the next save through it writes serialize(<JSON>) again (the command reads that too, and converts it back on the next run, but that is a loop). Switch the cast first, then the rows stay JSON. --status lists the casts that are not yet switched.

A plain php artisan atom:tiptap-migrate is a dry run. Before the backups existed, a plain run wrote; a deploy script that ran it will silently stop migrating, and now needs --force. The command finds models the way the purge command does (app/Models, subdirectories included, plus --path=), reads every row with the query builder, and never loads a value as anything but a string.

The report. Each value is converted HTML to JSON and rendered back, and the two are compared on the visible text and on the tag and attribute inventory (a <b> that becomes <strong> is the same; a class, an inline style property, a <font>, a <script>, an event handler or an unknown tag the editor drops is a loss). A value is one of:

clean converts without losing anything. --force converts it.
flagged converts, but loses something. The dry run lists the row and what it would lose, and it is left untouched until --accept=<ids> (row ids, comma separated) or --accept=all.
refused cannot be converted safely: a serialized object or other non-string, JSON that is not a Tiptap document, the HTML parser's reserved placeholder, a value over the size or nesting limits, a parser failure. Named in the report and never written, --accept or not; fix it by hand.
already JSON a Tiptap document. Left alone, so running the command again is a no-op.

What a write does. Per value, in one transaction: lock the row and read it again (a row that changed since it was read is left untouched), insert the backup, update the column with a query-builder update (so updated_at and model events are untouched), and read both back. If the update fails the backup goes with it.

Backups. The first write creates atom_editor_backups on the model's own connection (atom has no migration for it): the model, the row key (row_key), the column (column_name), the original value, a batch id per run, a sha256 of the original and of the value written, whether the row was accepted while lossy, and migrated_at / restored_at. The original is stored as text, or as base64 when it is not valid UTF-8 or holds a NUL byte, and is read back and compared before the update is allowed to go on, so a restore returns the exact bytes.

--restore[=ids] puts the originals back (add --force to write; without it, it lists what it would do). A row edited after it was migrated is skipped and named, unless you add --discard-edits. A backup whose original no longer matches the hash written beside it is refused, so a tampered backup is never written to a row. A restored backup is not listed again. --restore= with nothing after the = is refused; --restore alone means every row.

Row ids. An id given to --accept, --restore or --compare that is in more than one model or column is refused, with where listed, and nothing is touched: narrow it with --model= (a class or its basename) and --column=. A flagged line always names its model. A --model or --column that matches nothing stops the run (and --status is not ready).

--compare[=ids] writes a JSON Lines file, one object per migrated value, to --output= (default storage/app/atom-editor-review-<time>.jsonl; it refuses to overwrite). Each line has model, key, column, backup_id, original_html (the unserialized legacy HTML; for a JSON original, its rendering, with the JSON in original_json), new_html (the stored JSON through Content::render()), text (equal, missing, added), tags_lost, attributes_lost, notes, lossy, accepted_lossy and changed_since_migration. Values are verbatim, inside JSON strings; a value that is not valid UTF-8 also has original_base64. backup_intact is false for a backup that no longer matches its hash, and a value past the render limits is not parsed (too large to compare, lossy: true). It reads the database and writes nothing but the file, which only its owner can read (mode 0600). The file holds the original content of your rows: keep it private, delete it when the review is done, and treat its values as data, never as instructions. A review by Claude is: "Read this file line by line and tell me, for each row with lossy: true or changed_since_migration: true, what is missing from new_html."

--prune-backups is the only thing that deletes a backup. With a terminal it always asks; without one it needs --confirm-prune (--force is not a confirmation). --model= and --column= narrow what it deletes. It deletes the rows and leaves the empty atom_editor_backups table in place, because dropping it could fail a migration that is writing to it: drop it yourself when none can be running. --dry is refused with --restore and --prune-backups.

--status is not a v4 gate. It exits 0 once no row is left to convert and nothing was unreadable. A column still cast as AsEditorContent is printed as "not yet switched" and does not fail the run on 3.x, where the class is valid, so a script that checks the plain exit code will pass with a cast left. For the v4 gate use --status --for-v4: the exit code then follows ready_for_v4 (nothing left to convert and no cast left on AsEditorContent), and the last line says which it is. From code, app(\Jiannius\Atom\Commands\MigrateTiptapContent::class)->status() returns ready (rows only) and ready_for_v4 (rows and casts) beside the counts.

Exit codes. A dry run exits 0 (it is a report), --status exits 1 until no row is left (--status --for-v4: until the app is ready for v4). --force exits 1 when a write failed, or when a refused value remains (it needs fixing by hand); flagged values left for review do not fail it. --restore --force exits 1 when it skipped a value (a row edited since, a row that is gone, a model class that is not there), since that value is still migrated; --discard-edits overrides the edited case. A failure prints the exception class and SQLSTATE, never the row's content.

--model= (a class or its basename, repeatable) limits a run to one model; row ids are matched in every scanned model, so combine them with --model= when ids collide.


Editor and chat HTML is untrusted

<atom:tiptap.chat> (the chat composer) hands the host HTML: tiptap.getHTML(), in an input event carrying { body, files }. Nothing checks it on the way in. A client that skips the editor and calls $wire.submit(...) (or sets the bound property) with its own string stores whatever it likes, and stored and printed as-is that is stored XSS. atom can't see your storage code, so the rule for a host that keeps chat HTML is:

This is for HTML, not for the JSON editor. <atom:tiptap> (and the AsTiptapContent cast) store Tiptap JSON, and sanitize() returns HTML. Don't pass JSON editor content through it before storing: that would turn the column into HTML and drop YouTube embeds. JSON is already printed safely by <atom:tiptap.content> / Content::render(), so store it as JSON and print it through those.

Rows stored before you adopt sanitize() stay unclean. sanitize() only cleans what passes through it from now on. A chat message already in your table keeps whatever it was saved with until you render it through <atom:tiptap.content> / Content::render() (which cleans on the way out, so old rows print safely), or backfill the column by running each row through Content::sanitize(). A host that prints stored HTML with x-html is exposed to every unclean row it already holds.

Content::sanitize(mixed $html, int $maxBytes = 131072, int $maxTags = 5000): string parses the value through the same schema and the same hardened extensions as render(), and returns the schema's own serialisation, so nothing of the input's markup survives except what the editor itself can write. It also accepts a Tiptap JSON document (a string or array with a type key) and a Stringable; any other string, '42' and 'null' included, is text (printed in a paragraph, like any loose top-level text).

It returns '' when the input is empty, when it is refused, and when it fails. It refuses (silently, so a client can't flood your logs) HTML over $maxBytes, HTML with more than $maxTags tags (or a document with more than $maxTags nodes and marks), input whose output would have more than $maxTags tags (a document prints up to four tags per node, and an empty table is one node), a document that is not a Tiptap document, a document nested more than 200 levels, HTML that carries tiptap-php's reserved MINIFYHTML placeholder, and the <pre> inputs the parser can't survive (below). Output over four times $maxBytes is refused too, so a small $maxBytes also caps the output at four times that. Only an unexpected failure is reported through Laravel's report(). Content::sanitizeRefuses($html) tells a refusal from an empty message.

The limits exist because parsing cost tracks the tag count, not the byte count: about 3 KB of memory per tag or document node in the worst case, so an input of 65,000 <p>a (260 KB) needs over 200 MB, and 95,000 {"type":"paragraph"} nodes (2 MB of JSON) needs about 290 MB. Measured at the sanitize defaults, the worst shape costs about 16 MB and 0.2 s; a long chat message is a few KB and a few dozen tags. Raise the limits only for a field that holds long documents. The parser also has inputs it takes minutes on or crashes on, which are normalised where real content could have them and refused only where it can't:

Kept (as the editor writes it) Dropped
Paragraphs, headings, lists, blockquotes, code blocks, line breaks, rules, tables <script>, <style>, <svg>, <form>, <object>, <embed>, <link>, <meta>, <base>, comments, CDATA and any tag the editor has no node for
Bold, italic, strike, underline, code, sub/superscript Every event handler (onclick, onerror, ...) and every attribute the schema doesn't define, id and srcdoc included
Links to http, https, mailto, tel (and the other protocols Tiptap allows, such as ftp and sms) and relative URLs, with atom's own target / rel Links whose href is javascript:, vbscript:, data: or another scheme (the text stays, the link goes); a link's own class, rel or target
Images with an http(s), relative or raster data:image/ source An image whose source is javascript:, data:image/svg+xml or another scheme (the whole image goes)
color, background-color, font-size, text-align, image width / float / align when the value passes the allow-list style declarations that fail it (position, url(...), expression(...), out-of-range sizes), and every class except mention, a font-size preset and language-*
Mentions (<span class="mention" data-type="mention" data-id data-label>), escaped The data-mention-suggestion-char marker the JS adds
YouTube embeds in a JSON document, rebuilt from the video id Any <iframe> in HTML input, and any iframe that isn't YouTube
Text that looks like markup (&lt;script&gt;), as escaped text Invalid UTF-8 (scrubbed, the text around it kept)

Two things it does not do:

Upgrading: render() and <atom:tiptap.content> refuse what they can't parse safely

Content::render() (and so <atom:tiptap.content>) reads stored content, and it now renders empty, and logs a warning, for stored content that is over its limits, has a <pre> block or count of <pre> tags the parser can't survive (see above; long whitespace runs and unclosed <pre> tags are normalised, not refused), carries the minifier's placeholder token (MINIFYHTML), or is not a Tiptap document. Nothing is reported through report(). The warning (Log::warning, once per value per process) carries the reason, the size and the limits, so check your log after upgrading if a page that used to show content is blank.

The defaults are 2 MB and 20,000 tags (HTML tags, or nodes and marks of a JSON document; worst case about 64 MB of memory for HTML and up to about 82 MB for a JSON document). Raise or lower them for your app in config/atom.php:

Memory grows with the tag limit (about 3 KB per tag or node), so raising render_max_tags needs a matching increase in PHP's memory_limit: at the defaults a page that renders one such document can peak near 64 MB (HTML) or 82 MB (JSON) above baseline, and doubling the limit roughly doubles that.

A long legitimate document (a 1,000-row price table, a 3,000-paragraph article) is within the defaults. A value that is not a Tiptap document at all (one only a hostile client can send) renders empty without a warning.


Actions

Named PHP classes you can invoke from PHP or, if they opt in, from the browser.

Resolution order:

  1. App\Actions\{Name} (host app — wins).
  2. Jiannius\Atom\Actions\{Name} (package fallback).

From PHP

Any action, any public method:

From the browser

Atom mounts POST /atom/action/{name} and the front-end exposes window.atom.action(name, params). That endpoint is public — no auth, reachable by anyone who can load the app — so it only runs actions that opt in by implementing Jiannius\Atom\Contracts\WebAction:

The endpoint:

Gating who may call it

Declare authorize() on the action. The endpoint calls it before handle() and answers 403 when it returns false:

Actions without authorize() are callable by anyone, including guests — which is right for something like GetOptions (country and dial-code lists on public forms) and wrong for almost everything else. An action inheriting from an opted-in parent inherits the contract.

Upgrading to 3.38.0

What a host that does nothing will notice:

Upgrading to 3.37.2

Content::sanitize() and Content::render() now print the same thing on every libxml, bar the malformed-HTML cases listed below. PHP on Ubuntu 22.04 and 24.04 and the Debian php images is built against libxml 2.9; a newer build (2.14 and later, as in most local setups) reads some HTML differently, and on 2.9 a few inputs made tiptap-php throw (a report() on every call, for input anyone can send). Content that comes from the editor or the chat composer is not affected. This release also contains a security fix in sanitize() and render(); upgrade soon if either handles input from users. Output cached or stored by them before the upgrade is not repaired.

Upgrading to 3.34.4

This is a security fix. Upgrade soon if any label, badge colour or embed icon in your app can come from a user or the database. Component labels were printed as HTML, so a label built from user-entered text (<atom:badge :label="$contact->name">) could run script in the page. A badge color that only started with # was written into the style attribute, so it could add CSS declarations.

Upgrading to 3.29.14

This is a security fix for stored Tiptap JSON documents. Upgrade soon if any user can write to an AsTiptapContent column, to an <atom:tiptap> field, or to anything you pass to Content::sanitize() or Content::render() as JSON.

A client that can save a JSON document could get markup of its choosing into what Content::render(), <atom:tiptap.content> and Content::sanitize() print (stored XSS). The cause is in tiptap-php: a zero in a node's attributes (an int 0, or a float that is zero such as 0.0) makes its serialiser print the node's other string attributes as raw tags instead of escaped attribute values. Two shapes were exploitable: an image whose alt, title or height was zero, and a mention whose id was zero; and a table cell (tableCell or tableHeader) whose colspan or rowspan was zero and whose colwidth held a string. From 3.29.14 a zero in any node or mark attribute is turned into the string "0", which prints the same inside an attribute, before the document reaches the serialiser.

If you only ever stored chat HTML, or JSON through AsTiptapContent, skip it. Do not pass JSON through sanitize() from now on either (see the section above); it is for HTML.

Upgrading to 3.29.13

A URL handed to an atom component used to be printed into an href (or navigated to) as it came. {{ }} escapes the HTML, but a javascript: URL still runs when clicked, so a host that passed a user-supplied URL (a profile "website", a link from a CMS) let that user run script in a visitor's browser. Atom now checks the URL first, with safe_url() in PHP and atom.safeUrl() in JS.

Allowed: http, https, mailto, tel, sms, and any URL with no scheme (/path, path, //host/path, #anchor, ?query). Anything else (javascript:, vbscript:, data:, blob:, file:, and versions hidden with upper case, HTML entities, tabs, newlines or leading control characters) is dropped: the link renders without an href, a button or row does not navigate, and a toast or lightbox does not open it. It covers <atom:link>, <atom:button>, <atom:tabs> / <atom:tabs.item>, <atom:menu.item>, <atom:list.item>, <atom:command.item> (and Enter in the palette), <atom:navlist.item>, <atom:table.row>, the <atom:logo> link, the breadcrumbs trail and its back action, toast url / navigate, the lightbox download, and the call-to-action button in the generic mail template (atom()->mail(cta: ...)), which is left out when its URL is blocked.

Upgrading to 3.29.12

<atom:sharer> printed title and url, and <atom:embed> printed an image src, into HTML attributes without escaping, so a value containing a quote could add attributes to the element; <atom:error :errors="..."> printed each message as HTML. They are escaped now. <atom:embed> also refuses a src whose scheme is not http or https (relative and protocol-relative URLs still work) and shows the file icon instead.

Upgrading to 3.29.9

Remote and static select options used to be turned into HTML without escaping label, caption or color, so a value a user typed (a contact name, say) rendered as markup. They are escaped now, including the native select's <option> text.

Upgrading to 3.25

3.25 makes the trait's action() helper protected. It was public, and Livewire exposes every public method a component declares — a trait method included, because reflection reports the using class as the declaring class. So on every component using AtomComponent, in every app:

reached any App\Actions\* class and any method on it, with no WebAction contract, no authorize(), and no allowlist. That is the hole 3.19 closed on POST /atom/action, standing open through Livewire the whole time. On a guest-facing page it was reachable without signing in.

What breaks: JS that calls the helper on the wire proxy. Find it with both spellings — Livewire proxies an exposed method under its own name, so the obvious grep misses most of it:

Migration, per hit: move the call to the public route, which has been the gated path since 3.19 — window.atom.action(name, params) — and opt the action in with implements \Jiannius\Atom\Contracts\WebAction plus an authorize(). See From the browser. If the call passed method, split that method into its own action; the route ignores method.

What does not change: server-side $this->action(...) inside a component, and atom()->action(...) from anywhere. Both still reach any action and any method — being protected only closes the browser door.

Upgrading to 3.20

3.20 closes three holes in GetOptions, the one action the package ships web-callable without authentication. All three were reachable by an anonymous caller:

What you must do, in every app with its own App\Actions\GetOptions: declare each option set in $auth (needs a signed-in caller) or $guest (readable by anyone). Undeclared sets return [] — the select goes empty — and log a warning naming the set. See GetOptions above.

Assume $auth unless you can say why a stranger may read every row. Sets like contacts, users, documents or taxes were guest-readable before this release; declaring them $guest keeps them that way.

$auth gates who is signed in, not which rows they get. Scope the queries too.

Upgrading to 3.19

Before 3.19 the endpoint ran any class in App\Actions\ — unauthenticated, and with the caller choosing which public method to invoke. It is now closed by default, so any action your JS calls goes dark until you opt it in.

  1. Find them: grep -rn "atom.action(" resources/ (and any .js outside resources/). Each name maps to a class — Foo.Bar → App\Actions\Foo\Bar.
  2. For each, add implements \Jiannius\Atom\Contracts\WebAction. Nothing else changes.
  3. While you are in each file, decide whether it should have been public at all. Add authorize() to anything that reads or writes user data — before 3.19 it had no gate, so assume none of them do.
  4. If you have your own App\Actions\GetOptions, make it extends \Jiannius\Atom\Actions\GetOptions — otherwise it shadows the package class without the contract and every remote-option select (<atom:select options="users">) in the app 404s.
  5. If any JS passed method in the params, split that method into its own action — the endpoint ignores method now.
  6. Check the app's CLAUDE.md/AGENTS.md. Atom's guidelines are copied into it rather than read from vendor/, and Boost rewrites that file on composer update — so the new rules arrive on their own, but any hand-edits you made to the atom section are overwritten at the same time. Re-apply them, or keep them outside that section.

Anything you do not opt in stays fully callable from PHP; only the browser path is affected.

If you miss one, the log says so. A refused action that exists writes a warning naming the class and the endpoint:

Requests for actions that don't exist stay silent, so this doesn't turn into noise from probing.

GetOptions: shared option lists

Jiannius\Atom\Actions\GetOptions loads option arrays from JSON files. It merges:

with the app-side values taking precedence. Results are cached under _options.

Built-in JSON sets: countries, postcodes, colors. Override any of them by creating resources/json/colors.json in your host app.

To serve options from your database instead, create App\Actions\GetOptions extending the package class (it shadows it, and extending is what carries the WebAction contract that remote-option selects need). Each option set needs two things: a camelCase method, and its name declared in $auth or $guest.

Reach it by passing the set name as a string on options — that is what makes the select fetch rather than render a static list:

:options="[...]" (an array) is a static list; name is the field name and never selects an option set.

Why the declaration: the option name arrives in the request body, and it used to be turned straight into a method call. Anything zero-arg on your subclass was reachable from a browser, authenticated or not. Now the name only selects among the sets you listed, and a name in neither list returns an empty array.

The package's own sets (countries, states, dialcodes, currencies, colors, postcodes) are always readable — guest address and phone forms need them — and you don't re-declare them.

$auth is a coarse gate: signed in or not. It does not scope rows. A signed-in user of tenant A calling a set that returns every tenant's rows still gets every tenant's rows, so scope the query itself as well.

Option text is escaped; the html key is trusted

The listbox renders each option's markup with x-html. An option is a value plus a label, and optionally caption, avatar and color. Atom builds the markup from those fields and escapes every one of them, both on the server (GetOptions::getOptionHtml()) and in the client-side fallback (select.js). A contact name a user typed renders as text, whatever it contains. Return the raw text in label and caption; don't pre-escape it, or it is escaped twice. color is checked as well as escaped: only #hex, rgb()/rgba(), hsl()/hsla() or a plain colour name draws a swatch, and anything else (red; position: fixed) draws none.

An option may instead carry its own html (and selected_html, the version shown in the closed trigger). That key is the escape hatch for a custom layout, and it is trusted: atom passes it to the browser untouched, so you own escaping it. Wrap every user or database value you put in it with e():

An unescaped field in html is a stored XSS for everyone who opens that select. Keep label plain even when html is set: the label is what search filters on and what the chips show.

The native variant prints label into <option>, and escapes it.


Translation

t('Some string', $countOrParams, $params) is the translation shim. Almost every UI string in components passes through it, so to translate your app you just drop standard Laravel translation files under lang/{locale}/.


Front-end JS API

resources/js/atom.js is built to dist/ and served by the package; it boots automatically when <atom:html> renders. It exposes:


Conventions worth knowing


Preparing for v4

v4 is a breaking release (a restyle onto design tokens, AtomComponent split into traits, the Date facade swap and the prototype helpers removed, AsEditorContent and <atom:editor*> deleted). Prepare on 3.x, where each step is reversible.

  1. See the size of it. php artisan atom:upgrade-check reads the app (app/, resources/, routes/, modules/, config/, database/ and tests/, which it reports apart) and writes nothing. It lists every break the v4 upgrade guide describes (UPGRADE.md is on the v4 branch: https://github.com/jiannius/atom/blob/v4/UPGRADE.md), by check, with file:line and counts, how bad each is (breaks at runtime, visual change or review) and whether the atom:upgrade codemod that ships with v4 will fix it (auto) or only report it. It also prints:

    • for each component that uses AtomComponent, the traits it needs (WithTable, WithBreadcrumbs, WithEditor, WithRecaptcha, plus WithPagination and WithFileUploads), read from its view, the partials the view includes and its methods;
    • the <atom:...> tags in use, counted per name, with the section of UPGRADE.md that restyled each (the list to pilot v4 against);
    • the JS sites (prototype helpers, bare empty( and dd(), the AsEditorContent casts and <atom:editor*> tags;
    • whether the atom section of your CLAUDE.md / AGENTS.md still matches what the installed version renders (in sync, diverged with a short summary of what differs, or not found); refresh it with php artisan boost:install.

    --json prints the same result as JSON (what the codemod and other tooling read), --all lists every finding (the report shows the first 10 of each check), --output=path also writes what is printed to a file (the only thing the command ever writes) and --path= scans another directory. The report and --output quote up to 160 characters of each matching line, so treat the file like source code. It does not follow symlinks, says which directories it could not read and which files it skipped (over 2 MB, or minified), and lists published atom views (resources/views/vendor/atom/) as a section of their own: re-diff those against v4. With Date::use(...) already in a service provider, the date findings drop to review. A finding is a candidate from a text scan, not a proof: ->local( on something that is not a date counts, and a recent() query scope matches ->recent(.

  2. Move the editor columns to JSON. Switch each AsEditorContent cast to AsTiptapContent, change the column to longText, then php artisan atom:tiptap-migrate (dry run), --force, --compare, --prune-backups; --status --for-v4 exits 0 when no row is left and no cast is on AsEditorContent (plain --status is not a v4 gate). See "Moving a column to Tiptap JSON" above. Do this before you require v4: the class is gone there, Laravel ignores a cast it cannot resolve, and the attribute silently reads as the raw serialize()d string.

Artisan commands

Command Purpose
atom:purge-editor-images Walks App\Models\*, finds columns cast as AsEditorContent or AsTiptapContent, and moves any unreferenced editor image to editor-purged/ on the local disk before removing from the configured disk. A file is referenced if its name appears anywhere in a stored value or in a migration backup.
atom:purge-editor-images --dry-run Lists what it would delete and changes nothing.
atom:purge-editor-images --force Empties the editor-purged/ backup folder.
atom:upgrade-check [--json] [--all] [--output=path] [--path=dir] Read only: lists what moving to atom 4 will break or change (file:line, counts, severity, codemod verdict), the traits each AtomComponent user needs, the atom tags in use, and whether the atom section of CLAUDE.md / AGENTS.md is in sync. See "Preparing for v4".
atom:tiptap-migrate Dry run: classifies every editor value as clean, flagged, refused or already JSON, and writes nothing.
atom:tiptap-migrate --force [--accept=ids\|all] Backs up and converts the clean rows (and the flagged ones named in --accept).
atom:tiptap-migrate --restore[=ids] [--force] [--discard-edits] Puts originals back byte for byte.
atom:tiptap-migrate --compare[=ids] [--output=path] Writes a JSON Lines review file of the migrated rows.
atom:tiptap-migrate --prune-backups Deletes the backups (asks first; --confirm-prune without a terminal).
atom:tiptap-migrate --status [--for-v4] Says what is left to migrate; exit 1 until no row is. A cast still on AsEditorContent is listed, not failed, unless --for-v4 asks for the v4 gate.

License

MIT. See LICENSE.md.


All versions of atom with dependencies

PHP Build Version
Package Version
Requires php Version ^8.3
illuminate/support Version ^13.0
intervention/image Version ^3.0
league/commonmark Version ^2.8.1
livewire/livewire Version ^4.0
ueberdosis/tiptap-php Version ^2.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package jiannius/atom contains the following files

Loading the files please wait ...