Reference Image Bundle Laravel Package

Getting Started

This is the initial 1.0.0 release of a reference image bundle for Unite-CMS. It ships sample/reference media assets rather than application logic, so there is no service provider API to learn — the work is in wiring the bundle into your CMS install and your local seed data.

Minimal steps:

1. Require the package via Composer alongside your Unite-CMS install (composer require <vendor>/<package>), then commit the lockfile.
2. Publish the bundle's assets/manifest so the images land in a path your CMS media storage actually reads (typically public/ or your configured disk, not vendor/).
3. Confirm the files are reachable through the CMS media model/config — a bundle that publishes to the wrong disk fails silently later, at render time.
4. Run the package's installer or seeder to register the reference records, then load the CMS admin media library and verify thumbnails generate.

Where to look first: the package README and the publishable config/manifest, since that is where the mapping between bundled asset names and CMS media records is defined. Check the composer.json for the Laravel/Unite-CMS version constraints before anything else — a first release pins tightly.

First use case: seeding a fresh local or staging environment with a predictable set of images so demos, front-end work, and visual regression tests don't depend on content editors. Do not ship the reference bundle to production as real content.

Implementation Patterns

• Local/staging seeding only. Register the bundle's seeder in DatabaseSeeder behind an environment check, or in a dedicated ReferenceImageSeeder. Keep it out of production seeding paths entirely.
• Fixtures for tests. Use the bundle as a stable asset fixture set: seed once in a base TestCase and assert media transformations against known dimensions. This is the strongest day-to-day value of a reference bundle — deterministic images for resize/crop/WebP conversion tests.
• Demo environments. Pair with an .env flag (e.g. SEED_REFERENCE_IMAGES=true) so the same codebase can seed a client demo without touching the default seed path.
• Storage disk abstraction. Publish to a named disk from config rather than hardcoding public. This lets the same seeder target local disk in dev and S3 in a staging sandbox.
• Idempotent seeding. Wrap registration in updateOrCreate keyed on filename or a stable slug so repeated migrate:fresh --seed runs don't duplicate media records.
• CI asset cache. Because the bundle ships fixed binaries, it makes a good warm-up artifact — seed once per pipeline and reuse the storage directory across jobs rather than re-publishing per test shard.

Gotchas and Tips

• It is not a media library. This package provides images, not upload handling, transformations, or storage logic. Those still come from Unite-CMS. Do not evaluate it as a feature package.
• .gitignore traps. Publishing assets into public/ is usually ignored by default; either commit the published output or, better, ensure the publish step runs in every deploy/build script.
• Re-publish overwrites. vendor:publish --force will clobber any locally edited or replaced reference images. Treat published assets as generated output and keep customisations elsewhere.
• Version pinning. The bundle is coupled to Unite-CMS's media model schema — a 1.0.0 image bundle carries no migration of its own, so a CMS upgrade that changes media fields can orphan records. Pin the pair and retest seeding after any CMS bump.
• Binary size in the repo. Reference bundles are usually large. Check the install footprint and whether the images live in the package archive or are fetched — the latter needs network access in CI and can fail intermittently.
• Licensing of the images. For a reference image bundle this is the first thing to verify, above any code concern: confirm the bundled assets are licensed for redistribution and for use in your test fixtures and demo environments.
• Debugging registration failures. If images publish but records don't appear, the cause is almost always a disk/path mismatch or a guard that skips seeding outside local. Log the resolved path from the config at seed time rather than guessing.