Livewire Starter Kit Laravel Package

Getting Started

This is the ArtisanPack UI Laravel application skeleton (starter kit), not a drop-in library — you consume it via composer create-project (or laravel new with the ArtisanPack preset) and then work inside the generated app.

Minimum viable path:

composer create-project artisanpack-ui/laravel-app my-app
cd my-app
npm install && npm run build   # Vite 7
php artisan migrate
php artisan serve

Requirements before you start: PHP 8.3+ (8.4/8.5 are the tested targets) and Laravel 13 only. If you are on L12 or PHP 8.2, stay on the 1.0.3 line — v2.x does not carry the ^12.0|^13.0 range.

Where to look first, in order:

1. config/session.php — serialization now defaults to json via SESSION_SERIALIZATION. This is the single change most likely to bite an existing app.
2. config/cache.php — ships an empty serializable_classes allowlist matching L13's hardened deserialization default.
3. config/database.php — MySQL/MariaDB SSL handling with a PHP-version-aware constant.
4. app/Console/Commands (or the package vendor path) for artisanpack:optional-packages-command — this is your day-to‑day entry point for adding ArtisanPack UI packages.

First use case: run the optional-packages command immediately after scaffolding to pull in whichever ArtisanPack UI modules you actually need (ai, cms-framework, media-library, visual-editor, etc.) rather than hand-editing composer.json.

Implementation Patterns

Installing optional ArtisanPack UI packages. Run it manually any time:

php artisan artisanpack:optional-packages-command

In v2.0.0 the prompt covers the full current suite — ai, bing-places, bookings, cms-framework, google, google-business-profile, hooks, icons, media-library, security, visual-editor — grouped by category in each label, plus the code-style dev tooling. The command partitions dependency installs: artisanpack-ui/code-style and artisanpack-ui/code-style-pint go through a separate composer require --dev call so they never leak into production builds. If you are scripting your own scaffold, mirror that split rather than doing one flat composer require.

Non-interactive installs. Under laravel new the command now re-attaches to /dev/tty so the prompts still render even though --no-interaction was passed. When no terminal is reachable at all, it prints a "run this manually after install" notice and exits cleanly. Pattern: in CI or container builds, expect the notice and run the command in a later, interactive-ish step or pass explicit package names.

Session serialization rollout. Because the default flipped from php to json, existing session payloads become unreadable. Two workable patterns:

• Hard cutover: deploy during a low-traffic window, bump the session cookie name or flush the sessions table, accept that everyone re-authenticates.
• Soft migration: set SESSION_SERIALIZATION=php in the environment to pin the old behavior, ship the rest of the upgrade, then flip the env var in a follow-up deploy and flush sessions then.

Either way, drive it through the env var rather than editing the config file, so it's reversible without a code deploy.

Cache allowlist. The empty serializable_classes in config/cache.php is a deliberate hardened default. If you cache value objects, you must explicitly enumerate the classes you intend to unserialize. Pattern: keep a short, audited list in config and prefer caching scalars/arrays where you can.

Database SSL. config/database.php now prefers Pdo\Mysql::ATTR_SSL_CA when it exists (PHP 8.5+) and falls back to PDO::MYSQL_ATTR_SSL_CA on 8.3/8.4. You don't need to branch in your own code — just wire the CA path through MYSQL_ATTR_SSL_CA env vars as usual and let the shipped config resolve the constant.

Front-end integration. Vite ^7.0 plus laravel-vite-plugin ^2.0 means the standard @vite(['resources/css/app.css', 'resources/js/app.js']) directive is unchanged; the work is in your Node version and plugin API surface, not your Blade templates.

Testing. Pest 4 with pest-plugin-laravel ^4.0 and PHPUnit 12 are explicitly required and CI runs 8.3/8.4/8.5. Write tests as you normally would; just make sure your local PHP is not 8.2.

Gotchas and Tips

• Session data invalidation is the headline breaking change. Flipping serialization from php to json makes every existing session unreadable — users get logged out. Plan the rollout, and if you can't take the hit, pin SESSION_SERIALIZATION=php first.
• No L12 path in v2.x. The ^12.0|^13.0 range from 1.0.3 is gone. If any of your other dependencies still constrain laravel/framework to ^12.0, composer will deadlock. Resolve those first, or stay on 1.0.3.
• PHP 8.2 is dropped. Lint your CI matrix, your Docker base image, and your local Herd/Valet PHP version — a stale 8.2 container will fail at composer install, not at runtime.
• artisanpack-ui/security is a major bump (^2.1.0). Read its changelog before upgrading; a major on a security package is not something to skim.
• owenvoke/blade-fontawesome is no longer pulled in transitively via artisanpack-ui/livewire-ui-components. If your Blade views use those components directly, add the package back explicitly or switch to the ArtisanPack icons package.
• Empty serializable_classes is not a bug. If you get "unserialization of class not allowed" style errors after upgrading, add the class to that allowlist rather than removing the setting.
• /dev/tty probing is read+write fopen, not is_readable()/is_writable(). On Linux those functions return true even without a controlling terminal (the open then fails with ENXIO). This means: inside Docker, cron, or CI you will reliably get the "run this manually" notice — that's correct behavior, not a failure.
• A failed TTY re-attach exits cleanly now. It routes back through the skipping notice instead of leaking a non-zero shell status, so laravel new won't falsely report failure. Don't add error handling that assumes a non-zero exit means the install broke.
• PHP 8.5 deprecation noise. If you maintain your own DB config instead of using the shipped one, you'll still see the PDO::MYSQL_ATTR_SSL_CA deprecation. Copy the Pdo\Mysql::ATTR_SSL_CA-preferring pattern from config/database.php.
• Vite 7 needs a modern Node. Bump to Node 20.19+ or 22.12+ before npm install, or you'll get confusing plugin resolution errors from laravel-vite-plugin v2.
• Extension point worth knowing: the optional-packages command is the intended seam for adding ArtisanPack UI modules — prefer it over hand-editing composer.json, because it gets the dev/prod partitioning right for you.