Omnia Ipsum Laravel Package

Getting Started

This is a Symfony-first package: it ships a Flex recipe, a bundle, and Twig functions. In a Laravel app none of that wiring is automatic, so treat it as a PHP library with a config array, not a drop-in Blade toolkit.

1. composer require <vendor>/omnia (check composer.json for a extra.laravel.providers entry — if absent, nothing is auto-registered).
2. Publish config: php artisan vendor:publish --tag=omnia-config (verify the tag; fall back to copying the package's config/*.yaml/*.php manually and loading it in a service provider).
3. Add environment values: GCS bucket + credentials for video, and any provider base URLs you intend to override.
4. Bind the package's provider/generator interfaces in AppServiceProvider (or a dedicated OmniaServiceProvider) so you can inject them rather than calling globals.

Where to look first: the configuration file (it enumerates every provider and generator and is the fastest map of the package's surface area), then the provider classes for images/audio to confirm the public method signatures. Ignore the Twig layer entirely — it is thin glue you will re-implement.

First use case: database seeders and demo fixtures. Replace https://picsum.photos/... strings scattered through factories with a single PlaceholderService call that returns a deterministic, seeded image URL per record. That is the highest-value, lowest-risk adoption path and it does not touch production rendering.

Implementation Patterns

Wrap everything in one application service. Create App\Support\Placeholder (or similar) with methods like image(), avatar(), video(), audio(), paragraphs(). Inject the package's generators into it. This gives you a Blade-facing API ({{ $placeholder->image($post->slug, 800, 600) }}), keeps Twig out of your codebase, and gives you one place to swap providers later.

Use the Picsum seed parameter for stable-per-record images. The single most useful feature in this release. Derive the seed from something immutable and environment-independent:

$seed = substr(md5($post->slug), 0, 8);
$url  = $placeholder->image(seed: $seed, width: 1200, height: 630);

The same post renders the same photo on every page load, in every environment, and across re-seeds.

Seeder and factory integration. Laravel already ships fakerphp/faker, so use the package's Faker formatters directly from your existing $this->faker instance for text, and reserve the package's providers for media URLs only. Keep factories returning MediaPlaceholder::image(...) objects/strings rather than hardcoded hosts so a future provider swap is one config change.

Consistent media sets for demo environments. For a "demo tenant" seeder, pull video from the GCS provider and audio from SoundHelix, and store the resolved URLs on the model (a media_url column) rather than resolving at render time. This keeps php artisan serve on a plane and in CI from depending on external hosts.

Test suite configuration. Point the audio provider at silence and (if you can) the image provider at a local fixture or a cached URL set in phpunit.xml / a testing config block. Assert on shape (URL contains the expected dimensions, seed, or provider host) rather than exact strings — the providers are third parties and URLs can change.

Blade integration tips. If you want ergonomics, register a Blade directive rather than a global helper:

Blade::directive('placeholder', fn ($expr) => "<?php echo app(\App\Support\Placeholder::class)->image($expr); ?>");

Avoid adding a root-namespace global function; see Gotchas.

Extension point. The provider abstraction is the real integration surface. Implement the package's image/audio interface with your own class (local disk fixtures, S3-backed samples, an internal CDN) and bind it in the container. This is the cleanest way to keep the package in require-dev while still using its interfaces and config shape.

Gotchas and Tips

fake() name collision. Laravel defines a global fake() helper. The package's fake() Twig function maps to something similar. If you pull package code into the global namespace or copy Twig globals into helpers, you will get a fatal redeclaration. Always fully qualify or wrap; never use function a package fake into a file that also calls Laravel's fake().

No Blade/Twig bridge. The 12 Twig functions are useless in Laravel as-is. There is no Blade directive registration in this release. Budget an hour for the wrapper service; do not expect omnia_image() to exist in a .blade.php file.

Twig/Symfony dependency weight. The package requires Symfony 6.4–8.x. Confirm it does not force a Symfony minor bump that conflicts with your Laravel version's constraints before composer require in a production app; run composer why-not if the install fails.

Hotlinking external providers in production. Picsum, Placehold.co, UI Avatars, and SoundHelix are third-party hosts. They rate-limit, change TLS/CDN behaviour, and return errors offline. Never ship these URLs to end users on a critical path — restrict them to seeded demo data, staging, and tests. For anything user-visible, download and store the asset, or proxy through your own route with a cache.

Deterministic seeds must not derive from auto-increment IDs. IDs differ between local, staging, and production after re-seeding, so your "same post, same image" guarantee silently breaks. Use slugs, UUIDs, or content hashes.

GCS video provider costs and credentials. Egress on video is the most expensive thing in this package by far. Use a dedicated bucket, a scoped service account, and prefer signed URLs with short TTLs over public objects. Store the service account JSON path in config/filesystems.php-adjacent config, not in a .env value you might accidentally dump. Also check the region — cross-region egress on demo videos adds up fast.

UI Avatars encoding. Pass names through urlencode; unicode names, +, and # will otherwise truncate the initials or break the URL. Confirm the provider's max-length behaviour before feeding it long company names.

Silence provider for CI. The SoundHelix default serves ~5-minute tracks; ten of them in a test suite is a lot of network. Set the audio provider to silence in phpunit.xml and any CI env file.

Config caching. After php artisan config:cache, any config read at render time from the package must go through config(), not env(). If the package reads $_ENV directly, wrap it. Test with config:cache enabled once before shipping.

Verify Laravel package discovery. Symfony Flex recipes do nothing here. If the package's composer.json lacks extra.laravel, you must register the service provider and alias manually in bootstrap/providers.php (Laravel 11+) or config/app.php.

Pin the version loosely but test the upgrade. This is 0.1.0 — pre-1.0, so expect provider lists, config keys, and the Twig function set to churn. Keep the wrapper service thin enough that a breaking change is a one-file fix, and add a smoke test that asserts each wrapper method returns a non-empty string.